World

The root container for an arcade2d simulation. A World owns the set of live WorldObjects, drives the per-frame update loop that animates them, and itself hosts world-scoped Components — i.e. components that conceptually belong to the simulation as a whole rather than to any single object (a Scene graphics root, a physics broadphase, an input sampler, an audio mixer, and so on). It also optionally resolves named prefab lookups against a PrefabRegistry passed at construction.

The class is designed so a typical game's "main loop" is one line: construct the world, then call World.update once per animation frame. Everything else — when components run, what order they run in, how spawns/destroys interact with the running tick — is the responsibility of this class and is described below.

The update tick

Each call to World.update executes the following schedule, in this exact order. Understanding the schedule is the single most important thing about working with arcade2d, because everything else (spawn semantics, destroy semantics, cross-component wiring, ordering pitfalls) is downstream of it.

┌──────────────────────────────────────────────────────────────────┐
│ Phase 1 — Pre-update                                             │
│   1a. World components, in insertion order, call `onPreUpdate`   │
│   1b. Each live WorldObject, in spawn order, has every component │
│       (in component insertion order) call `onPreUpdate`          │
├──────────────────────────────────────────────────────────────────┤
│ Phase 2 — Update                                                 │
│   2a. World components, in insertion order, call `onUpdate`      │
│   2b. Each live WorldObject, in spawn order, has every component │
│       (in component insertion order) call `onUpdate`             │
├──────────────────────────────────────────────────────────────────┤
│ Phase 3 — Post-update                                            │
│   3a. World components, in insertion order, call `onPostUpdate`  │
│   3b. Each live WorldObject, in spawn order, has every component │
│       (in component insertion order) call `onPostUpdate`         │
├──────────────────────────────────────────────────────────────────┤
│ Phase 4 — Sweep + flush                                          │
│   4a. Run `onDestroy` on every object marked destroyed this tick │
│       (or earlier) and remove them from the live set + id map    │
│   4b. Promote objects spawned mid-tick into the live set so they │
│       participate in the *next* tick                             │
└──────────────────────────────────────────────────────────────────┘

Two ordering rules that follow from the schedule

1. Phases are strict. Every component on every host finishes its onPreUpdate before any component anywhere starts onUpdate. Every onUpdate finishes before any onPostUpdate starts. This is the contract you rely on to make camera-follows-player and similar "I need everyone else's results" patterns work without race conditions.

2. Within a phase, world components run before object components. A world-scoped input sampler in Phase 1a will have finished polling by the time a controller component in Phase 1b reads it. A world-scoped physics step in Phase 2a will have resolved collisions by the time a per-object damage handler in Phase 2b decides what to do about them.

Within each of those two sub-orderings (world components among themselves; object components on a single host among themselves), the order is insertion order — i.e. the order they were registered via addComponents (or the order they appear in a Prefab's component map). There is no priority or weight system; if A must run before B, register A first.

Choosing the right phase

The three update hooks aren't "early, middle, late" so much as three specific roles. Picking the right one is mostly about asking what does this code need to be true when it runs?

onPreUpdate — sample and prepare

Use when you produce state that other components will consume during onUpdate. The hook is optional: components that don't have prep work to do should omit it. Canonical uses:

• Input polling. A world-scoped InputSystem reads keyboard/mouse state once per tick in onPreUpdate and exposes it via getters. Every controller component then queries it in onUpdate and sees a consistent snapshot.
• Per-frame buffer clears. A world-scoped collision broadphase clears the previous tick's overlap set in onPreUpdate so per-object colliders can populate it during their own onUpdate without stepping on the previous frame's results.
• Interpolation snapshots. A graphics component caches its pre-update transform so any other system that wants to interpolate between "before" and "after" positions during the post phase has a clean snapshot to work from.

onUpdate — do the work

The main per-frame body of behaviour. Required on every component — even if it's empty. Use when the work doesn't depend on having seen the results of everyone else's update this frame. The vast majority of components only need this hook. Canonical uses:

• Movement and behaviour. Controllers reading input and translating it into changes to the host's position, AI components evaluating their decision logic, projectile components advancing themselves.
• World simulation steps. A world-scoped physics system stepping its solver, a particle emitter advancing emission timers, a wave manager spawning enemies on a cadence.
• Lifetime accounting. A bullet decrementing its remaining lifetime and self-destructing when it hits zero.

onPostUpdate — react to everyone else's updates

Use when your work requires that every other component has finished its onUpdate first. Optional; skip when not needed. Canonical uses:

• Camera follow. A world- or object-scoped camera component reads the player's already-moved position in onPostUpdate and centres the viewport on it. If you did this in onUpdate and the player's controller ran later in the iteration order, you'd lag by a frame.
• Transform sync to a renderer. A graphics component copying host.position into a PIXI display object in onPostUpdate guarantees the final visual reflects every behaviour change that happened this tick, including ones from late-running components.
• Late audits and assertions. A debug overlay that needs to inspect the world's settled state, count active enemies, etc.

Rule of thumb

If the code reads state set by other components: pre-update produces, update consumes, post-update reacts. If you only set state, you almost certainly want onUpdate. If you're not sure, start with onUpdate and move to a different phase only if you see a one-frame-lag bug.

Spawn and destroy semantics

Both spawns (createFromPrefab, createFromPrefabName, createEmpty) and destroys (WorldObject.destroy) are deferred and re-entrancy-safe so that running components can't observe inconsistent state mid-tick.

Spawning

• Outside a tick (e.g. during world setup before the first update() call), spawned objects join the live set immediately and participate in the very next tick from Phase 1 onward.
• During a tick, spawned objects are queued and only join the live set during Phase 4b. They first participate in the next tick. This keeps Phase 2/3 iteration order stable even if a component spawns ten new objects mid-update.
• Either way, the new object is findable via World.findById immediately — the id map is updated synchronously on spawn — so cross-references in the same tick are valid even if the spawned object hasn't yet been driven by an update. Bulk tag queries are deliberately the other way: World.findByTag and World.findOneByTag exclude pending objects by default, because iterating over a mix of "fully ticked" and "exists but has never ticked" objects silently produces wrong answers (an AOE damaging enemies that have not initialised, a counter reporting non-yet-rendered units). Opt back into the same-tick view with { includePending: true } when you genuinely want it.

Destroying

WorldObject.destroy only marks the object. The real removal happens in Phase 4a. Consequences:

• An object destroyed mid-tick is skipped for all remaining phases. If a controller destroys itself in Phase 1, neither Phase 2 nor Phase 3 will touch it. This is the "no final tick" rule and exists so destroyed objects can't observe state from after their own death.
• onDestroy is idempotent. Calling destroy() twice, or destroying an already-cleaned object during teardown, is a no-op. Components on a destroyed object also have their onDestroy run exactly once during sweep.
• Spawned-and-destroyed-in-the-same-tick objects never enter the live set but do receive onDestroy during Phase 4b, so component cleanup is honoured.

Enable/disable: per-component and per-host

Two gates control whether update hooks run, layered from most specific to most general:

1. Per-component — each Component carries an optional enabled flag. When explicitly false, the engine skips that component's onPreUpdate, onUpdate, and onPostUpdate.
2. Per-host — every host (the World itself, and every WorldObject) carries an AbstractComponentHost.enabled field. When false, every component on that host has all three update phases skipped at a single early-return — the cheap way to freeze an entire object during a cutscene or pause a UI widget while a menu is up. The world-level toggle gates the world's own components only; object iteration is controlled by whether update() is called.

Neither gate touches onAdded or onDestroy. Both fire regardless so a component is never left half-attached and a destroyed host is always cleanly torn down.

Error isolation

Every component hook (onPreUpdate, onUpdate, onPostUpdate, onDestroy) is wrapped in a try/catch by the engine. A thrown error in one component does not abort the tick — the rest of the host's components, and every other host, continue to run. Errors are routed through World.reportError, which forwards to the optional WorldOptions.onError handler (defaulting to console.error). If you want fail-fast, throw from inside onError and the engine's try/finally will let the exception propagate out of update().

Cross-references

• Component — the per-host lifecycle interface.
• WorldObject — the per-object host driven by Phases 1b/2b/3b.
• Prefab — the declarative template used to build objects.
• PrefabRegistry — name-keyed prefab lookup, attachable to a world for World.createFromPrefabName.
• WorldErrorContext — payload handed to onError when a component callback throws.

// The blessed path: bootstrap a Game, then ask it for a World.
const game = await Game.bootstrap({ canvas: { fill: 'window' } });

const world = game.createWorld({
  components: (world) => ({
    // Phase 1a (pre-update) — registered first so it runs first.
    input: () => new InputSystem(world),
    // Phase 2a (update) — runs second, sees fresh input.
    physics: () => new PhysicsSystem(world),
    // Phase 3a (post-update) — runs third, sees settled positions.
    camera: () => new CameraSystem(world),
  }),
  prefabs: prefabRegistry,
});

onUpdate() {
  const keys = this.host.world.getKeyboardState();

  if (keys.isDown('KeyW')) this.host.position.y -= 5;
  if (keys.isDown('KeyS')) this.host.position.y += 5;
}

onUpdate() {
  const { position, buttons } = this.host.world.getMouseState();

  if (buttons.left) {
    this.host.position.moveTowards(position, 5);
  }
}