Struct EngineHandle

Source

pub struct EngineHandle { /* private fields */ }

Expand description

A handle to a running or initialized engine instance.

Holds the engine configuration, an optional Canvas 2D renderer, an optional WebGPU renderer, and the optional scheduler handle once the game loop has started. Use Engine::new_handle to construct one, then call init_canvas or init_webgpu (matching the backend chosen in RenderConfig) and finally start to begin the game loop.

Implementations§

Source §

impl EngineHandle

Implements lifecycle management for EngineHandle.

All getter methods (get_config, get_canvas_renderer, get_webgpu_renderer) are generated by the Data derive on the struct definition; this impl only contributes lifecycle and accessor behavior that is not expressible as a plain getter.

Source

pub fn init_canvas(&mut self) -> bool

Initializes the Canvas 2D rendering backend.

On success, populates canvas_renderer and clears webgpu_renderer. On failure, both renderer fields remain None.

§Returns

bool - true if the renderer was created successfully.

Source

pub async fn init_webgpu(&mut self) -> Result<WebGpuRenderer, WebGpuInitError>

Initializes the WebGPU rendering backend.

On success, populates webgpu_renderer and clears canvas_renderer. On failure, both renderer fields remain None and the typed error is returned so the caller can decide how to surface it (typically via Console::error).

§Returns

Result<WebGpuRenderer, WebGpuInitError> - The initialized renderer, or a typed error describing the specific failure.

Source

pub fn init_webgl(&mut self) -> Result<WebGlRenderer, WebGlInitError>

Initializes the WebGL 2 rendering backend.

On success, populates webgl_renderer and clears the other renderer fields. On failure, all renderer fields remain None and the typed error is returned so the caller can decide how to surface it.

§Returns

Result<WebGlRenderer, WebGlInitError> - The initialized renderer, or a typed error describing the specific failure.

Source

pub fn register_input(&mut self) -> Option<InputStateCell>

Attaches DOM input listeners and stores the shared input state.

Resolves the canvas element from the render configuration’s canvas_selector and routes DOM events into a shared InputState: keyboard events bind to window, mouse and touch events bind to the canvas. This works for both the Canvas 2D and WebGPU backends because either way the same <canvas> element receives the pointer events.

Returns None (and stores nothing) if the canvas selector does not resolve at call time - for example when called before the canvas element is mounted into the DOM.

The registered listeners stay alive for the lifetime of the document (mount-only convention; there is no matching unregister_input).

§Returns

Option<InputStateCell> - The shared input state cell, or None if the canvas element was not found.

Source

pub fn start(&mut self, handler: TickHandlerRc)

Starts the game loop with the given tick handler.

The scheduler configuration from EngineConfig controls the fixed timestep and maximum frame time. The scheduler handle is stored internally and can be stopped via stop. If register_input has attached DOM listeners, the shared input state is closed out at the end of every frame so edge-triggered queries (keys_pressed, keys_released, mouse_buttons_pressed, touch_started) only report the frame they occurred in. Tasks registered through EngineHandle::register_task are advanced once per fixed step, immediately after the handler’s on_update callback.

§Arguments

TickHandlerRc - The tick handler receiving update and render callbacks.

Source

pub fn tasks(&self) -> &TaskRegistryRc

Returns the shared task registry, for direct inspection or registration outside EngineHandle::register_task.

§Returns

&TaskRegistryRc - The engine’s task registry.

Source

pub fn register_task<T>(&self, task: T) -> TaskHandle
where T: Updatable + 'static,

Registers a task to be advanced on every fixed step.

The task is driven by SchedulerState::tick immediately after the handler’s on_update callback, with the configured SchedulerConfig::get_fixed_timestep delta. This is the entry point that gives Timer, Tween, ParticleEmitter, Entity, Animator, SceneManager, and the physics worlds a heartbeat — all of them implement Updatable but none were driven before the registry existed.

Registration order is preserved: tasks are updated in the order they were registered.

§Arguments

T - The updater to register. Must implement Updatable.

§Returns

TaskHandle - A handle used to unregister the task.

Source

pub fn unregister_task(&self, handle: &TaskHandle) -> bool

Removes a previously registered task.

§Arguments

&TaskHandle - The handle returned by EngineHandle::register_task.

§Returns

bool - true if a task was removed, false if the handle did not match any registered task.

Source

pub fn register_assets(&mut self) -> AssetLoader

Creates the engine’s asset loader and drives it from the game loop.

The loader implements Updatable, so it is registered with the scheduler’s TaskRegistry rather than polled by hand. On every fixed step it releases the onload / onerror callbacks of loads that have already settled — a wasm_bindgen::Closure cannot be dropped from inside the callback that is running, so this engine update is the only safe drop point. Without this the loader would pin two closures per asset forever and is_all_loaded would never observe the decrement of the pending count.

Calling this more than once returns the already-created loader rather than replacing it, so pending loads are not orphaned.