rgame 0.2.0 → 0.3.0

data/docs/api/components.md

@@ -1,325 +1,1005 @@
 # Components
 
-A **component** is a reusable piece of behaviour attached to a `Node2D`, instead of
-baked into a node subclass. A node composes several of them; each knows its owning
-`node` and is driven by the node's tick. Components live in `engine/components/` under
-`RGame::Engine::Components` and subclass `RGame::Engine::Component`. See [Scene graph](scene_graph.md)
-for how nodes drive components, and [Systems & shared resources](systems.md) for
-components that act as shared, scene- or program-scoped services.
+**A component is a reusable piece of behaviour attached to a `Node2D`**, instead
+of being built into a node subclass. A node composes several components. Each
+knows its owning `node`, and the node's tick drives it. Components live in
+`engine/components/`, under `RGame::Engine::Components`, and subclass
+`RGame::Engine::Component`. [Scene graph](scene_graph.md) explains how nodes drive
+components. [Systems & shared resources](systems.md) covers components that serve
+a whole scene or program.
+
+`examples/walk` shows the smallest character in one file: `AnimatedSprite`,
+`CharacterBody` and `PlayerController`.
+
+## When what you want is not a component
+
+**A component is behaviour on the node's tick.** It overrides `control`, `update`
+or `draw`, and the node drives it. Much of what a game needs is not that. Searching
+this page for it leads to worse, hand-made answers.
+
+Those helpers live in the [Toolbox](toolbox.md). A game constructs them directly,
+attached to nothing, and that is ordinary use. `examples/sound` emits on `AudioBus`
+and reads a `Text` within ten lines.
+
+| Looking for | Reach for | |
+|---|---|---|
+| a label from a value that changes, with no `String` per frame | `Text` | [→](toolbox.md#text--the-string-a-node-draws) |
+| to say *what happened* without naming a sound device | `AudioBus` | [→](toolbox.md#audiobus--decoupled-audio-facts) |
+| a point to follow, clamped to the world | `Camera` | [→](toolbox.md#camera--follow-a-point-clamp-to-the-world) |
+| text in the player's language | `I18n` | [→](localization.md) |
+| an ordered route to walk | `Path` | [→](toolbox.md#path--a-walkable-polyline) |
+| the cheapest route between two tiles | `NavGrid`, from `TileWorld#nav_grid` | [→](toolbox.md#navgrid--routes-over-a-tile-grid) |
+| a node that walks itself to a point, around the map | `Components::Navigator` | [→](#navigator) |
+
+**Per-frame work earns a component.** Two toolbox classes have component wrappers,
+for that reason only. A timer must advance every tick, and a pool must reclaim
+freed nodes every tick. `Components::Timer` and `Components::Pool` put that work in
+the traversal, where nothing can forget it. Without per-frame work there is no
+wrapper. A `Text` is read when something draws it. A component that
+overrode no hook would be a component in name only. The one-per-slot rule would
+even make a second label on one node harder.
 
 ## The `Component` base
 
-`RGame::Engine::Component` (`rgame/engine/component`) gives every component a `node` back-link and
-a set of hooks the node calls — override the ones you need; the rest are no-ops. Like
-nodes, it extends the signal DSL, so a component can declare and emit signals.
+`RGame::Engine::Component` (`rgame/engine/component`) gives every component a
+`node` back-link and hooks the node calls. Override the hooks you need; the rest
+do nothing. Like nodes, components extend the signal DSL, so they can declare and
+emit signals.
 
-Per-tick hooks (a node runs its components in each phase, before its own hook and
-before its children):
+**Per-tick hooks.** In each phase a node runs its components before its own hook
+and before its children.
 
-- `control(actions)` — read intent from the per-frame action snapshot. It is the
-  actions of whoever [owns the node](scene_graph.md#who-a-node-answers-to), so a
+- `control(actions)` reads intent from the per-tick action snapshot. The snapshot
+  belongs to whoever [owns the node](scene_graph.md#who-a-node-answers-to), so a
   component never learns there is more than one player.
-- `update(dt)` — advance state over the timestep.
-- `draw(renderer, view)` — render against the renderer interface, into the
-  [viewport being drawn](scene_graph.md#viewports-and-views). Most components ignore the
-  view; it is there for laying out against the region's edges and for culling.
+- `update(dt)` advances state over the timestep.
+- `draw(renderer, view)` renders through the renderer interface into the
+  [viewport being drawn](scene_graph.md#viewports-and-views). Most components
+  ignore `view`. It serves layout against the region's edges, and culling.
+
+**Tree-lifecycle hooks.** The engine fires these when the node enters or leaves
+the live tree. Anchors and sibling systems are reachable here, so wire across
+nodes here, not in `initialize`.
+
+- `on_attach`: the node entered the tree. Look up shared systems and register
+  with them.
+- `on_detach`: the node is leaving. Release those registrations.
+
+`sweep_freed` serves container components that hold nodes outside the normal
+child list. The default does nothing; see
+[deferred free](scene_graph.md#deferred-free).
+
+**`require_sibling(klass)` opens the `on_attach` of a component that drives a
+sibling**: `@body = require_sibling(CharacterBody)`. It returns the component, or
+raises naming both. A plain `nil` would stay silent until the first frame called a
+method on it. When it raises, the cause is nearly always add order; see
+[Where to add a component](#where-to-add-a-component) below. It also raises,
+naming each one, when *several* siblings match `klass`, such as two
+[`Mover`](#mover)s under one [`AnimatedSprite`](#animatedsprite). It never quietly
+takes whichever came first.
+
+**A node holds at most one component per slot.** The slot defaults to the
+component's class, so by default a node holds one per class, and `add_component`
+raises on a taken slot. Pass `as: :name` to keep several of one type, such as a
+spawn timer and a wave timer. Look a component up with `get_component(key)`. The
+key is a class, matched by ancestry and raising if several share the type, or a
+Symbol name.
+
+## Where to add a component
+
+**Assemble a node before it enters the tree.** Two shapes do that. Which one fits
+depends on whether the node has a class of its own:
+
+- **A `Node2D` subclass adds components in `initialize`.** This default covers most
+  entities.
+
+  ```ruby
+  class Bullet < RGame::Engine::Node2D
+    def initialize(x:, y:, vx:, vy:)
+      super(x: x, y: y)
+      add_component(RGame::Engine::Components::Velocity.new(vx: vx, vy: vy))
+      add_component(RGame::Engine::Components::DespawnOffscreen.new)
+    end
+  end
+  ```
+
+- **A plain `Node2D` built from components gets a builder method** that returns
+  the assembled node. Use it when the node is nothing but its components, and a
+  subclass would add no behaviour. `examples/save_load` builds its walkers this
+  way.
+
+  ```ruby
+  def build_player
+    node = RGame::Engine::Node2D.new(x: spawn_x, y: spawn_y)
+    node.add_component(RGame::Engine::Components::AnimatedSprite.new(sheet: PLAYER_SHEET))
+    node.add_component(RGame::Engine::Components::FeetCollider.new(width: 10, height: 8))
+    node.add_component(RGame::Engine::Components::CharacterBody.new(
+                         speed: PLAYER_SPEED, blocked_by: [:tiles]
+                       ))
+    node.add_component(RGame::Engine::Components::PlayerController.new)
+    node
+  end
+  ```
 
-Tree-lifecycle hooks (fired by the engine when the node enters/leaves the live tree —
-this is where anchors and sibling systems are reachable, so do cross-node wiring here,
-not in `initialize`):
+**Both shapes work for the same reason.** The node is not in the tree yet, so
+`add_component` only appends. No `on_attach` fires until the whole set is present
+and the node enters. **Add order is therefore free.** `build_player` above adds an
+`AnimatedSprite` *before* the `CharacterBody` it faces by, and that works.
 
-- `on_attach` — the node entered the tree; pull and register with shared systems.
-- `on_detach` — the node is leaving; release those registrations.
+### Adding from `on_add`, and when you must
 
-`sweep_freed` exists for container components that hold nodes off the normal child
-list; the default is a no-op (see [deferred free](scene_graph.md#deferred-free)).
+**A node running `on_add` is already in the tree.** Each `add_component` attaches
+at once and sees only the components added before it. The same two lines in the
+other order raise (see [`require_sibling`](#the-component-base) above). Prefer
+`initialize` or a builder. Use `on_add` only when the component cannot be built
+earlier, because its constructor needs something only the tree can answer:
 
-A node holds **at most one component per slot**. The slot defaults to the component's
-class, so by default that's one per class (`add_component` raises on a taken slot) — but
-pass `as: :name` to keep several of one type (a spawn timer and a wave timer). Look a
-component up with `get_component(key)`, where `key` is a class (matched by ancestry; it
-raises if several share the type) or a Symbol name.
+```ruby
+def on_add
+  # Both arguments are cross-tree lookups: the asset manager hangs off the root's
+  # context, and the player registry is a system. Neither exists at construction.
+  add_component(RGame::Engine::Components::TileWorld.new(
+                  map: root.context.assets.tilemap(MAP_KEY).map,
+                  tilemap_id: MAP_KEY,
+                  cameras: root.system(RGame::Engine::Players).map(&:camera)
+                ))
+end
+```
 
-## Available components
+**Apply one test: does the constructor need the tree?** A `World` built from
+numbers the scene already has does not. Nor does a `CollisionWorld` built from a
+constant. `examples/collision` mounts both in `initialize`. There they are
+guaranteed to precede every entity the scene spawns later. A `TileWorld` parsed
+from the asset manager needs the tree, so it waits.
 
-### `Velocity`
+The opposite exception is a component added **deliberately** after entry, because
+it depends on state that exists only once the node is live. An example is a
+`CameraFollow` whose offset comes from the sibling body's resolved
+`collision_box`. That is a later decision, not assembly, and `on_add` suits it.
 
-Integrates linear and angular velocity into the node's transform each step.
+## Available components
 
-- **Construct:** `Velocity.new(vx: 0.0, vy: 0.0, spin: 0.0)`.
-- **State:** `vx`, `vy`, `spin` are read/write accessors — a controller (or the node's
-  own `control` hook) writes them as movement intent.
-- **Phase:** `update(dt)` adds `vx*dt`/`vy*dt` to `node.x`/`node.y` and `spin*dt` to
-  `node.angle`.
+### `ActionTrigger`
 
-A free-moving entity can use `Velocity` alone; pair it with a controller for input.
+**Maps held input actions to an `on_triggered(action)` signal, limited by a
+per-action cooldown.** One instance covers several actions and emits the action
+name, so listeners filter. The same component serves "fire" in a shooter or
+"jump" and "fire" in a platformer.
 
-### `PathFollow`
+- **Construct:** `ActionTrigger.new(cooldowns)`, where `cooldowns` is
+  `{ action => seconds }`, e.g. `ActionTrigger.new(fire: 0.22)`.
+- **Signal:** `on_triggered` fires with the action name:
+  `trigger.on_triggered { |a| … }`.
+- **Phase:** `update(dt)` ticks the per-action cooldowns. `control(actions)` emits
+  when an action is held and its cooldown has elapsed. Held plus cooldown gives
+  auto-repeat.
 
-Walks the owning node along an [`RGame::Engine::Path`](toolbox.md#path--a-walkable-polyline)
-at a constant speed and emits `on_finished` when it reaches the last waypoint — the seam a
-tower-defense game uses to leak a life when an enemy reaches the base.
+### `AnimatedSprite`
 
-- **Construct:** `PathFollow.new(path:, speed:)`.
-- **Lifecycle:** `on_attach` (re)starts the walk — back to the first waypoint with progress
-  cleared — so a pooled follower reacquired and re-added begins a fresh walk.
-- **Signal:** `on_finished` fires once (no payload) at the end of the path —
-  `follow.on_finished { node.queue_free }`.
-- **Phase:** `update(dt)` advances `speed * dt`, crossing as many segments as one step
-  spans and interpolating the node's position; allocation-free.
+**Draws a sprite-sheet animation, chosen from its [`Mover`](#mover) sibling's
+[heading](#mover).** It plays `walk_left`, `walk_right`, `walk_up` or `walk_down`
+while moving, and `stand` when still. The heading's larger axis picks the
+direction, and a tie goes horizontal. A keyboard diagonal therefore walks sideways,
+while a stick held mostly down walks down, as does a route segment running mostly
+down. Any mover works. A [`CharacterBody`](#characterbody) faces its intent. A
+[`PathFollow`](#pathfollow) or [`Navigator`](#navigator) faces the segment it
+walks. A [`Velocity`](#velocity) faces where it flies. The component owns an
+`RGame::Engine::Animator` over the pure `AnimationSet` built from the sheet's
+animation table.
+
+- **Construct:** `AnimatedSprite.new(sheet:, z: 0)`. `sheet` is the asset's
+  relative path. `z` orders this component against the node's other drawing,
+  inside the node's own slot, as for [`Sprite`](#sprite).
+- **Lifecycle:** `on_attach` resolves the sheet from the game's asset manager
+  (`node.root.context.assets.sheet(sheet)`) and builds its animation set. It
+  **sizes the node** to the sheet's frame (`node.width` and `height`), so a
+  [`FeetCollider`](#feetcollider) can read them. It then looks up the mover sibling
+  it faces by. A node with **two** movers raises here, naming both: both write the
+  position, so no facing is defined. The renderer resolves the same path when
+  drawing, so nothing is registered or passed in by hand.
+- **Phase:** `update(dt)` selects and advances the animation.
+  `draw(renderer, view)` renders the current frame via `renderer.sprite` at
+  **`0, 0`** with no angle. The traversal already placed the renderer on the node,
+  and a [`WorldView`](scene_graph.md#view-transforms-and-the-camera) ancestor
+  already applied the camera. The frame is lifted by
+  [`node.elevation`](scene_graph.md#elevation), so it draws at `0, -elevation`.
+  The component skips the draw when the view cannot show it. It measures the
+  node's box, raised by the same elevation, against `node.world_x` and `world_y`.
+  Culling uses world coordinates because it compares against the camera.
+  [`Sprite`](#sprite) is the single-image counterpart.
+
+### `BoxCollider`
+
+**A rectangular collision shape in a scene's
+[`CollisionWorld`](#collisionworld).** It is the sibling of
+[`CircleCollider`](#circlecollider), for box-shaped entities: a crate, a platform,
+a wall segment. It registers when the node enters the tree and unregisters when it
+leaves, so spawning and despawning never leak a registration.
+
+- **Construct:** `BoxCollider.new(width:, height:, offset_x: 0, offset_y: 0, layer: :default)`.
+  The offsets are relative to the node's origin, so a 32×32 sprite can carry a
+  small box at its feet. `layer` is an opaque tag. The *owner* reads it to decide
+  what a contact means; the collision system ignores it.
+- **Lifecycle:** `on_attach` registers with `node.system(CollisionWorld)`, and
+  `on_detach` unregisters. In a scene with **no** world, it stays a bare shape and
+  does not raise. A collider is a shape; a world turns shapes into contacts. A
+  tile-only game can therefore carry a feet box for
+  [`CharacterBody(blocked_by:)`](#characterbody), or any other [`Mover`](#mover),
+  alone. The cost: an `on_hit` handler in such a scene never fires, and nothing
+  reports it.
+- **Geometry:** the rectangle is an
+  [`RGame::Engine::CollisionBox`](toolbox.md#collisionbox--an-actors-feet-box),
+  exposed as the read/write `box` accessor. Assign a new one, such as
+  `CollisionBox.bottom_anchored(...)`, to retune a pooled entity's shape on reset.
+  No re-registration is needed. `aabb_x`, `aabb_y`, `aabb_w` and `aabb_h` give the
+  world-space box. `cx` and `cy` give the **box's** centre, which the world's range
+  queries measure from. A circle's centre, by contrast, is the node origin.
+- **Rotation:** the box stays axis-aligned in world space and does not turn with
+  the node. A spinning entity wants a `CircleCollider`, which rotation does not
+  affect, instead of a box recomputed every frame.
+- **Contacts:** `overlap?(other)` works against a box *or* a circle. The two
+  colliders settle the test between themselves, so both shapes mix freely in one
+  world.
+- **Blocking:** a box on a layer that some [`Mover`](#mover) named in
+  `blocked_by:` also *stops* that mover's steps, flush against this box's edge. The
+  box needs no opt-in; the other body's layer declaration is the whole setup.
+- **Signals:** `on_hit` fires with the other collider on the step a contact
+  **starts**, and `on_separated` on the step it **ends**:
+  `collider.on_hit { |other| ... }`. The system triggers them through
+  `emit_hit(other)` and `emit_separated(other)`. Each fires once per pair, so a
+  handler may count, play a sound or spend a life; see
+  [`CollisionWorld`](#collisionworld).
 
-### `Timer`
+```ruby
+collider = add_component(RGame::Engine::Components::BoxCollider.new(
+  width: 32, height: 32, layer: :pickup
+))
+collider.on_hit { |other| collect if other.layer == :player }
+```
 
-A node-driven interval timer: it rides the node's update tick (so nothing can forget to
-advance it) and emits `on_timeout` each time a whole interval elapses — a spawn cadence, a
-tower's fire rate, a wave clock. Wraps the pure [`RGame::Engine::Timer`](toolbox.md#timer--paced-periodic-events),
-reusing its drift-free carry-forward.
-
-- **Construct:** `Timer.new(interval, repeating: true)` (seconds). Add it named when a node
-  needs several: `node.add_component(Timer.new(0.8), as: :spawn)`. `repeating: false` makes
-  it a **one-shot** — it fires `on_timeout` exactly once, then goes inert. The one-shot
-  replaces a dedicated "lifetime" component: a projectile that should vanish after N seconds
-  on a fixed board is `Timer.new(2.0, repeating: false)` + `on_timeout { node.queue_free }`
-  (use `DespawnOffscreen` instead when the board scrolls and the entity leaves the screen).
-- **Signal:** `on_timeout` fires once per whole interval — `timer.on_timeout { spawn_enemy }`.
-- **Lifecycle:** `on_attach` restarts the countdown (and re-arms a spent one-shot), so a
-  pooled node reacquired and re-added starts fresh rather than inheriting its previous
-  life's elapsed time.
-- **Phase:** `update(dt)` advances and emits; a repeating timer emits once per interval
-  crossed in a single long step (catch-up, not drift), a one-shot at most once. Allocation-free.
-- **Reset:** `reset` drops accumulated time and re-arms a one-shot — a fresh timer.
+### `CameraFollow`
 
-### `Pool`
+**Points a camera at the node it is attached to.**
 
-Wraps an [`RGame::Engine::Pool`](toolbox.md#pool--reuse-dont-allocate) of nodes and folds the
-tree bookkeeping into the frame tick, so a scene that recycles entities (enemies, projectiles)
-writes no acquire/add/reclaim bridge of its own — just `spawn` and the ordinary `queue_free`.
-Pooled nodes are **normal children** of the owner, so the scene's usual traversal updates and
-draws them; this component only manages their pool membership.
-
-- **Construct:** `Pool.new { Enemy.new(...) }` — the factory builds a blank node. Add it named
-  (`as:`) when a node needs more than one pool.
-- **Spawn:** `pool.spawn` takes a node (recycled or freshly built) and adds it as a child;
-  `pool.spawn { |n| n.reset(...) }` runs the block to re-initialise it *before* it enters the
-  tree (so `on_attach` sees the reset state — the order projectiles need).
-- **Reclaim:** `update(dt)` returns every freed pooled node to the free list, detaching any
-  still attached. So despawning is just `node.queue_free` anywhere; the pool recycles it with
-  no game-side wiring. Allocation-free in steady state.
+- **Construct:** `CameraFollow.new(camera:, offset_x: 0.0, offset_y: 0.0)`. The
+  offsets shift the point the camera centres on, for a node whose origin should not
+  sit mid-screen. A bottom-anchored sprite usually wants its feet centred.
+- **Phase:** `update(dt)` calls `camera.center_on` with the node's world origin.
+  The camera trails the node's movement by one step, uniformly.
+- **Example:** `examples/scroll_map`. The followed node is an invisible rig with a
+  `CharacterBody` and a `PlayerController`. That is all "scroll the map with the
+  arrow keys" takes.
 
-### `ScreenWrap`
+**The camera belongs to a [player](input.md#players-seats-and-joining)**, not to
+this component or the scene, because a scene may have any number of viewers. The
+player owns the camera; this component moves it. "Player two's camera follows
+player two" is this component holding player two's camera.
 
-Wraps the node's position toroidally within a rectangle, so an entity leaving one edge
-reappears on the opposite one.
+### `CharacterBody`
 
-- **Construct:** `ScreenWrap.new(width:, height:, margin: 0.0)` — `margin` lets a
-  sprite pass fully off one edge before reappearing on the other.
-- **Phase:** `update(dt)` clamps-and-wraps `node.x`/`node.y` against the bounds.
+**Direct, per-step walking for an actor.** A controller writes a movement intent,
+each axis −1..1. The body turns it into a move each `update`, at a fixed speed with
+no inertia. `Velocity`, by contrast, integrates a velocity the controller sets, and
+`ThrustController` accelerates one.
 
-### `DespawnOffscreen`
+A character is a `CharacterBody` plus a controller. A character the map stops adds
+a feet box and a declaration. **[`Mover`](#mover) decides what may stop a step**,
+for `Velocity` and `PathFollow` too. `blocked_by:`, `on_blocked`, `on_unblocked`
+and the `apply_move` seam are documented there, and work the same way here.
 
-Removes the node once it has fully left the bounds (plus margin) — for short-lived
-entities like projectiles.
+```ruby
+add_component(RGame::Engine::Components::AnimatedSprite.new(sheet: 'hero.json'))
+add_component(RGame::Engine::Components::FeetCollider.new(width: 12, height: 6))
+add_component(RGame::Engine::Components::CharacterBody.new(speed: 80, blocked_by: [:tiles]))
+add_component(RGame::Engine::Components::PlayerController.new)
+```
 
-- **Construct:** `DespawnOffscreen.new(width:, height:, margin: 0.0)`.
-- **Phase:** `update(dt)` calls `node.queue_free` when the node is past every edge.
-  Removal is *deferred* (see [deferred free](scene_graph.md#deferred-free)), so it is
-  safe to trigger from inside the update traversal. For a *fixed* board (an entity that
-  never leaves the screen, e.g. a projectile that should vanish after N seconds), use a
-  one-shot [`Timer`](#timer) (`repeating: false`) with `on_timeout { node.queue_free }`
-  instead.
+- **Construct:** `CharacterBody.new(speed:, blocked_by: [])`: walk speed in px/s,
+  and what may stop a step (see [`Mover`](#mover)).
+- **State:** `set_intent(x, y)` writes the step's intent. `move_x` and `move_y`
+  read it back, and so do `heading_x` and `heading_y`. A body pressed into a wall
+  still heads into it.
+- **Phase:** `update(dt)` applies `intent * speed * dt` through `apply_move`, and
+  moves nothing when the intent is zero. That still counts as a step, so a body
+  that stops pushing into a wall reports `on_unblocked`.
+- **Seam:** a body that resolves a step differently, such as a platformer's with
+  gravity and a jump, overrides [`apply_move`](#mover). It inherits the intent, the
+  speed and the standing-still check.
+- **Examples:** `examples/walk` uses this, a `PlayerController` and an
+  `AnimatedSprite`, and nothing else. `examples/collision_tiles` adds a feet box and
+  `blocked_by: [:tiles]`, and draws the box over the sprite so you can see what
+  collides. A crowd adds more names: walkers that each declare
+  `%i[tiles hero npc]` are stopped by the map and by one another.
 
 ### `CircleCollider`
 
-A circular collision shape that participates in a scene's
-[`CollisionWorld`](#collisionworld). It registers itself when the node enters the tree
-and unregisters when it leaves, so a spawned or despawned entity never leaks a
-registration.
-
-- **Construct:** `CircleCollider.new(radius:, layer: :default)`. `layer` is an opaque
-  tag the *owner* reads to decide what a contact means; the collision system itself is
-  layer-agnostic.
-- **Lifecycle:** `on_attach` registers with `node.system(CollisionWorld)`; `on_detach`
-  unregisters.
-- **Geometry:** `cx`/`cy` are the node's resolved absolute origin; `radius` is a
-  read/write accessor (so a pooled entity can retune its shape on reset — see
-  `ScreenWrap`/pooling), `layer` is a reader; `overlap?(other)` is the circle-vs-circle
-  test.
-- **Signal:** `on_hit` fires with the other collider on each contact —
-  `collider.on_hit { |other| ... }`. The system triggers it via `emit_hit(other)`.
+**A circular collision shape in a scene's [`CollisionWorld`](#collisionworld).** It
+registers when the node enters the tree and unregisters when it leaves, so spawning
+and despawning never leak a registration.
+
+- **Construct:** `CircleCollider.new(radius:, layer: :default)`. `layer` is an
+  opaque tag. The *owner* reads it to decide what a contact means; the collision
+  system ignores it.
+- **Lifecycle:** `on_attach` registers with `node.system(CollisionWorld)`, and
+  `on_detach` unregisters. As with [`BoxCollider`](#boxcollider), a scene with no
+  world leaves it a bare shape, without raising.
+- **Geometry:** `cx` and `cy` are the node's world origin (`node.world_x`,
+  `world_y`). `radius` is read/write, so a pooled entity can retune its shape on
+  reset. `layer` is a reader. `aabb_x`, `aabb_y`, `aabb_w` and `aabb_h` give the
+  bounding box the world buckets on.
+- **Contacts:** `overlap?(other)` works against a circle *or* a
+  [`BoxCollider`](#boxcollider). The two colliders settle the test between
+  themselves, so both shapes mix freely in one world.
+- **It never blocks.** Blocking is box against box. A circle on a layer that a
+  [`Mover`](#mover) named in `blocked_by:` reports contacts as usual and stops
+  nobody. Nor can a circle *be* stopped. A mover that declares anything needs a
+  `BoxCollider` of its own, and raises at attach without one. The first rule is a
+  limit, not a check: layer membership is a runtime fact, so a raise at attach
+  would catch only circles that already existed.
+- **Signals:** `on_hit` fires with the other collider on the step a contact
+  **starts**, and `on_separated` on the step it **ends**:
+  `collider.on_hit { |other| ... }`. The system triggers them through
+  `emit_hit(other)` and `emit_separated(other)`. Each fires once per pair; see
+  [`CollisionWorld`](#collisionworld).
 
 ### `CollisionWorld`
 
-A scene-scoped broadphase collision **system**: a component that lives on the scene
-node, holds the registered colliders in a `SpatialHash`, and each step reports every
-overlapping pair. Because it is a normal component it rides the `update` traversal and
-is torn down with the scene. See [Systems & shared resources](systems.md).
-
-- **Construct:** `CollisionWorld.new(cell_size:)` — the spatial-hash cell size (tune to
-  the typical collider size).
-- **Registration:** `register(collider)` / `unregister(collider)`; colliders call these
-  through their own lifecycle, so nodes never wire this by hand.
-- **Phase:** `update(dt)` rebuilds the spatial index and, for each overlapping pair,
-  fires both colliders' `on_hit`. It is **layer-agnostic** — it reports contacts and
-  lets each collider's owner decide meaning by reading the other's `layer`. Colliders
-  whose node is queued for removal are skipped.
-- **Range queries (targeting):** the same index answers point-radius lookups against the
-  most recent `update`, so a tower can find enemies without a contact:
-  - `query_circle(x, y, r) { |collider| }` yields every registered collider whose centre
-    is within `r` of `(x, y)` (centre distance — the collider's own radius isn't added,
-    so it reads like a range ring); freed-node colliders are skipped, and a collider may
-    be yielded more than once (broadphase dedup contract — fine for selecting). Filter by
-    `collider.layer` in the block.
-  - `nearest(x, y, r, layer: nil)` returns the closest such collider (optionally limited
-    to one `layer`), or `nil`. Both are allocation-free, so a targeting component can call
-    them every frame.
+**A scene-scoped broadphase collision system.** The component lives on the scene
+node, holds the registered colliders in a `SpatialHash`, and reports each step
+where overlapping pairs begin and end. As a normal component, it runs in the
+`update` traversal and goes away with the scene. See
+[Systems & shared resources](systems.md).
+
+**It ignores shape.** It buckets each collider by its reported bounding box
+(`aabb_x`, `aabb_y`, `aabb_w`, `aabb_h`) and leaves the exact test to the pair's own
+`overlap?`. [`CircleCollider`](#circlecollider) and [`BoxCollider`](#boxcollider)
+therefore share one world and collide with each other. A game can add its own
+shape by answering the same few methods.
+
+- **Construct:** `CollisionWorld.new(cell_size:)`, the spatial hash's cell size.
+  **Size it to the colliders**, and nothing else. A tile map in the same scene is
+  no guide. A 64px collider in 16px cells lands in twenty-five cells and is queried
+  from all of them. That measured 2.8× the cost of a cell sized to the collider. A
+  12×6 feet box in the same 16px cells costs only 10–20% over its own optimum. A
+  wrong value costs frame time, never correctness, so pick it deliberately.
+- **Registration:** `register(collider)` and `unregister(collider)`. Colliders call
+  these through their own lifecycle, so nodes never wire them.
+- **Queries:** `query_box(x, y, w, h)` yields every registered collider bucketed in
+  a cell the region covers. It skips nodes queued for removal. It is the
+  rectangular form of `query_circle`, and a blocked [`Mover`](#mover) asks it each
+  step. `nearest(x, y, r, layer:)` and `cell_empty?(x, y)` complete the set. All of
+  them read the index the most recent `update` built, and allocate nothing.
+- **Staying current mid-step:** `reindex(collider, from_x, from_y, from_w, from_h)`
+  re-buckets a collider that moved after the index was built, given the box it
+  *was* bucketed at. Buckets fill once per step, so a query over cells a mover left
+  would miss it. With two hundred actors, that measured 116 misses in 60,000
+  queries, and none once each mover re-bucketed itself. A [`Mover`](#mover) that
+  declares a collider layer does this through its resolver. Anything else that
+  moves a collider mid-step may call it directly: a mover that declared nothing, or
+  an ancestor.
+- **Phase:** `update(dt)` rebuilds the spatial index. It fires both colliders'
+  `on_hit` for each pair that *started* overlapping, then both colliders'
+  `on_separated` for each pair that *stopped*. It **ignores layers**: it reports
+  contacts, and each owner decides their meaning by reading the other's `layer`. It
+  skips colliders whose node is queued for removal.
+- **Contacts arrive one step late.** This component sits on the scene node, and a
+  node runs its components before its children. The world builds the index and
+  reports every pair *before* any actor moves this step. Contacts therefore
+  describe where things stood at the end of the previous step. The delay is
+  consistent, so nothing jitters, but a pair that starts overlapping during step N
+  is reported at the start of step N+1. A blocked [`Mover`](#mover) does not read
+  the index this way and is unaffected. It queries mid-step and re-buckets itself,
+  through `reindex` above.
+- **A contact is two edges, not a state.** Each signal fires **once per pair**.
+  Nothing fires on the steps between, however long the overlap lasts, and a pair
+  spanning several cells reports once. A handler may therefore do what must happen
+  exactly once, such as `score += 100`, playing a sound or spending a life, with
+  nothing to guard. `examples/collision`'s crate counts arrivals in one line thanks
+  to this.
+
+  The world keeps an
+  [`Engine::ContactSet`](internals.md#contactset--the-two-edges-of-a-contact) per
+  collider for this. The set also absorbs the
+  [`SpatialHash`](internals.md#spatialhash--uniform-grid-broadphase) may-yield-twice
+  contract: a pair spanning three cells is offered three times and recorded once.
+- **`on_separated` also fires when the partner goes.** A contact ends when the
+  partner is destroyed (`queue_free`) or leaves the tree, not only when the two move
+  apart. The survivor hears about it on its next step. Otherwise a ship could stay
+  "in contact" with a rock that no longer exists. The departing collider hears
+  nothing, because it is leaving.
+
+  **Remember that last point when pooling.** The world clears a collider's own
+  contacts when it registers, so a recycled entity never reports a separation from
+  its previous life. But state a *node* derived from those contacts, such as a "how
+  many things am I touching" count, never unwinds. The edge that would unwind it
+  never arrived. Zero that state in the node's `reset`, with the rest.
+- **Example:** `examples/collision` puts this system on the scene, circles and boxes
+  on the nodes, two layers, and one line that ignores same-layer pairs. A circle
+  stays lit while inside a crate (`on_hit` on, `on_separated` off), and the crate
+  blinks once and counts it. The backdrop draws the broadphase grid, so you can see
+  `cell_size`.
+- **Range queries (targeting):** the same index answers point-radius lookups
+  against the most recent `update`. A turret can find enemies without a contact:
+  - `query_circle(x, y, r) { |collider| }` yields every registered collider whose
+    centre lies within `r` of `(x, y)`. It measures centre distance and does not add
+    the collider's size, so it reads like a range ring. It skips freed nodes'
+    colliders, and may yield a collider more than once, which is fine for selecting.
+    Filter by `collider.layer` in the block.
+  - `nearest(x, y, r, layer: nil)` returns the closest such collider, optionally
+    limited to one `layer`, or `nil`. Both allocate nothing, so a targeting
+    component can call them every frame.
+- **Cell occupancy (grid games):** `cell_empty?(x, y)` answers whether the cell
+  containing the **world** point `(x, y)` is free, for questions like "may a pickup
+  spawn on this square?". It takes a point, not a region; pass any coordinate inside
+  the square you mean. Set `cell_size` to the game's own square so the two grids
+  line up. The cells form the hash's own lattice, anchored at the world origin. A
+  board should therefore put its origin on a multiple of `cell_size`. Off that
+  lattice, each square straddles two cells and both read occupied. Like the queries
+  above, it reads the index the last `update` built. It allocates nothing, even on a
+  miss, which is what a board scan asks most.
+
+  A collider whose node is queued for removal does not occupy a cell, so a corpse
+  cannot reserve a square. The rest is
+  [`SpatialHash#cell_empty?`](internals.md#spatialhash--uniform-grid-broadphase).
+  Its cell walk is half-open on the far edge, so a piece filling one square leaves
+  its neighbours free.
+
+  It takes *world* coordinates, because colliders report those. A node whose grid
+  starts elsewhere adds its origin first:
+
+  ```ruby
+  # in a Grid node whose cells are cell_size across
+  def free?(col, row)
+    collisions = system(RGame::Engine::Components::CollisionWorld)
+    collisions.cell_empty?(world_x + (col * cell_size), world_y + (row * cell_size))
+  end
+  ```
 
-### `Targeting`
+### `DespawnOffscreen`
 
-Picks an enemy for the owning node (a tower) to aim at: each `update` it queries the
-scene's [`CollisionWorld`](#collisionworld) around the node's world origin and exposes the
-chosen target. It only *selects* — it never moves or fires; the owner reads `target` and
-acts. Because enemies already register with the broadphase through their
-[`CircleCollider`](#circlecollider), targeting keeps no entity list of its own.
-
-- **Construct:** `Targeting.new(range:, policy: :nearest, layer: nil)`. `range` is the
-  reach in pixels; `layer` restricts candidates (a tower passes `:enemy`, so it ignores
-  other towers/projectiles); an unknown `policy` raises at construction.
-- **Policies** (how to choose among the in-range candidates):
-  - `:nearest` — the closest enemy (the default; one broadphase nearest-lookup).
-- **State:** `target` is the chosen enemy **node** (or `nil` when nothing is in range),
-  refreshed every `update` — so a freed/out-of-range target clears on its own. It's a node
-  (not a collider) so the owner can read its position and components.
-- **Lifecycle:** `on_attach` pulls the scene's `CollisionWorld`.
-- **Phase:** `update(dt)` re-selects the target; allocation-free, so it runs every frame.
+**Removes the node once its origin passes an edge of the world bounds by more than
+`margin`.** Use it for short-lived entities like projectiles. The margin stands in
+for the node's size: a node drawn centred on its origin has fully left once the
+margin reaches half its extent.
+
+- **Construct:** `DespawnOffscreen.new(margin: 0.0)`, with the same optional
+  `width:` and `height:` override as `ScreenWrap`.
+- **Lifecycle:** `on_attach` resolves the bounds, exactly as `ScreenWrap` does.
+- **Phase:** `update(dt)` calls `node.queue_free` once the node's **world**
+  position passes an edge. A projectile spawned as a child of an offset emitter
+  leaves at the world's edge, not at an edge shifted by the emitter's position.
+  Removal is *deferred* (see [deferred free](scene_graph.md#deferred-free)), so
+  triggering it inside the update traversal is safe. For an entity that never
+  leaves a *fixed* board, such as a projectile that should vanish after N seconds,
+  use a one-shot [`Timer`](#timer) (`repeating: false`) with
+  `on_timeout { node.queue_free }` instead.
+- **One response to the edge per node.** It raises at attach beside a `ScreenWrap`
+  or a mover declaring `blocked_by: [:bounds]`; see
+  [`WorldBounds.one_response!`](#world).
+
+### `FeetCollider`
+
+**A [`BoxCollider`](#boxcollider) whose rectangle is the node's feet**: centred
+horizontally in the node's dimensions and anchored to their bottom. A top-down
+character should collide with this shape. A 16×22 hero occupies the 12×6 patch
+under them, not the whole sprite, so their head does not bump a wall a tile away. In
+every other respect it is a `BoxCollider`: same registration, same signals, same
+mixing with circles. `get_component(BoxCollider)` finds it.
+
+- **Construct:** `FeetCollider.new(width:, height:, layer: :default)`, the feet box
+  size in px. It takes no sprite size and no offsets. Those come from `node.width`
+  and `node.height`, which [`AnimatedSprite`](#animatedsprite) sets from the sprite
+  frame, so box and sprite never disagree. A node without a sprite sets its own
+  dimensions.
+- **Geometry:** the collider builds `box` on **first read** and keeps it, not at
+  construction. A node has no size until its sprite attaches, so add order never
+  matters. Reading `box` from a 0×0 node **raises**, naming the size. The
+  alternative would be a box anchored to nothing, and an actor walking through walls
+  far from the cause. Assigning `box =` still takes priority, which lets a pooled
+  entity retune its shape on reset.
+- **Everything else:** as [`BoxCollider`](#boxcollider): `aabb_*`, `cx` and `cy`,
+  `overlap?`, `on_hit` and `on_separated`, and registration with the scene's
+  [`CollisionWorld`](#collisionworld) when one exists.
+
+A blocked [`CharacterBody`](#characterbody) resolves its steps against this same
+shape, so one component carries the feet box for both jobs.
+`examples/collision_tiles` mounts no `CollisionWorld` at all, and uses the collider
+only as the rectangle a step may not push past.
 
-### `Sprite`
+```ruby
+add_component(RGame::Engine::Components::AnimatedSprite.new(sheet: 'hero.json'))
+feet = add_component(RGame::Engine::Components::FeetCollider.new(
+  width: 12, height: 6, layer: :hero
+))
+feet.on_hit { |other| take_damage if other.layer == :spike }
+```
 
-Draws a single registered image centered on the node's absolute origin.
+### `Hop`
+
+**A jump in a top-down view.** The node's picture rises along a parabola and comes
+back down. The node itself stays on the ground, and so does every collider, camera
+and child that reads its position.
+
+- **Construct:** `Hop.new(peak:, duration:, action: :jump)`. `peak` is the highest
+  the picture rises, in px, reached halfway through `duration` seconds. Both must be
+  positive, or the constructor raises `ArgumentError`. `action` names the action
+  whose **press edge** starts a hop, so holding it hops once. `action: nil` reads no
+  input.
+- **State:** `height` (px above the ground now), `airborne?`, `peak`, `duration`.
+- **Starting one:** press `action` during `control`, or call `jump`. `jump` does
+  nothing while a hop is under way. NPCs and scripts call it.
+- **Phase:** `update(dt)` advances the arc and writes the height to
+  [`node.elevation`](scene_graph.md#elevation). [`AnimatedSprite`](#animatedsprite)
+  and [`Sprite`](#sprite) draw lifted by it. The arc depends on the time accumulated
+  in `update`, never on a clock, so a paused node hangs in the air.
+- **Lifecycle:** `on_attach` lands the node, so a pooled node reused mid-hop starts
+  on the ground.
+
+**The game decides what a hop crosses.** `Hop` knows nothing about tiles or
+colliders. A [`CharacterBody`](#characterbody) blocked by a wall stays blocked while
+its node is in the air. A game whose chasm tiles should be passable mid-hop reads
+`airborne?` where it decides what is solid.
 
-- **Construct:** `Sprite.new(id:, scale: 1.0, z: 0)` — `id` is a renderer image id; `z`
-  orders this component against the node's *other* drawing (a shadow under a sprite),
-  inside the node's own slot. It is not the node's `z`, which orders the node against
-  its siblings. See [Drawing](drawing.md#draw-order).
-- **State:** `scale` is a read/write accessor (a pooled entity can retune it).
-- **Phase:** `draw(renderer, view)` draws the image with **no angle** — `Node2D#draw`
-  already wraps a node's own draws in `renderer.rotated(abs_angle, …)`, so the node's
-  rotation orients the sprite; passing an angle here would rotate it twice. It skips the
-  draw entirely when the view cannot show it, measuring the node's box scaled — a node
-  that never set a size is never culled.
+```ruby
+hop = add_component(RGame::Engine::Components::Hop.new(peak: 18, duration: 0.5))
+hop.airborne? # => false — until the :jump action is pressed
+```
 
-### `CameraFollow`
+`examples/jump_topdown` draws the shadow and the feet box that stay on the ground
+under the picture.
 
-Points a camera at the node it is attached to.
+### `Identity`
 
-- **Construct:** `CameraFollow.new(camera:, offset_x: 0.0, offset_y: 0.0)` — the offsets
-  shift the point being centred on, for a node whose origin is not what should be in the
-  middle of the screen (a bottom-anchored sprite usually wants its feet).
-- **Phase:** `update(dt)` calls `camera.center_on` with the node's resolved absolute
-  origin. The camera trails the node's own movement by one step, uniformly.
+**A stable name for one node**, so something outside the tree can refer to it.
 
-The camera belongs to a [player](input.md#players-seats-and-joining), not to this
-component or to the scene — a scene may have any number of viewers. Ownership and
-behaviour are different questions: the player owns the camera, and this moves it. So
-"player two's camera follows player two" is this component with their camera in it.
+```ruby
+sheep.add_component(RGame::Engine::Components::Identity.new(id: 7))
+RGame::Engine::Components::Identity.of(sheep)   # => 7
+```
 
-### `ThrustController`
+- **Construct:** `Identity.new(id:)`, with any object; `nil` raises.
+- **Read:** `#id`, or `Identity.of(node)`. `of` returns `nil` for a node without an
+  identity, and for no node at all.
+- **Phase:** none. It holds a value and does nothing per frame.
 
-Inertial "ship" flight on top of a `Velocity` sibling: a turn axis rotates the node and
-a thrust axis accelerates it along its heading.
+**Most saving needs no identity.** A scene is a recipe and a save file is state. A
+*singular* thing is named by the variable that holds it. *Interchangeable* things
+are named by their order in an array. `examples/save_load` restores a dog and a
+flock with exactly those two and nothing else. `examples/save_load_ids` needs this
+component.
 
-- **Construct:** `ThrustController.new(turn_speed:, accel:, max_speed:, drag: 0.0,
-  turn_action: :turn, thrust_action: :thrust)`.
-- **Lifecycle:** `on_attach` pulls the node's `Velocity` component.
-- **Phase:** `control(actions)` reads intent (turn → `velocity.spin`, thrust stored);
-  `update(dt)` accelerates along the heading (angle 0 = up, so forward is
-  `(sin θ, −cos θ)`), applies drag, and clamps to `max_speed`. Firing is intentionally
-  not here.
+`Identity` covers two cases the others miss:
 
-### `ActionTrigger`
+- **A collection whose members can die.** An array index names nothing once a
+  middle member is gone.
+- **A reference from one saved thing to another**, such as a dog chasing one
+  particular sheep. This case truly forces ids. A collection can be respawned from
+  its own records, but a reference into it needs a name for its target.
+  `Targeting#target` shows the problem: it holds a *node*, and `Identity.of` turns
+  that into something a file can hold.
 
-Maps held input actions to an `on_triggered(action)` signal, rate-limited by a per-action
-cooldown. One instance covers several actions (the engine allows one component per class
-per node), so it emits the action name and lets listeners filter — reusable for "fire"
-here, or "jump"/"fire" in a platformer.
+The game must get two things right; this component does not check them:
 
-- **Construct:** `ActionTrigger.new(cooldowns)` where `cooldowns` is `{ action => seconds }`,
-  e.g. `ActionTrigger.new(fire: 0.22)`.
-- **Signal:** `on_triggered` fires with the action name — `trigger.on_triggered { |a| … }`.
-- **Phase:** `update(dt)` ticks the per-action cooldowns; `control(actions)` emits when an
-  action is held and its cooldown has elapsed (held + cooldown = auto-repeat).
+- **Ids must be unique** among things that can refer to each other. A duplicate
+  restores the wrong object, silently.
+- **The id allocator belongs in the save.** A counter that restarts at 1 on load
+  reissues ids the restored objects already hold. Save the next id with them.
 
-### `AnimatedSprite`
+### `Mover`
 
-Draws a sprite-sheet animation and picks the animation from a [`CharacterBody`](#characterbody)
-sibling's movement: `walk_left`/`walk_right`/`walk_up`/`walk_down` while moving (horizontal wins
-on a diagonal), `stand` when still. Owns an `RGame::Engine::Animator` over the pure `AnimationSet` built
-from the sheet's animation table.
+**The base class of every component that moves its node**:
+[`CharacterBody`](#characterbody), [`Velocity`](#velocity) and
+[`PathFollow`](#pathfollow). Walking an intent, integrating a velocity and following
+a path are three different jobs, so they are three classes. They share what happens
+*after* a step is computed, and `Mover` holds that part. You never add a `Mover` on
+its own.
 
-- **Construct:** `AnimatedSprite.new(sheet:, z: 0)` — `sheet` is the asset's relative path; `z`
-  orders this component against the node's other drawing, inside the node's own slot (as
-  for [`Sprite`](#sprite)).
-- **Lifecycle:** `on_attach` resolves the sheet from the game's asset manager
-  (`node.root.context.assets.sheet(sheet)`), builds its animation set, **sizes the node** to the
-  sheet's frame (`node.width`/`height`, so a `CharacterBody` sibling can read them), and pulls that
-  sibling (the facing source). The renderer resolves the same path when drawing, so nothing is
-  registered or passed in by hand.
-- **Phase:** `update(dt)` selects + advances the animation; `draw(renderer, view)` renders the
-  current frame via `renderer.sprite` at the node's **world** origin (`abs_x`/`abs_y`) with no
-  angle — a [`WorldView`](scene_graph.md#view-transforms-and-the-camera) ancestor applies the
-  camera offset, so the component never touches the camera. It skips the draw when the view
-  cannot show it, measuring the node's box. (`Sprite` above is the single-image counterpart.)
+**A mover declares what stops a step; it does not subclass for it.**
+`blocked_by:` lists what a step may not pass through. The default is nothing. Then
+the mover writes the node's position directly, and needs **no sprite, no
+dimensions, no collider and no system on the scene**.
 
-### `CharacterBody`
+```ruby
+add_component(RGame::Engine::Components::BoxCollider.new(width: 12, height: 12, layer: :crate))
+add_component(RGame::Engine::Components::Velocity.new(vx: 90, vy: 40, blocked_by: [:wall]))
+```
+
+Two names are reserved, and every other name is a collider layer:
+
+| Name | Resolved against | Stops the step at |
+|---|---|---|
+| `:tiles` | the scene's [`TileWorld`](#tileworld) | the edge of a solid tile |
+| `:bounds` | the scene's [`WorldBounds`](#world) | the edge of the world |
+| anything else | the scene's [`CollisionWorld`](#collisionworld) | the edge of any `BoxCollider` wearing that layer |
+
+**Each step resolves one axis at a time and takes the most restrictive answer.** A
+diagonal held against a wall keeps its free half, so the mover slides. It slides
+off a villager exactly as off a fence. A character wants that; a bullet does not,
+but needs no separate resolver. `on_blocked` fires on the step the bullet hits, and
+a bullet that frees itself there is gone before it slides. A mover that keeps
+pushing also keeps its intent: a blocked `Velocity` does not zero its `vx`. A bullet
+that bounces reads which axis stopped, and reverses that half of its velocity:
+
+```ruby
+velocity = RGame::Engine::Components::Velocity.new(vx: 120, vy: 80, blocked_by: %i[wall bounds])
+velocity.on_blocked do |_by, axis|
+  velocity.vx = -velocity.vx unless axis == :y
+  velocity.vy = -velocity.vy unless axis == :x
+end
+```
 
-Collision-checked walking for a tile-bound actor. A controller writes a per-step movement intent
-(each axis −1..1); the body turns it into a real move each `update`, resolved against the scene's
-[`TileWorld`](#tileworld) so the actor slides along walls and stays in the map. Unlike `Velocity`
-(which integrates blindly), every step here is collision-checked.
-
-- **Construct:** `CharacterBody.new(feet_width:, feet_height:, speed:)` — the feet box size (in px)
-  and walk speed (px/s). No sprite size is passed: `collision_box` is built lazily from the node's
-  `width`/`height` (which `AnimatedSprite` sets), centred horizontally and bottom-anchored. A body
-  with no sprite must set the node's dimensions itself.
-- **State:** `set_intent(x, y)` writes the step's intent; `move_x`/`move_y` read it back (the facing
-  for `AnimatedSprite`).
-- **Lifecycle:** `on_attach` caches the scene's `TileWorld`.
-- **Phase:** `update(dt)` moves `intent * speed * dt` through the tile world (nothing when the
-  intent is zero).
+```ruby
+add_component(RGame::Engine::Components::FeetCollider.new(width: 12, height: 6, layer: :hero))
+add_component(RGame::Engine::Components::CharacterBody.new(speed: 80, blocked_by: %i[tiles npc]))
+```
+
+Three rules apply to layer names:
+
+- **An empty layer is not an error.** The declaration says what *may* stop this
+  mover, not what does.
+- **A mover is never stopped by its own collider.** A crowd of villagers can all
+  declare `blocked_by: [:npc]` while each wears `:npc`.
+- **Blocking is box against box.** A [`CircleCollider`](#circlecollider) on a
+  declared layer reports contacts as usual and stops nothing.
+
+`blocked_by` and [`on_hit`](#boxcollider) answer different questions: what may I
+walk through, and what am I touching? They are not alternatives. A blocked pair
+ends up *touching*, and `CollisionBox.overlap?` is half-open, so a blocked step
+reports no contact. An entity that must both stop and react needs both.
+
+**The mover reports what stopped a step.** `on_blocked` fires on the step something
+starts stopping the mover, and `on_unblocked` on the step it stops doing so. Each
+fires once per blocker. `BoxCollider` reports contacts with the same pair of edges,
+here aimed at what a step could not pass. A spiky ball that both stops the player and
+hurts them is thus two ordinary components, not a hand-written `on_hit`.
+
+```ruby
+mover.on_blocked { |by| take_damage if by.layer == :spike }
+```
+
+The listener receives the blocker and reads `by.layer` and `by.node`, whatever kind
+stopped the step. A collider answers its own layer and owning node. The map's solid
+tiles answer `:tiles` and `nil`. The world's edge answers `:bounds` and `nil`. The
+second argument is the stopped axis: `:x`, `:y` or `:both`. A listener that names
+only the blocker never sees it. Three details matter:
+
+- **Standing still counts as unblocking.** The set of blockers advances once per
+  `update`. A mover that stops pushing records nothing that step, so `on_unblocked`
+  fires. The mover has not moved; it has stopped *being stopped*.
+- **Once per blocker, not once per axis.** A step stopped on both axes by one thing
+  fires once, with `:both`. Only the map produces that, with a diagonal into an
+  inside corner of solid tiles. A step resolves X first, and once X is flush, a
+  single collider no longer overlaps on Y. A step stopped on X by the map and on Y
+  by a villager fires twice, each with its own axis. Starting edges come before
+  ending ones, the order `CollisionWorld` uses for contacts. A blocker that stops X
+  on one step and Y on the next stood in the way throughout. It fires once, with the
+  axis it first stopped. `on_unblocked` carries no axis for the same reason.
+- **A blocked pair is not a contact**, as the paragraph above explains. The spiky
+  ball listens to `on_blocked`; a trigger area listens to `on_hit`.
+
+**`:bounds` must be declared.** A mover that does not name it leaves the world.
+Stopping at the edge is one of three responses to it, beside
+[`ScreenWrap`](#screenwrap) and [`DespawnOffscreen`](#despawnoffscreen), and a node
+may carry only one. Declaring `:bounds` beside either raises at attach. A game whose
+entities wrap or despawn at the edge gives their movers no `:bounds`.
+`blocked_by?(name)` answers whether a mover declared a name.
+
+**The shape has one owner, and it is not the mover.** A blocked step resolves
+against the sibling [`BoxCollider`](#boxcollider)'s rectangle;
+[`FeetCollider`](#feetcollider) suits a walking character. You give the box once,
+to the component that *is* a shape. The same rectangle stops the step and reports
+contacts. Reassigning `collider.box` retunes both, and no component hands data to
+another.
+
+- **Construct:** every mover takes `blocked_by: []`. A bare Symbol also works
+  (`blocked_by: :tiles`).
+- **Lifecycle:** `on_attach` resolves the declarations and builds the mover's own
+  [`CollisionSystem`](internals.md#collisionsystem--move-an-actor-against-its-blockers)
+  from the sources it finds. It **raises** for anything missing. It checks the
+  node's collider first, then the scene's `TileWorld` for `:tiles`, its `WorldBounds`
+  for `:bounds`, and its `CollisionWorld` for any layer name. Falling back to free
+  movement would look like a collision bug, caused by a scene three files away that
+  never mounted the system.
+- **Signals:** `on_blocked` fires with what stopped the step and the stopped axis.
+  `on_unblocked` fires with what stopped stopping it:
+  `mover.on_blocked { |by, axis| ... }`, `mover.on_unblocked { |by| ... }`.
+- **Phase:** `update(dt)` opens the step, calls the subclass's private
+  `take_step(dt)`, and reports the edges. Do not override it; it guarantees that no
+  mover forgets an edge.
+- **Heading:** `heading_x` and `heading_y` give the step's direction, each axis in
+  -1..1, and `0, 0` when the mover is not trying to move.
+  [`AnimatedSprite`](#animatedsprite) faces by it. It is a facing, not a velocity: a
+  mover pressed into a wall still heads into it. A [`CharacterBody`](#characterbody)
+  answers its intent. A [`Velocity`](#velocity) answers its velocity, scaled so the
+  larger axis is ±1. A [`PathFollow`](#pathfollow) answers the unit direction of its
+  current segment. Reading it allocates nothing.
+- **Seam:** `apply_move(dx, dy)` lands a step. With nothing declared, it writes
+  straight onto the node. With declarations, it goes through the resolver. A mover
+  may call it several times in one step, and still reports the edges once.
+- **Actor adapter:** when blocked, the mover passes *itself* to
+  [`CollisionSystem#move`](internals.md#collisionsystem--move-an-actor-against-its-blockers).
+  It answers `collision_box` from the collider, and `x`, `y`, `x=` and `y=` from the
+  node **in world space**, the frame the tile grid and broadphase use. Writing back
+  translates the node's local position. That is exact under an unrotated ancestor
+  chain and approximate under a rotated one. A spinning thing wants a circle anyway.
+
+### `Navigator`
+
+**A [`PathFollow`](#pathfollow) that plans its own paths.** `go_to(world_x, world_y)`
+finds a route over the scene's [`TileWorld`](#tileworld) to the tile containing that
+point. It smooths the route into as few straight segments as the node's collider can
+travel, and walks it.
+
+```ruby
+# `actors` is the node TileMapLayer.mount returned, in a scene with a TileWorld mounted.
+hero = RGame::Engine::Node2D.new(x: 40, y: 40)
+hero.add_component(RGame::Engine::Components::AnimatedSprite.new(sheet: 'hero.json'))
+hero.add_component(RGame::Engine::Components::FeetCollider.new(width: 12, height: 6))
+navigator = hero.add_component(RGame::Engine::Components::Navigator.new(speed: 80, blocked_by: [:tiles]))
+actors.add_node(hero)
+
+navigator.go_to(200.0, 360.0) # => true — the hero sets off; false when there is no route
+```
+
+- **Construct:** `Navigator.new(speed:, blocked_by: [])`. It takes no `path:` and
+  stays idle until the first `go_to`. [`Mover`](#mover) decides what may stop it. A
+  navigator that should stay off solid tiles while walking declares `:tiles`, like
+  any mover.
+- **Lifecycle:** `on_attach` raises when the scene has no `TileWorld` to plan over.
+  It also looks up the node's `BoxCollider`, if any. Calling `go_to` before the
+  node is in the tree raises too.
+- **`go_to(world_x, world_y)`** plans from where the node stands and starts walking
+  at once, from exactly there. A navigator halfway along one route turns onto the
+  next without a jump. It returns `true`, or `false` when no route exists: the
+  target is solid, outside the map, or in a part the node cannot reach. On `false`
+  nothing changes, and a walk under way continues. `on_finished` never fires inside
+  `go_to`, even for a target in the node's own cell; it fires on the next step.
+- **The anchor.** The centre of the collider's box reaches the target: the feet,
+  for a [`FeetCollider`](#feetcollider). On a node without a collider, the origin
+  does. The walk ends with the anchor on the centre of the target tile.
+- **Readers:** `cells` returns the route as the search found it,
+  `[[col, row], ...]` from start tile to target, or `nil` before the first `go_to`.
+  Use it to draw the route. `path` returns the smoothed
+  [`Path`](toolbox.md#path--a-walkable-polyline) the node walks, in the node's
+  coordinates, starting where the node stood.
+- **It can walk every route it plans.** Smoothing keeps a straight segment only if
+  the map's own blocker source says the collider's box can travel it. That source is
+  `TileWorld#blockers`, the one that stops a mover declaring `:tiles`, queried
+  through [`TileBlockers#travel?`](internals.md#tileblockers--the-tile-grid-as-a-blocker-source).
+  A test on tiles alone would keep a diagonal past a tree's corner that a point
+  clears but a feet box clips. A `PathFollow` held on a corner does not slide off;
+  it would stand there. `travel?` holds for a walker taking steps under a quarter
+  tile: 240 px/s at 60 ticks a second on 16 px tiles.
+- **One component, not a search beside a walker.** A navigator *is* a `PathFollow`,
+  so no component hands a route to a sibling. There is no wiring to forget, and the
+  order you add components in does not matter.
+- **Colliders up to one tile only.** Pathfinding for a collider wider or taller than
+  a tile is unsupported. Smoothing assumes the box fits the cells the search found.
+  `go_to` raises `ArgumentError`, naming the box and the tile size, instead of
+  planning a route such a walker could stall on. A collider of exactly one tile
+  works.
+- **It waits; it does not replan.** It plans against the map and knows only the
+  map. A navigator declaring other collider layers waits behind anything standing on
+  its route, as a `PathFollow` does, and resumes when the way clears. To go around
+  instead, call `go_to` again.
+- **Cost.** Planning runs when `go_to` is called, never per frame, and allocates. It
+  takes about 0.2 ms for a 65-tile route across a 60x40 map. A 117-tile route across
+  120x90 takes 1.3 ms, 1 ms of it in the search. The walk itself is `PathFollow`'s,
+  and allocates nothing.
+- **Spaces:** it plans in world space and walks in the parent's. The two agree under
+  an unrotated ancestor chain, the same limit a blocked [`Mover`](#mover) has.
+- **Example:** in `examples/pathfinding`, a tile cursor picks the target. The scene
+  draws `cells` as a dot per tile and `path` as lines. It adds the feet box's centre
+  back to each waypoint so the lines sit on the dots.
+
+### `PathFollow`
+
+**Walks the owning node along an
+[`RGame::Engine::Path`](toolbox.md#path--a-walkable-polyline) at constant speed**,
+and emits `on_finished` at the last waypoint. Hook whatever should happen on arrival
+to that signal.
+
+- **Construct:** `PathFollow.new(speed:, path: nil, blocked_by: [])`.
+  [`Mover`](#mover) decides what may stop it. Without a path, the follower is idle:
+  it moves nothing, never finishes, and heads nowhere until it receives one.
+- **Lifecycle:** `on_attach` restarts the walk. It returns to the first waypoint,
+  clears progress, and *places* the node there regardless of declarations. A pooled
+  follower acquired and added again starts a fresh walk.
+- **A new route:** `follow(path)` restarts with a different path, at any time. A
+  finished follower walks it and emits `on_finished` again. A follower halfway along
+  another route drops that route at once and is placed on the new first waypoint. You
+  may call it from an `on_finished` handler. `follow(nil)` stops the walk where it
+  stands. `path` returns the route being walked.
+
+  ```ruby
+  out  = RGame::Engine::Path.new([[40.0, 100.0], [200.0, 100.0]])
+  back = RGame::Engine::Path.new([[200.0, 100.0], [40.0, 100.0]])
+  patrol = RGame::Engine::Components::PathFollow.new(path: out, speed: 40)
+  patrol.on_finished { patrol.follow(patrol.path.equal?(out) ? back : out) }
+  ```
+- **Heading:** the unit direction of the current segment, computed as the walk
+  enters it. It is `0, 0` while idle, after finishing, and along a zero-length
+  segment.
+- **Signal:** `on_finished` fires once, without payload, at the path's end:
+  `follow.on_finished { node.queue_free }`. `finished?` reports the same state.
+- **Phase:** `update(dt)` advances `speed * dt`, crosses as many segments as one step
+  spans, and interpolates the node's position. It allocates nothing. With nothing
+  declared, it places the node on that point.
+- **When blocked, the walk waits.** With declarations, the follower moves the node
+  to that point through `apply_move`. A step stopped short **does not advance the
+  walk**: progress returns to where the step began. A follower held for a second
+  arrives a second late instead of racing ahead once free. `on_finished` never fires
+  for a walker still standing in front of its blocker.
+- **A held follower does not slide.** The step's free axis still moves, but each
+  step aims at the same path point again. A follower pressed diagonally against a
+  wall comes to rest, unlike a [`Velocity`](#velocity), which slides. To get around
+  an obstacle, replan the path.
 
 ### `PlayerController`
 
-Drives a `CharacterBody` sibling from two input axes — direct 8-way walking, no inertia (unlike
-`ThrustController`).
+**Drives a `CharacterBody` sibling from two input axes**: direct 8-way walking, no
+inertia (unlike `ThrustController`). It neither knows nor cares whether the body is
+blocked.
 
 - **Construct:** `PlayerController.new(x_axis: :move_x, y_axis: :move_y)`.
+- **Lifecycle:** `on_attach` looks up the node's `CharacterBody` with
+  `require_sibling`.
 - **Phase:** `control(actions)` copies the two axes into the body's intent.
+- **Example:** `examples/walk`.
 
-### `WanderController`
+### `Pool`
 
-A simple AI driver for a `CharacterBody`: every so often it rolls a new direction (one of eight, or
-idle) and holds it, re-rolling early when a wall blocks it. The RNG is injected, so behaviour is
-deterministic in tests.
+**Wraps an [`RGame::Engine::Pool`](toolbox.md#pool--reuse-dont-allocate) of nodes
+and runs its tree bookkeeping in the frame tick.** A scene that recycles entities,
+such as enemies or projectiles, writes no acquire/add/reclaim code. It calls `spawn`
+and the ordinary `queue_free`. Pooled nodes are **normal children** of the owner, so
+the scene's traversal updates and draws them. This component manages only pool
+membership.
+
+- **Construct:** `Pool.new { Enemy.new(...) }`. The factory builds a blank node. Add
+  the component with a name (`as:`) when a node needs several pools.
+- **Spawn:** `pool.spawn` takes a node, recycled or newly built, and adds it as a
+  child. `pool.spawn { |n| n.reset(...) }` runs the block to re-initialise the node
+  *before* it enters the tree, so `on_attach` sees the reset state. Projectiles need
+  that order.
+- **Reclaim:** `update(dt)` returns every freed pooled node to the free list, and
+  detaches any still attached. Despawning is thus `node.queue_free` from anywhere;
+  the pool recycles the node with no game-side wiring. It allocates nothing in steady
+  state.
+- **State:** `size` counts the live pooled nodes, and `empty?` is true once all are
+  reclaimed. A scene reads it to tell when a wave is cleared.
 
-- **Construct:** `WanderController.new(rng: Random.new, change_interval: 1.0..3.0, idle_chance: 0.25)`.
-- **Phase:** `update(dt)` counts down the timer and re-rolls on timeout or when blocked.
+### `ScreenWrap`
 
-### `TileWorld`
+**Wraps the node's position within the world bounds**, so an entity leaving one edge
+reappears at the opposite one.
+
+- **Construct:** `ScreenWrap.new(margin: 0.0)`. `margin` lets a sprite pass fully off
+  one edge before reappearing on the other. Bounds come from the scene's world
+  system. `ScreenWrap.new(width:, height:, margin:)` overrides them for a node whose
+  wrap region is not the whole world.
+- **Lifecycle:** `on_attach` resolves the bounds, which is why you can omit them. A
+  pooled entity is built long before it enters a tree, and has nothing to ask yet. It
+  resolves again on every entry, so a recycled node follows the scene it lands in.
+  Attaching without bounds and without a world system in scope **raises**.
+- **Phase:** `update(dt)` wraps the node's **world** position against the bounds, and
+  writes it back through [`Node2D#world_x=`](scene_graph.md#the-two-spaces). A node
+  under an offset container wraps at the world's edge, not at an edge shifted by the
+  container.
+- **A wrap is a placement, not a step.** It does not consult a sibling mover's
+  `blocked_by` about the far side. A node wrapped onto something that blocks it stays
+  pressed against it.
+- **One response to the edge per node.** It raises at attach beside a
+  `DespawnOffscreen`, or beside a mover declaring `blocked_by: [:bounds]`. A wrapping
+  entity's mover declares no `:bounds`; see [`WorldBounds.one_response!`](#world).
 
-The scene-scoped tile **system** (see [Systems](systems.md)): it holds the parsed `RGame::Engine::TileMap`
-and answers everything an actor needs from it — collision against the solid tiles (reusing
-`RGame::Engine::CollisionSystem`) and the world bounds. Found with `node.system(TileWorld)`.
+### `Sprite`
+
+**Draws one registered image centred on the node's origin**, at `0, 0`, where the
+traversal already placed and rotated the renderer.
+
+- **Construct:** `Sprite.new(id:, scale: 1.0, z: 0)`. `id` is a renderer image id.
+  `z` orders this component against the node's *other* drawing, such as a shadow
+  under a sprite, inside the node's own slot. It is not the node's `z`, which orders
+  the node among its siblings. See [Drawing](drawing.md#draw-order).
+- **State:** `scale` is read/write, so a pooled entity can retune it.
+- **Phase:** `draw(renderer, view)` draws the image at **`0, 0`** with **no angle**.
+  `Node2D#draw` already pushed the node's transform, so the origin and rotation
+  already apply. Passing either would apply it twice. The image is lifted by
+  [`node.elevation`](scene_graph.md#elevation), in the node's local space. The
+  component skips the draw entirely when the view cannot show it. It measures the
+  node's box, scaled and lifted, against `node.world_x` and `world_y`. A node that
+  never set a size is never culled.
 
-**It does not draw.** `RGame::Engine::TileMapLayer` does — one node per Tiled layer, mounted
-inside a `WorldView`, so the map is drawn once per viewport like the rest of world space.
-This stays the thing actors ask questions of.
+### `Targeting`
 
-- **Construct:** `TileWorld.new(map:, tilemap_id:, cameras: [])` — it clamps each camera it is given to
-  the map's edges, and `bound(camera)` does the same for one that arrives later (a player joining).
-- **Queries:** `move(actor, dx, dy)` slides an actor (anything responding to `x`/`y`/`collision_box`)
-  along solids and clamps it to the world; `solid?(col, row)`; `world_width`/`world_height`;
-  `tilemap_id` and `elapsed`, which the layers read; `layer_count` and `first_above_layer`,
-  which `TileMapLayer.mount` reads to decide where the actors go.
+**Picks a node for the owner to aim at.** Each `update`, it queries the scene's
+[`CollisionWorld`](#collisionworld) around the node's world origin and exposes the
+chosen target. It only *selects*; it never moves or fires. The owner reads `target`
+and acts. Every candidate already registers with the broadphase through its
+collider, so targeting keeps no entity list.
+
+- **Construct:** `Targeting.new(range:, policy: :nearest, layer: nil)`. `range` is
+  the reach in pixels. `layer` restricts candidates, so `:enemy` ignores allies and
+  projectiles. An unknown `policy` raises at construction.
+- **Policies:** `:nearest`, the default and only policy, picks the closest candidate
+  in range with one broadphase lookup.
+- **State:** `target` is the chosen **node**, or `nil` when nothing is in range. It
+  refreshes every `update`, so a freed or out-of-range target clears itself. It is a
+  node, not a collider, so the owner can read its position and components.
+- **Lifecycle:** `on_attach` looks up the scene's `CollisionWorld`.
+- **Phase:** `update(dt)` selects the target again. It allocates nothing, so it runs
+  every frame.
+
+### `ThrustController`
+
+**Inertial ship flight on top of a `Velocity` sibling.** A turn axis rotates the
+node, and a thrust axis accelerates it along its heading.
+
+- **Construct:** `ThrustController.new(turn_speed:, accel:, max_speed:, drag: 0.0,
+  turn_action: :turn, thrust_action: :thrust)`.
+- **Lifecycle:** `on_attach` looks up the node's `Velocity` with `require_sibling`,
+  so a missing one raises at once instead of surfacing later as a `nil`.
+- **Phase:** `control(actions)` reads intent: turn sets `velocity.spin`, and thrust
+  is stored. `update(dt)` accelerates along the heading, applies drag, and clamps to
+  `max_speed`. Angle 0 points up, so forward is `(sin θ, −cos θ)`. Firing is not part
+  of this component.
+
+### `TileWorld`
+
+**The scene-scoped tile system** (see [Systems](systems.md)). It holds the parsed
+[`RGame::Engine::TileMap`](tile_maps.md) and answers what an actor needs from it: where the solid
+tiles are, and how big the world is. Find it with `node.system(TileWorld)`. It
+includes `WorldBounds` (see [`World`](#world)), so `ScreenWrap` and
+`DespawnOffscreen` work in a tile scene with no arguments.
+
+**It does not draw.** `RGame::Engine::TileMapLayer` draws, one node per Tiled layer,
+mounted inside a `WorldView`. The map is therefore drawn once per viewport, like the
+rest of world space. `TileWorld` stays the thing actors ask.
+
+**Each piece of the tile stack is the kind of object its job requires:**
+
+| Piece | Kind | Because |
+|---|---|---|
+| `TileMap`, `Tileset` | values | parsed data with no handle; the gid rows are a `Util::Tensor` |
+| `TileWorld` | component, mounted as a system | it is a scene-scoped answer — solid tiles, world size — that actors look up |
+| `TileMapLayer` | node | it draws in world space, and draw order is tree order |
+
+None of them duplicates state the node owns. None needs a hand-written hook to pass
+data to another, depends on a sibling's add order, or names a layer it may not name.
+
+- **Construct:** `TileWorld.new(map:, tilemap_id:, cameras: [])`. It clamps each
+  camera it receives to the map's edges. `bound(camera)` does the same for a camera
+  that arrives later, when a player joins.
+- **Queries:**
+  - `blockers` returns the map's solid tiles as an
+    [`Engine::TileBlockers`](internals.md#tileblockers--the-tile-grid-as-a-blocker-source),
+    the same object every time. A [`Mover`](#mover) declaring `:tiles` borrows it
+    and resolves its own steps against it.
+  - `nav_grid` returns the same solidity as an
+    [`Engine::NavGrid`](toolbox.md#navgrid--routes-over-a-tile-grid), for planning a
+    route instead of resolving a step. It is built on first request and reused.
+  - `tile_width` and `tile_height` turn a world position into a cell.
+  - `solid?(col, row)`, `world_width` and `world_height`.
+  - `tilemap_id` and `elapsed`, which the layers read.
+  - `layer_count` and `first_above_layer`, which `TileMapLayer.mount` reads to
+    decide where actors go.
+- **Solidity is read from the map once.** On the first request, `TileWorld` reads
+  the map's `solid_tile?` once per cell into one
+  [`Util::SolidGrid`](values.md#rgameutilsolidgrid). From then on, `blockers`,
+  `nav_grid` and `solid?` all read that store, never the map. They cannot disagree
+  about a cell. A resolve on the per-frame path becomes a byte lookup instead of a
+  walk through the map's layers and tileset. Everything past the map's edges is open.
+  `TileWorld` does not hand the store out, so a game cannot change a tile's solidity
+  at runtime.
+- **It does not resolve a step.** Tiles, other actors, the world's edge, or any
+  combination may stop a mover, and only the mover knows which. The resolver
+  therefore belongs to the mover, and the grid to this system.
 - **Phase:** `update(dt)` advances the map's animation clock.
+- **Examples:** `examples/scroll_map` loads a `.tmx` through the asset manager and
+  uses this system, `TileMapLayer.mount`, and a camera clamped to the map's edges.
+  `examples/collision_tiles` adds an actor that collides, and shows the solid half of
+  this system.
 
 ```ruby
 world  = scene.add_node(RGame::Engine::WorldView.new)
@@ -327,19 +1007,106 @@ actors = RGame::Engine::TileMapLayer.mount(world)   # a node per Tiled layer
 actors.add_node(player)                             # in the gap between them
 ```
 
-`mount` returns the node the actors go in. It sits below the first layer Tiled flags
-`above` — trunks under the walker, canopies over — and `mount(world, under: index)`
-overrides that for a map with a different arrangement. Nothing here picks a `z`.
+**`mount` returns the node the actors go in.** That node sits below the first layer
+Tiled flags `above`, so trunks draw under the walker and canopies over it.
+`mount(world, under: index)` overrides the position for a map arranged differently.
+Nothing here picks a `z`.
+
+### `Timer`
+
+**A node-driven interval timer.** It runs in the node's update tick, so nothing can
+forget to advance it. It emits `on_timeout` each time a whole interval elapses: a
+spawn cadence, a turret's fire rate, a wave clock. It wraps the pure
+[`RGame::Engine::Timer`](toolbox.md#timer--paced-periodic-events) and reuses its
+drift-free carry-forward.
+
+- **Construct:** `Timer.new(interval, repeating: true)`, in seconds. Add it with a
+  name when a node needs several: `node.add_component(Timer.new(0.8), as: :spawn)`.
+  `repeating: false` makes a **one-shot** that fires `on_timeout` exactly once, then
+  goes inert. A projectile that should vanish after N seconds on a fixed board is
+  `Timer.new(2.0, repeating: false)` plus `on_timeout { node.queue_free }`. When the
+  board scrolls and the entity leaves the screen, use `DespawnOffscreen` instead.
+- **Signal:** `on_timeout` fires once per whole interval:
+  `timer.on_timeout { spawn_enemy }`.
+- **Lifecycle:** `on_attach` restarts the countdown and re-arms a spent one-shot. A
+  pooled node acquired and added again starts fresh, without its previous life's
+  elapsed time.
+- **Phase:** `update(dt)` advances and emits. In one long step, a repeating timer
+  emits once per interval crossed, catching up without drift. A one-shot emits at
+  most once. It allocates nothing.
+- **Reset:** `reset` drops accumulated time and re-arms a one-shot, giving a fresh
+  timer.
+
+### `Velocity`
+
+**Integrates linear and angular velocity into the node's transform each step.**
+
+- **Construct:** `Velocity.new(vx: 0.0, vy: 0.0, spin: 0.0, blocked_by: [])`.
+  [`Mover`](#mover) decides what may stop it, as for a `CharacterBody`.
+- **State:** `vx`, `vy` and `spin` are read/write. A controller, or the node's own
+  `control` hook, writes them as movement intent.
+- **Phase:** `update(dt)` moves the node by `vx*dt` and `vy*dt` through `apply_move`.
+  It adds `spin*dt` to `node.angle` directly: a collision box does not turn with its
+  node, so nothing can block a rotation.
+- **Blocked:** a stopped step leaves `vx` and `vy` unchanged. They are the intent.
+  The game decides what a stop does to them, whether nothing, zero or a bounce, in an
+  `on_blocked` handler. To block a `ThrustController` ship, declare `blocked_by:` on
+  the `Velocity` it drives.
+
+A free-moving entity can use `Velocity` alone. Pair it with a controller for input.
 
 ```ruby
-# A node composing components, with collision meaning decided by the owner:
-class Bullet < RGame::Engine::Node2D
-  def initialize(x:, y:, vx:, vy:, bounds:)
-    super(x: x, y: y)
-    add_component(RGame::Engine::Components::Velocity.new(vx: vx, vy: vy))
-    add_component(RGame::Engine::Components::DespawnOffscreen.new(**bounds))
-    collider = add_component(RGame::Engine::Components::CircleCollider.new(radius: 3, layer: :bullet))
-    collider.on_hit { |other| queue_free if other.layer == :rock }
-  end
-end
+add_component(RGame::Engine::Components::BoxCollider.new(width: 8, height: 8, layer: :bullet))
+velocity = add_component(RGame::Engine::Components::Velocity.new(vx: 400, blocked_by: %i[tiles]))
+velocity.on_blocked { queue_free }
 ```
+
+### `WanderController`
+
+**A simple AI driver for a `CharacterBody`.** At intervals it rolls a new direction,
+one of eight or idle, and holds it. A wall that blocks it triggers an early re-roll.
+The RNG is injected, so tests get deterministic behaviour.
+
+- **Construct:** `WanderController.new(rng: Random.new, change_interval: 1.0..3.0, idle_chance: 0.25)`.
+- **Lifecycle:** `on_attach` looks up the node's `CharacterBody` with
+  `require_sibling`.
+- **Phase:** `update(dt)` counts down and re-rolls on timeout or when blocked.
+  "Blocked" means *the node did not move while intending to*. The controller measures
+  that instead of asking a collision world. It therefore works over a plain
+  `CharacterBody` too, and never re-rolls early for a body whose steps always land.
+- **Example:** `examples/save_load`.
+
+### `World`
+
+**The scene-scoped world system for a rectangular world**: it knows how big the
+world is, and nothing more. Mount one on a scene with a plain rectangular world. The
+components that need bounds find it, so no constructor between scene and entity has
+to pass the numbers along.
+
+- **Construct:** `World.new(width:, height:)`.
+- **Queries:** `world_width` and `world_height`. They never change; a world of a
+  different size is a new scene.
+- **Contract:** it includes `WorldBounds`, and so does [`TileWorld`](#tileworld),
+  which answers the same two questions from its map's pixel size. Ask for the
+  contract, `node.system(RGame::Engine::Components::WorldBounds)`, and either kind of
+  world answers. `get_component` matches an included module the same way it matches a
+  class.
+- **Frame:** the bounds run from (0, 0) to (`world_width`, `world_height`) in
+  **world** coordinates. Everything that compares a node against them reads
+  `world_x` and `world_y`. An entity under an offset container is inside the world
+  exactly when its world position is.
+- **One response to the edge per node:** `WorldBounds.one_response!(node)` raises,
+  naming both, if the node carries more than one of [`ScreenWrap`](#screenwrap),
+  [`DespawnOffscreen`](#despawnoffscreen) and a [`Mover`](#mover) declaring
+  `blocked_by: [:bounds]`. Each of the three calls it from `on_attach`, so whichever
+  attaches second raises, in any add order. No pair makes sense. Stopping and
+  wrapping disagree about where the node ends up. Wrapping and despawning race on
+  which margin is reached first. Stopping tests the collision box, while the other
+  two test the node's origin. The engine therefore refuses every combination.
+
+**The world is not the window.** The two coincide in a single-screen game, which
+makes the mistake easy to make and hard to see. Bind wrapping to the viewport, and
+the world changes shape without warning when the window resizes or the screen
+splits into viewports. Ask [`Viewports`](scene_graph.md#viewports-and-views), or the
+`View` a `draw` receives, how big the *window* is. Ask `World` how big the *world*
+is.