Scene
graphics/scene.ts:72 Extends AbstractWorldComponent<SceneDeps>
The world-scoped graphics root: every WorldObject-attached
graphics component parents its display object to the Scene, and the
Scene in turn lives under the Pixi Application's root stage.
Decoupling the engine's scene graph from the Pixi stage one level lets
the engine own framing decisions (mounting, unmounting, clearing on world
teardown) without dictating the rest of the application's Pixi layout.
Wraps a Pixi Container internally rather than extending one. The
container is created in the constructor, parented to the application's
stage in Scene.onAdded, and detached again in
Scene.onDestroy.
Camera-driven framing
Scene is the renderer-aware half of the engine's camera system. It
declares a sibling dependency on the auto-attached Camera and,
during Scene.onPostUpdate, applies the camera's inverse
transform to the underlying container:
- The container's pivot is set to the camera's world-space position, so that world point becomes the container's rotation/origin anchor.
- The container is positioned at the centre of the application's screen, plus the camera's current Camera.shakeOffset (in screen pixels), so the pivoted world point lands in the middle of the canvas — with whatever shake jitter is in flight stacked on top.
- The container's rotation is set to the negated camera rotation, so increasing Camera.rotation spins the world clockwise beneath a stationary viewer.
- The container's scale is set to the camera's Camera.zoom, so the rendered world scales with the camera, uniform on both axes.
With the default camera (position = (0, 0), rotation = 0, zoom = 1),
the world's origin appears at the centre of the canvas and one world
unit equals one screen pixel.
Coordinate conversions
Scene.worldToScreen and Scene.screenToWorld expose the forward and inverse forms of the transform above. Both use the camera's logical state (no shake offset) so that they are proper inverses of each other, which is what input handling and HUD-marker placement almost always want — clicking during a shake should still land on the world point the player aimed at.
Example
// In normal use, the engine wires Scene up for you: `game.createWorld()`
// auto-attaches one bound to the game's PIXI application stage. Reach for
// the constructor directly only when you're mounting under a custom
// application — typically a test, devtool, or alternative renderer.
const world = game.createWorld();
// The auto-attached camera makes "follow the player" a one-liner.
world.camera.position.copyFrom(player.position);Constructors
Properties
enabled: boolean Per-component gate on the three update hooks (onPreUpdate,
onUpdate, onPostUpdate). When explicitly false, the engine skips
all three for this component during the host's tick — useful for
temporarily pausing behaviour (e.g. a freeze powerup) without removing
the component and losing its internal state.
Does not gate onAdded or onDestroy; those always fire so a host can
never end up with a half-attached component.
Accessors
game: Game The Game the host world belongs to. Always non-null — the
world's game field is a mandatory construction argument, not an
option.
raw: Container Direct access to the underlying Pixi Container instance.
Use with care. raw is an intentional escape hatch for cases the
arcade2d API doesn't cover — sorting children, custom layer ordering,
applying filters at the scene level, masking. Code that touches raw
is coupled to Pixi's public API and may break when:
- arcade2d upgrades Pixi (including minor versions).
- Pixi itself ships a breaking change.
- arcade2d swaps Pixi for a different renderer.
None of those will be treated as breaking changes to arcade2d's own
surface. Prefer the typed methods on this component; reach for raw
only when no equivalent exists, and isolate the access behind your own
helper so the coupling is in one place.
world: World The World this component is attached to — identical to
AbstractComponent.host at this tier, exposed under the
world name so subclass code reads the same on every tier.
Methods
addChild(child: Container): void Adds a Pixi display object as a child of the scene. Called by
AbstractGraphics during onAdded; callers working directly
with Pixi (e.g. integrating an effect that isn't yet modeled as a
Component) can use this as a lower-friction alternative to going
through Scene.raw.
Parameters
-
childContainer
Returns
void onAdded(): void Lifecycle hook that is called when the component is added to the host object. Should not be called directly.
Returns
void onDestroy(): void Lifecycle hook that is called when the host object is destroyed. Should not be called directly.
Returns
void onPostUpdate(_update: unknown, __namedParameters: SceneDeps): void Reads the auto-attached Camera's state and applies its inverse
transform to the underlying Pixi container. Runs in the post-update
phase so any camera mutation made during onUpdate (a follow
controller writing camera.position = player.position, for example) is
already settled by the time the scene re-frames.
The shake offset is added to the container's position, not the
pivot — Pixi applies position after the scale/rotation chain, so
the offset stays in literal screen pixels regardless of camera.zoom
and camera.rotation. That's what game devs intuitively want from a
"screen-shake of N pixels": N pixels on screen, not a value that grows
with zoom-in.
Parameters
-
_updateunknown -
__namedParametersSceneDeps
Returns
void onUpdate(_update: WorldUpdate, _deps: SceneDeps): void Lifecycle hook for the main update phase. Called once per world
tick, after every component's onPreUpdate and before any
onPostUpdate.
Parameters
-
_updateWorldUpdate -
_depsSceneDeps
Returns
void removeChild(child: Container): void Detaches a Pixi display object from the scene. Idempotent — calling with a child that isn't attached is a no-op.
Parameters
-
childContainer
Returns
void resolveDependencies(resolver: WorldDependencyResolver): SceneDeps Parameters
-
resolverWorldDependencyResolver
Returns
SceneDeps screenToWorld(screen: PointPrimitive): Point Converts a point in canvas-local screen pixels to world space, using the camera's logical state. This is the primitive Mouse builds on to report pointer positions in world coordinates, and what game-side click handlers should generally use — clicking during a camera shake should still resolve to the world point the player aimed at, not a phantom shifted by the jitter.
The inverse of Scene.worldToScreen.
Parameters
-
screenPointPrimitive
worldToScreen(world: PointPrimitive): Point Converts a point in world space to canvas-local screen pixels, using the camera's logical state (i.e. position, rotation, and zoom — but not shake). Useful for placing HUD overlays that need to track a world target (mission markers, damage numbers floating above an enemy, etc.).
The inverse of Scene.screenToWorld: round-tripping a point through both yields the original (modulo floating-point error).
Parameters
-
worldPointPrimitive