Struct GoudGame 

pub struct GoudGame { /* private fields */ }

The main game instance managing the ECS world and game loop.

Example

use goud_engine::sdk::{GoudGame, GameConfig};
use goud_engine::sdk::components::Transform2D;
use goud_engine::core::math::Vec2;

let mut game = GoudGame::new(GameConfig::default()).unwrap();
let player = game.spawn()
    .with(Transform2D::from_position(Vec2::new(400.0, 300.0)))
    .build();

Implementations

impl GoudGame

pub fn ffi_entity_spawn_empty(&mut self) -> u64

Spawns a new empty entity with no components.

Returns the entity as a u64 bit representation for FFI compatibility.

pub unsafe fn ffi_entity_spawn_batch( &mut self, count: u32, out_entities: *mut u64, ) -> u32

Spawns multiple empty entities in a batch and writes their IDs to the provided output buffer.

Returns the number of entities spawned.

Safety

out_entities must point to valid memory with capacity for at least count u64 values.

pub fn ffi_entity_despawn(&mut self, entity_id: u64) -> bool

Despawns an entity and all its components from the world.

Returns true if the entity was despawned, false otherwise.

pub unsafe fn ffi_entity_despawn_batch( &mut self, entity_ids: *const u64, count: u32, ) -> u32

Despawns multiple entities in a batch.

Returns the number of entities successfully despawned.

Safety

entity_ids must point to valid memory with at least count u64 values.

pub fn ffi_entity_is_alive(&self, entity_id: u64) -> bool

Checks if an entity is currently alive in the world.

pub fn ffi_entity_count(&self) -> u32

Returns the total number of alive entities in the world.

pub unsafe fn ffi_entity_is_alive_batch( &self, entity_ids: *const u64, count: u32, out_results: *mut u8, ) -> u32

Checks if multiple entities are alive in the world.

Results are written to out_results where 1 = alive, 0 = dead. Returns the number of results written.

Safety

• entity_ids must point to valid memory with at least count u64 values.
• out_results must point to valid memory with at least count u8 values.

impl GoudGame

pub fn new(config: GameConfig) -> Result<GoudGame, GoudError>

Creates a new game instance with the given configuration.

This creates a headless game instance suitable for testing and non-graphical use. For a windowed game with rendering, use with_platform instead.

pub fn default_game() -> Result<GoudGame, GoudError>

Creates a game with default configuration.

pub fn with_platform(config: GameConfig) -> Result<GoudGame, GoudError>

Creates a windowed game instance with a GLFW platform backend.

This initializes a GLFW window with an OpenGL 3.3 Core context, sets up the sprite batch renderer, and prepares the asset server.

Errors

Returns an error if GLFW initialization or window creation fails.

pub fn world(&self) -> &World

Returns a reference to the default scene’s ECS world.

pub fn world_mut(&mut self) -> &mut World

Returns a mutable reference to the default scene’s ECS world.

pub fn spawn(&mut self) -> EntityBuilder<'_>

Creates an entity builder for fluent entity creation (default scene).

pub fn spawn_empty(&mut self) -> Entity

Spawns an empty entity with no components (default scene).

pub fn spawn_batch(&mut self, count: usize) -> Vec<Entity>

Spawns multiple empty entities at once (default scene).

pub fn despawn(&mut self, entity: Entity) -> bool

Despawns an entity and removes all its components (default scene).

pub fn get<T>(&self, entity: Entity) -> Option<&T>

where T: Component,

Gets a reference to a component on an entity (default scene).

pub fn get_mut<T>(&mut self, entity: Entity) -> Option<&mut T>

where T: Component,

Gets a mutable reference to a component on an entity (default scene).

pub fn insert<T>(&mut self, entity: Entity, component: T)

where T: Component,

Adds or replaces a component on an entity (default scene).

pub fn remove<T>(&mut self, entity: Entity) -> Option<T>

where T: Component,

Removes a component from an entity (default scene).

pub fn has<T>(&self, entity: Entity) -> bool

where T: Component,

Checks if an entity has a specific component (default scene).

pub fn entity_count(&self) -> usize

Returns the number of entities in the default scene.

pub fn is_alive(&self, entity: Entity) -> bool

Checks if an entity is alive (default scene).

pub fn create_scene(&mut self, name: &str) -> Result<u32, GoudError>

Creates a new scene with the given name.

pub fn destroy_scene(&mut self, id: u32) -> Result<(), GoudError>

Destroys a scene. Cannot destroy the default scene.

pub fn scene(&self, id: u32) -> Option<&World>

Returns a reference to a scene’s world.

pub fn scene_mut(&mut self, id: u32) -> Option<&mut World>

Returns a mutable reference to a scene’s world.

pub fn scene_by_name(&self, name: &str) -> Option<u32>

Looks up a scene by name.

pub fn set_scene_active( &mut self, id: u32, active: bool, ) -> Result<(), GoudError>

Sets whether a scene is active.

pub fn scene_manager(&self) -> &SceneManager

Returns a reference to the scene manager.

pub fn scene_manager_mut(&mut self) -> &mut SceneManager

Returns a mutable reference to the scene manager.

pub fn config(&self) -> &GameConfig

Returns the game configuration.

pub fn title(&self) -> &str

Returns the window title.

pub fn window_size(&self) -> (u32, u32)

Returns the window dimensions.

pub fn run<F>(&mut self, update: F)

where F: FnMut(&mut GameContext, &mut World),

Runs the game loop with the given update callback.

The callback receives the default scene’s world for backward compatibility. Use scene_manager_mut inside the callback for multi-scene access.

pub fn update_frame<F>(&mut self, delta_time: f32, update: F)

where F: FnMut(&mut GameContext, &mut World),

Runs a single frame update for all active scenes.

pub fn fps_stats(&self) -> FpsStats

Returns the current FPS statistics from the debug overlay.

pub fn set_fps_overlay_enabled(&mut self, enabled: bool)

Enables or disables the FPS stats overlay.

pub fn frame_count(&self) -> u64

Returns the current frame count.

pub fn total_time(&self) -> f32

Returns the total time elapsed since game start.

pub fn fps(&self) -> f32

Returns the current FPS.

pub fn is_initialized(&self) -> bool

Returns true if the game has been initialized.

pub fn from_engine_config(config: EngineConfig) -> Result<GoudGame, GoudError>

Creates a headless game from an EngineConfig builder.

pub fn from_engine_config_with_platform( config: EngineConfig, ) -> Result<GoudGame, GoudError>

Creates a windowed game from an EngineConfig builder.

pub fn providers(&self) -> &ProviderRegistry

Returns a reference to the provider registry.

impl GoudGame

pub fn is_key_pressed(&self, key: Key) -> bool

Returns true if the given key is currently held down.

Example

if game.is_key_pressed(Key::W) {
    // Move forward continuously while held
}

pub fn is_key_just_pressed(&self, key: Key) -> bool

Returns true if the given key was pressed this frame (not held from previous frame).

Use this for one-shot actions like jumping or menu selection.

pub fn is_key_just_released(&self, key: Key) -> bool

Returns true if the given key was released this frame.

pub fn is_mouse_button_pressed(&self, button: MouseButton) -> bool

Returns true if the given mouse button is currently held down.

pub fn is_mouse_button_just_pressed(&self, button: MouseButton) -> bool

Returns true if the given mouse button was pressed this frame.

pub fn is_mouse_button_just_released(&self, button: MouseButton) -> bool

Returns true if the given mouse button was released this frame.

pub fn mouse_position(&self) -> (f32, f32)

Returns the current mouse position in window coordinates.

Returns (x, y) where (0, 0) is the top-left corner.

pub fn mouse_delta(&self) -> (f32, f32)

Returns the mouse movement delta since the last frame.

Returns (dx, dy) where positive X is right and positive Y is down.

pub fn scroll_delta(&self) -> (f32, f32)

Returns the scroll wheel delta since the last frame.

Returns (horizontal, vertical) scroll amounts.

pub fn map_action_key(&mut self, action: &str, key: Key)

Maps a key to a named action.

An action can have multiple key bindings. When any bound key is pressed, the action is considered active.

Example

game.map_action_key("Jump", Key::Space);
game.map_action_key("Jump", Key::W);

if game.is_action_pressed("Jump") {
    // Triggered by Space OR W
}

pub fn map_action_mouse_button(&mut self, action: &str, button: MouseButton)

Maps a mouse button to a named action.

pub fn is_action_pressed(&self, action: &str) -> bool

Returns true if any binding for the named action is currently held.

pub fn is_action_just_pressed(&self, action: &str) -> bool

Returns true if any binding for the named action was pressed this frame.

pub fn is_action_just_released(&self, action: &str) -> bool

Returns true if any binding for the named action was released this frame.

pub fn input(&self) -> &InputManager

Returns a reference to the underlying InputManager.

Use this for advanced input queries (gamepad, input buffering, etc.) that are not exposed through convenience methods.

pub fn input_mut(&mut self) -> &mut InputManager

Returns a mutable reference to the underlying InputManager.

Use this for advanced configuration (deadzone, buffer duration, etc.).

impl GoudGame

pub fn begin_2d_render(&mut self) -> Result<(), GoudError>

Begins a 2D rendering pass.

Call this before drawing sprites. Must be paired with end_2d_render.

pub fn end_2d_render(&mut self) -> Result<(), GoudError>

Ends the 2D rendering pass and submits batched draw calls to the GPU.

pub fn draw_sprites(&mut self) -> Result<(), GoudError>

Draws all entities with Sprite + Transform2D components.

pub fn render_2d_stats(&self) -> (usize, usize, f32)

Returns 2D rendering statistics: (sprite_count, batch_count, batch_ratio).

pub fn has_2d_renderer(&self) -> bool

Returns true if a 2D renderer (SpriteBatch) is initialized.

impl GoudGame

pub fn begin_render(&mut self) -> bool

Begins a new rendering frame. Call before any drawing operations.

pub fn end_render(&mut self) -> bool

Ends the current rendering frame.

pub fn set_viewport(&mut self, x: i32, y: i32, width: u32, height: u32)

Sets the viewport rectangle for rendering.

pub fn enable_blending(&mut self)

Enables alpha blending for transparent sprites.

pub fn disable_blending(&mut self)

Disables alpha blending.

pub fn enable_depth_test(&mut self)

Enables depth testing.

pub fn disable_depth_test(&mut self)

Disables depth testing.

pub fn clear_depth(&mut self)

Clears the depth buffer.

pub fn draw_sprite( &mut self, texture: u64, x: f32, y: f32, width: f32, height: f32, rotation: f32, r: f32, g: f32, b: f32, a: f32, ) -> bool

Draws a textured sprite at the given position (immediate mode).

pub fn draw_sprite_rect( &mut self, texture: u64, x: f32, y: f32, width: f32, height: f32, rotation: f32, src_x: f32, src_y: f32, src_w: f32, src_h: f32, r: f32, g: f32, b: f32, a: f32, ) -> bool

Draws a textured sprite with a source rectangle for sprite sheet animation.

pub fn draw_quad( &mut self, x: f32, y: f32, width: f32, height: f32, r: f32, g: f32, b: f32, a: f32, ) -> bool

Draws a colored quad (no texture) at the given position.

pub unsafe fn get_render_stats(&self, out_stats: *mut GoudRenderStats) -> bool

Gets rendering statistics for the current frame.

Writes default statistics to the provided out-pointer. Returns true on success, false if the pointer is null.

Safety

out_stats must be a valid, aligned, writable pointer to a GoudRenderStats value, or null (in which case this returns false).

impl GoudGame

pub fn create_primitive(&mut self, info: PrimitiveCreateInfo) -> u32

Creates a 3D primitive and returns its object ID.

pub fn create_cube( &mut self, texture_id: u32, width: f32, height: f32, depth: f32, ) -> u32

Creates a 3D cube and returns its object ID.

pub fn create_plane(&mut self, texture_id: u32, width: f32, depth: f32) -> u32

Creates a 3D plane and returns its object ID.

pub fn create_sphere( &mut self, texture_id: u32, diameter: f32, segments: u32, ) -> u32

Creates a 3D sphere and returns its object ID.

pub fn create_cylinder( &mut self, texture_id: u32, radius: f32, height: f32, segments: u32, ) -> u32

Creates a 3D cylinder and returns its object ID.

pub fn set_object_position(&mut self, id: u32, x: f32, y: f32, z: f32) -> bool

Sets the position of a 3D object.

pub fn set_object_rotation(&mut self, id: u32, x: f32, y: f32, z: f32) -> bool

Sets the rotation of a 3D object (Euler angles in degrees).

pub fn set_object_scale(&mut self, id: u32, x: f32, y: f32, z: f32) -> bool

Sets the scale of a 3D object.

pub fn destroy_object(&mut self, object_id: u32) -> bool

Removes a 3D object from the scene.

pub fn add_light( &mut self, light_type: i32, pos_x: f32, pos_y: f32, pos_z: f32, dir_x: f32, dir_y: f32, dir_z: f32, r: f32, g: f32, b: f32, intensity: f32, range: f32, spot_angle: f32, ) -> u32

Adds a light to the 3D scene with flattened parameters.

pub fn update_light( &mut self, light_id: u32, light_type: i32, pos_x: f32, pos_y: f32, pos_z: f32, dir_x: f32, dir_y: f32, dir_z: f32, r: f32, g: f32, b: f32, intensity: f32, range: f32, spot_angle: f32, ) -> bool

Updates a light’s properties.

pub fn remove_light(&mut self, light_id: u32) -> bool

Removes a light from the 3D scene.

pub fn set_camera_position(&mut self, x: f32, y: f32, z: f32) -> bool

Sets the 3D camera position.

pub fn set_camera_rotation(&mut self, pitch: f32, yaw: f32, roll: f32) -> bool

Sets the 3D camera rotation (pitch, yaw, roll in degrees).

pub fn configure_grid( &mut self, enabled: bool, size: f32, divisions: u32, ) -> bool

Configures the ground grid.

pub fn set_grid_enabled(&mut self, enabled: bool) -> bool

Sets grid enabled state.

pub fn configure_skybox( &mut self, enabled: bool, r: f32, g: f32, b: f32, a: f32, ) -> bool

Configures the skybox/background color.

pub fn configure_fog( &mut self, enabled: bool, r: f32, g: f32, b: f32, density: f32, ) -> bool

Configures fog settings.

pub fn set_fog_enabled(&mut self, enabled: bool) -> bool

Sets fog enabled state.

pub fn render(&mut self) -> bool

Renders all 3D objects in the scene.

pub fn render_all(&mut self) -> bool

Renders all 3D objects (alias for render).

pub fn has_3d_renderer(&self) -> bool

Returns true if a 3D renderer is initialized.

impl GoudGame

pub fn load(&mut self, path: &str) -> u64

Loads a texture from an image file and returns a packed u64 handle.

Returns u64::MAX on error.

pub fn destroy(&mut self, texture: u64) -> bool

Destroys a texture and releases its GPU resources.

impl GoudGame

pub fn should_close(&self) -> bool

Returns true if the window has been requested to close.

This checks whether the user clicked the close button, pressed Alt+F4, or called set_should_close.

Returns false if no platform backend is initialized (headless mode).

pub fn set_should_close(&mut self, should_close: bool) -> Result<(), GoudError>

Signals the window to close (or not) after the current frame.

Errors

Returns an error if no platform backend is initialized.

pub fn poll_events(&mut self) -> Result<f32, GoudError>

Polls platform events and advances input state for the new frame.

This processes all pending window/input events, syncs the OpenGL viewport on window resize, and returns the delta time (seconds since last call). Must be called once per frame before querying input.

Errors

Returns an error if no platform backend is initialized.

pub fn swap_buffers(&mut self) -> Result<(), GoudError>

Presents the rendered frame by swapping front and back buffers.

Call this at the end of each frame after all rendering is complete.

Errors

Returns an error if no platform backend is initialized.

pub fn clear(&mut self, r: f32, g: f32, b: f32, a: f32)

Clears the window with the specified color.

Sets the clear color and clears the color buffer using the render backend.

pub fn get_window_size(&self) -> (u32, u32)

Returns the physical window size (width, height) in pixels.

If no platform backend is initialized, returns the configured size from GameConfig.

pub fn has_platform(&self) -> bool

Returns true if a platform backend is initialized.

When false, window/rendering methods will return errors or fall back to headless behavior.

pub fn get_delta_time(&self) -> f32

Returns the delta time (seconds since last poll_events call).

This reads from the internal GameContext which is updated by poll_events. Returns 0.0 before the first poll.

pub fn get_framebuffer_size(&self) -> (u32, u32)

Returns the physical framebuffer size (width, height) in pixels.

On HiDPI/Retina displays, this may differ from the logical window size returned by get_window_size. Renderers should use this for gl::Viewport.

If no platform backend is initialized, returns the configured size.

Trait Implementations

impl Debug for GoudGame

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for GoudGame

fn default() -> GoudGame

Returns the “default value” for a type.