Game

Subclass hook that produces the concrete dependency resolver the host hands to a component's resolveDependencies. The World hosts a resolver scoped to siblings only; a WorldObject hosts one that also exposes cross-tier lookups against the parent world.

Engine-internal — never called by user code.

Hook for subclasses to intercept errors thrown by a component's onDestroy during AbstractComponentHost.removeAllComponents. Default behaviour is to log and swallow — a single bad component must not prevent the rest of the host's components from being torn down. Subclasses may override to route errors through their own reporting channel.

Adds a new component to the host object. Throws if a component with the specified key already exists. Calls onAdded() on the component once registered with its host.

Adds a new component to the host object using a factory function. Internally produces the new component using the factory function, then calls addComponent() with the result.

The advantage of using this method over addComponent() is that the factory function is provided with the host.

Adds a new set of components to the host object. Throws if a component with the specified key already exists. Calls onAdded() on each component after they are all registered with the host, rather than one by one. This is important for components that may want to reference each other during the addition phase via host.getComponent() or similar methods.

It is recommended to use this method rather than addComponent() in situations like initialization of a new host object.

Adds a new set of components to the host object based on an input map of component keys to factory functions. Behavious is equivalent to addComponents() using the key and output of each factory function.

Creates a new World and marks it as the active world for this Game. The engine auto-attaches a Scene (parented to the PIXI application's stage) and a Camera to every world it creates, so the user's component factory sees both as already-resolvable siblings.

Only one world may be active at a time. Calling this method while a world already exists throws ErrorCode.GAME_WORLD_ALREADY_EXISTS; destroy the existing one first via Game.destroyWorld.

Tears the game down completely: destroys the active world (if any), runs onDestroy on every game component, unhooks the PIXI ticker, and destroys the underlying PIXI application. The Game instance is not reusable after this call.

Idempotent in the same sense as World.destroy — calling it twice is safe and the second call is a no-op.

Destroys the active world, releasing this Game's reference to it. Equivalent to calling world.destroy() and then clearing Game.activeWorld, in that order — the world's components and objects all see their onDestroy hooks fire as part of the call.

Subsequent Game.createWorld calls succeed because the active world slot is now empty.

Gets a component from the host object using the key it was registered with. Throws if the component does not exist. Performs an efficient lookup on a local Map instance.

Gets a component from the host object using its type. Throws if no component of the type exists, or if more than one component of the type exists — in the multi-match case, getComponentByType deliberately does not pick one for you. Use ComponentHost.getComponentsByType when you genuinely expect multiple matches, or look the component up by its string key.

Performs an O(n) lookup once per type initially, then caches the resolved key for O(1) lookups on subsequent calls. The cache is invalidated whenever a component is removed.

Gets every component on the host of the given type, in the order they were originally registered. Returns an empty array if no components match.

Unlike ComponentHost.getComponentByType, this method never throws on multiplicity — it is the explicit "I expect more than one" accessor.

Gets a reference to the host object that this component is attached to. Required for the compiler to be able to resolve the type of the host object correctly in some internal function calls (e.g. when resolving the type of the host object from a factory function).

Returns the current keyboard state — the set of physical keys held at tick-snapshot time, plus a isDown(code) predicate for membership tests. Page-global; the same snapshot is visible to menu UI and to gameplay code alike.

Keys are identified by KeyboardEvent.code (the physical key, not the logical character) so movement bindings like KeyW/KeyA/ KeyS/KeyD keep working across keyboard layouts. See KeyboardState for the convention and a pointer to MDN's full code-value list.

Allocates a fresh KeyboardState (with a freshly-cloned downKeys set) per call so callers can safely stash the result.

Requires the auto-attached Keyboard component registered under KEYBOARD_COMPONENT_KEY. If you removed it deliberately, calling this method throws ErrorCode.COMPONENT_NOT_FOUND.

Returns the current screen-space mouse snapshot — canvas-local cursor position and the held/released state of the three standard buttons. Independent of any world or camera; the same snapshot is visible to menu UI and to gameplay code alike.

For the world-space projection of the cursor (camera-transformed), reach for World.getMouseState instead. This method exists so code working entirely in screen space (overlays, HUDs, intro menus with no world yet) doesn't have to construct a world to read the pointer.

Allocates a fresh MouseSnapshot (and a fresh Point for screenPosition) per call so callers can safely stash the result.

Requires the auto-attached Mouse component registered under MOUSE_COMPONENT_KEY. If you removed it deliberately, calling this method throws ErrorCode.COMPONENT_NOT_FOUND.

Gets a component from the host object using the key it was registered with. Returns null if the component does not exist, rather than throwing an error. Useful for referencing transient or optional components without manually handling errors.

Gets a component from the host object using its type. Returns null if the component does not exist or if more than one component of the type is registered (i.e. the lookup is ambiguous) — the nullable variant collapses both "not found" and "ambiguous" into a single null. Use ComponentHost.getComponentsByType when you need to distinguish them.

Checks if the host object has a component with the specified key.

Checks if the host object has a component with the specified type.

Removes all components from the host object. Typically called internally when the lifecycle of the host object is terminated. Differs from individually removing components in that it first calls onDestroy() on each component, then removes references from the host object in a separate step. This allows cleaner teardown of components that may reference each other.

Removes a component from the host object. Care should be taken when manually removing components, as methods like getComponent() will throw if components do not exist. Removal is idempotent and will do nothing if the component does not exist i.e. was already removed, or never existed.

Runs the game's per-frame tick: every game component's pre/update/post phase in order, then delegates to the active world's update() if one exists. Wired to the PIXI ticker during construction, so user code almost never calls this method directly; it's public only so tests (and the rare callers that disable the ticker for deterministic stepping) can drive a single tick on demand.

Creates and initialises a new Game. The async step is the PIXI application's own init() — which constructs the WebGL/WebGPU context and prepares the renderer. After it resolves, the canvas is appended to document.body (when running in a browser), the engine's auto-attached components are registered, the ticker is wired, and the returned Game is ready to receive a Game.createWorld call.

Synchronous test-only factory that constructs a Game backed by a stub PIXI Application. No WebGL context, no canvas mounted to the DOM, no ticker registered with a real renderer.

When to use this

Unit tests and headless tooling only. The engine's production surface — every accessor that needs page-scoped services like the mouse or keyboard — assumes a Game is present, so unit tests that exercise a World in isolation need something to satisfy the new mandatory game argument on the World constructor. This factory exists to give those tests a cheap, synchronous game without the cost of bootstrapping a real PIXI renderer.

When not to use this

• Never in production game code. The stub application does not render anything, does not run a ticker, does not own a canvas attached to the page. Anything that depends on actual draw output — Scene's transform sync to the screen, AbstractGraphics's parenting to the stage during real rendering, any code expecting Game.update to be driven by the PIXI ticker — will not behave correctly when the game is headless. Use Game.bootstrap instead, which performs the asynchronous WebGL/WebGPU init and mounts the canvas under document.body.
• Not for renderer-level unit tests that need to observe the real PIXI pipeline. Those should construct their own Application and pass it to the public Game constructor.

The auto-attached Mouse and Keyboard components are still registered on the returned game. In non-browser environments (Node, jest's default node environment) their typeof window guards short-circuit listener attachment, so they're effectively inert — callable, but reporting empty input state.