rgame 0.2.0 → 0.3.0

data/docs/api/signals.md

@@ -1,17 +1,16 @@
 # Signals
 
-Signals are the engine's typed take on the observer pattern: a tiny object that
-holds a list of listener blocks and `emit`s to them. They are how decoupled parts
-of the engine talk to each other — a `Button` tells a `Menu` it was clicked, a
-`Selector` announces its value changed, gameplay asks the audio layer to play a
-sound — without the emitter knowing who (if anyone) is listening.
-
-Signals replace the earlier global event bus / `Node#on` observer API. There is no
-central dispatcher and no string/symbol event types to match on: a signal *is* the
-channel, named by the attribute that exposes it, and its arity is fixed when it is
-defined.
-
-`RGame::Engine::Signal` is pure Ruby — no graphics — and lives in
+**A signal is the engine's typed observer.** It holds a list of listener blocks
+and `emit`s to them. Decoupled parts of the engine talk through signals. A
+`UI::Button` reports that it was activated. A collider reports a hit. Gameplay
+asks the audio layer to play a sound. The emitter never knows who listens, or
+whether anyone does.
+
+No central dispatcher exists, and no string or symbol event types need matching.
+A signal *is* the channel. The attribute that exposes it names it, and its arity
+is fixed when you define it.
+
+`RGame::Engine::Signal` is pure Ruby, with no graphics, in
 `lib/rgame/engine/signal.rb`.
 
 ## The Signal class: `Signal.define`
@@ -19,28 +18,29 @@ defined.
 `Signal.define(*fields)` builds a signal **class**. Each instance is one channel:
 
 ```ruby
-ClickSignal = Signal.define              # carries no payload
-ChangeSignal = Signal.define(:index, :value)  # carries two values
+require 'rgame'
+
+ClickSignal = RGame::Engine::Signal.define                   # carries no payload
+ChangeSignal = RGame::Engine::Signal.define(:index, :value)  # carries two values
 
 sig = ChangeSignal.new
 handle = sig.connect { |index, value| puts "#{index} -> #{value}" }
-sig.emit(index: 2, value: :hard)         # prints "2 -> hard"
-sig.disconnect(handle)                   # stops that listener
+sig.emit(index: 2, value: :hard)              # prints "2 -> hard"
+sig.disconnect(handle)                        # stops that listener
 ```
 
-Three instance methods:
+A signal has three instance methods:
 
-- **`connect(&block)`** — registers a listener and returns it as the *handle*. Listeners
-fire in the order they connected.
-- **`emit(...)`** — notifies every listener.
-- **`disconnect(handle)`** — removes the listener returned by `connect`.
+- **`connect(&block)`** registers a listener and returns it as the *handle*.
+  Listeners fire in the order they connected.
+- **`emit(...)`** notifies every listener.
+- **`disconnect(handle)`** removes the listener that `connect` returned.
 
 ### Keyword in, positional out
 
-The field names exist to give `emit` a **self-documenting, mistake-catching
-signature** — you call `emit(index:, value:)`, not `emit(2, :hard)`, so a wrong or
-missing field raises at the call site. But the *listener* block receives the values
-**positionally**:
+**`emit` takes keywords; listeners receive positional values.** The field names
+give `emit` a self-documenting signature. You call `emit(index:, value:)`, not
+`emit(2, :hard)`, so a wrong or missing field raises at the call site:
 
 ```ruby
 ChangeSignal = Signal.define(:index, :value)
@@ -48,29 +48,29 @@ sig.connect { |index, value| ... }   # positional params
 sig.emit(index: 2, value: :hard)     # keyword args -> it.call(2, :hard)
 ```
 
-This is deliberate. Ruby blocks bind positional parameters cleanly but handle
-keyword arguments awkwardly, so the generated `emit` translates `emit(x:, y:)` into
-`it.call(x, y)`.
+Ruby blocks bind positional parameters cleanly but handle keywords awkwardly. The
+generated `emit` therefore translates `emit(x:, y:)` into `it.call(x, y)`.
 
-A single-field signal does not follow this keyword convention, in this case the single parameter is non-keyworded.
+A signal with a single field takes its argument positionally, without a keyword:
 
 ```ruby
 PlaySound = Signal.define(:id)
-sig.connect { @audio.play_sound(it) }
+sig = PlaySound.new
+sig.connect { puts "play #{it}" }
 sig.emit(:boom)
 ```
 
 ### No per-emit allocation
 
-`emit` forwards its arguments straight to each listener — it never collects them
-into an array or hash. Defining the signature with explicit fields (rather than a
-`*splat`) is what makes this allocation-free, which matters because some signals
-fire every frame (the engine's rule: never allocate on the hot path).
+**`emit` allocates nothing.** It passes its arguments straight to each listener,
+never collecting them into an array or hash. The explicit fields make this
+possible; a `*splat` signature would allocate. Some signals fire every frame, and
+the engine never allocates on the hot path.
 
 ## The DSL: declaring a signal slot
 
-Hand-wiring a signal onto a class is repetitive — an ivar to hold the instance, a
-public method to subscribe, and a way to emit:
+Wiring a signal onto a class by hand repeats itself. The class needs an ivar for
+the instance, a public method to subscribe, and a way to emit:
 
 ```ruby
 # Without the DSL:
@@ -80,63 +80,68 @@ def on_clicked(&block) = @on_clicked.connect(&block)
 def activate = @on_clicked.emit
 ```
 
-`RGame::Engine::Signal::DSL` collapses that to one declaration. `extend` it, then declare
-slots with `signal`:
+`RGame::Engine::Signal::DSL` reduces that to one declaration. `extend` it, then
+declare slots with `signal`:
 
 ```ruby
-class Button < Control
+require 'rgame'
+
+class Lever < RGame::Engine::Node2D
   extend RGame::Engine::Signal::DSL
 
-  signal :on_clicked                          # a no-arg signal
-  # signal :on_changed, Signal.define(:index, :value)  # a typed one
+  signal :on_pulled                                                  # a no-arg signal
+  signal :on_changed, RGame::Engine::Signal.define(:index, :value)   # a typed one
 
-  def activate = on_clicked_signal.emit
+  def pull = on_pulled_signal.emit
 end
+
+lever = Lever.new
+lever.on_pulled { puts 'pulled' }
+lever.pull
 ```
 
-`signal :on_clicked` generates two methods:
+`signal :on_pulled` generates two methods:
 
-- **`on_clicked(&block)`** — *public*. Subscribe a listener; returns the handle. This
-  is the API observers use: `button.on_clicked { ... }`.
-- **`on_clicked_signal`** — *private*. The lazily-built `Signal` instance. Emit
-  through it from inside the class: `on_clicked_signal.emit`.
+- **`on_pulled(&block)`** is *public*. It subscribes a listener and returns the
+  handle. Observers call it: `lever.on_pulled { ... }`.
+- **`on_pulled_signal`** is *private*. It returns the `Signal` instance, built on
+  first use. The class emits through it: `on_pulled_signal.emit`.
 
-The signal is created on first use (`@on_clicked ||= type.new`), so the host wires
-**nothing** in `initialize`. Pass a signal class as the second argument for a typed
-slot; omit it for a no-arg signal.
+The reader builds the signal on first use, so the host wires **nothing** in
+`initialize`. Pass a signal class as the second argument for a typed slot. Omit
+it for a signal without a payload.
 
-A note on cost: the generated methods use `define_method`, and emitting goes through
-the private reader rather than a bare ivar — one extra method dispatch per emit
-(single-digit nanoseconds under YJIT, and `emit` itself stays a full-speed `def`).
-Negligible for UI and per-frame signals. For a signal emitted thousands of times per
-frame, hand-write it against a direct ivar instead.
+**The DSL costs one extra method call per emit.** Emitting goes through the
+private reader instead of a bare ivar. `emit` itself stays an ordinary `def`. UI
+and per-frame signals never notice. For a signal emitted thousands of times per
+frame, write it by hand against an ivar.
 
 ## Two shapes of signal
 
-**Per-instance signals (the DSL).** Each object owns its channels. This is the UI
-pattern: every `Button` has its own `on_clicked`, every `Selector` its own
-`on_changed`. The `signal` macro is built for exactly this (it stores the instance
-in an ivar).
+**Per-instance signals use the DSL.** Each object owns its channels. UI works this
+way: every `UI::Button` has its own `on_activated`, and every `UI::OptionButton`
+its own `on_changed`. The `signal` macro stores the instance in an ivar, which
+suits exactly this case.
 
-**A shared signal hub (module-level).** When one global channel serves the whole app,
-expose signals as module state instead. `RGame::Engine::AudioBus` is the example: it holds
-`Signal.define(:id).new` instances at module scope and exposes them through reader
-methods, so gameplay anywhere does `RGame::Engine::AudioBus.on_play_sound.emit(:boom)`
-and the `AudioDirector` connects once. The DSL doesn't apply here (there is no
-per-instance ivar); the hub hand-rolls the readers.
+**A shared hub holds signals at module level.** Use one when a single channel
+serves the whole game. `RGame::Engine::AudioBus` holds its signals at module scope
+and exposes them through readers. Gameplay anywhere calls
+`RGame::Engine::AudioBus.play_sound(:boom)`, and the `AudioDirector` connects
+once to `AudioBus.on_play_sound`. The DSL does not apply, because there is no
+instance; the hub writes its readers by hand.
 
 ## When to reach for a signal
 
 Follow the engine's communication rules (see [Scene graph](scene_graph.md)):
 
-- **Parent → child:** call methods directly. No signal needed; the parent holds the
-  reference.
-- **Child → parent, or sibling → sibling:** the child *exposes* a signal and the
-  parent (or a parent-arranged observer) subscribes. A `Button` exposes `on_clicked`;
-  its `Menu` parent connects in `on_add` and re-exposes a higher-level
-  `on_selected(index, id)` to the scene. Edges stay direct node-to-node.
-- **Cross-cutting app concerns** with no natural owner (audio, later maybe analytics):
-  a module-level hub like `AudioBus`.
-
-Keep the emitter ignorant of its listeners: a signal with no observers connected
-emits harmlessly to nobody.
+- **Parent → child:** call methods directly. The parent holds the reference, so
+  it needs no signal.
+- **Child → parent, or sibling → sibling:** the child *exposes* a signal, and the
+  parent or an observer the parent arranges subscribes. A `UI::Button` exposes
+  `on_activated`, and the scene that adds it to a menu connects to it. Edges stay
+  direct, node to node.
+- **Concerns that cut across the game** and have no natural owner, such as
+  audio: use a module-level hub like `AudioBus`.
+
+Keep the emitter ignorant of its listeners. A signal with no listeners emits to
+nobody, without error.

data/docs/api/systems.md

@@ -1,45 +1,34 @@
 # Systems & shared resources
 
-Some things a node needs don't live on the node: a tilemap, the world bounds, a
-shared collision world. The engine resolves this the way scene-graph engines do —
-shared resources are **systems that live on an anchor node and are reached by
-walking the tree**, not threaded through constructors. There is **no `GameContext`
-bag**: a system is just an `RGame::Engine::Component` on a boundary node, found with the
-same `get_component` every node already has.
-
-> Status: the anchor + lookup mechanism (`root`, `scene`, `system`), the
-> tree-lifecycle hooks, and deferred removal (`queue_free`) are in place.
-> `examples/14_asteroids` exercises the whole path end to end and shows **both
-> scopes**: a scene-scoped `CollisionWorld` system and a root-scoped `HighScores`
-> system. `examples/15_tiled_world` adds a second scene-scoped system, `TileWorld`
-> (the tile map: collision, world bounds, drawing). More systems arrive with the
-> rest of the component port (see `docs/wip/components.md`).
-
-## Two scopes = two anchor nodes
-
-Scope is a property of the **owner** you attach a system to, not of the system
-itself — the same insight behind Unreal's `UGameInstanceSubsystem` (whole session)
-vs `UWorldSubsystem` (one level), and Godot's autoload singletons vs per-scene
-nodes.
-
-- **Global scope → the root node.** `root` is set once and never changes, reachable
-  from every node. Program-lifetime systems (e.g. an audio bus, i18n) are components
-  on the root: `node.root.get_component(AudioBus)`.
-- **Scene scope → the scene node** (what `SceneStack` pushes). Scene-lifetime systems
-  (the collision world, the tilemap/world-bounds holder) are components on *that*
-  node — born when the scene is pushed, gone when it's popped:
-  `node.scene.get_component(CollisionWorld)`.
+Some things a node needs do not live on the node: a tile map, the world bounds, a
+shared collision world. **Shared resources are systems. A system lives on an
+anchor node, and other nodes reach it by walking the tree**, not through
+constructor arguments. A system is an ordinary `RGame::Engine::Component` on a
+boundary node, found with the same `get_component` every node has.
+
+## Two scopes, two anchor nodes
+
+**Scope belongs to the node you attach a system to**, not to the system.
+
+- **Global scope → the root node.** Every node can reach the root, and it never
+  changes. Systems that live as long as the program are components on the root,
+  such as `Players` and `Viewports`: `node.root.get_component(RGame::Engine::Players)`.
+- **Scene scope → the scene node**, the node `SceneStack` pushes. Systems that
+  live as long as a scene are components on *that* node, such as the collision
+  world or the tile world. They appear when the scene is pushed and go when it is
+  popped: `node.scene.get_component(CollisionWorld)`.
 
 ## The anchors
 
-Both anchors are **methods that walk the parent chain**, not cached fields. A cached
-back-link set at add-time goes stale when a node is built before it's mounted (its
-children would cache the wrong root); resolving on access can't.
+**Both anchors are methods that walk the parent chain**, not cached fields. A
+back-link cached at add time would go stale for a node built before it is
+mounted: its children would cache the wrong root. Resolving on every access
+cannot go stale.
 
-- `root` — `@parent ? @parent.root : self`. The top-most node is its own root.
-- `scene` — the nearest ancestor marked as a scene boundary. `SceneStack#push` marks
-  the pushed scene with `scene.scene = scene`; descendants resolve up to it. Outside
-  any scene, `scene` is `nil`.
+- `root` is `@parent ? @parent.root : self`. The top-most node is its own root.
+- `scene` is the nearest ancestor marked as a scene boundary. `SceneStack#push`
+  marks the pushed scene with `scene.scene = scene`, and descendants resolve up to
+  it. Outside any scene, `scene` is `nil`.
 
 ### Looking a system up
 
@@ -47,72 +36,196 @@ children would cache the wrong root); resolving on access can't.
 node.system(CollisionWorld)
 ```
 
-`Node2D#system(klass)` checks the **scene scope first, then the global root**, so a
-scene can override a global default and free-standing nodes still find globals. Use
-the explicit anchor (`node.root.get_component` / `node.scene.get_component`) when you
-specifically mean one scope.
+**`Node2D#system(klass)` checks the scene first, then the root.** A scene can
+therefore override a global default, and nodes outside any scene still find
+globals. To mean one scope specifically, use its anchor:
+`node.root.get_component` or `node.scene.get_component`.
 
-## Registering with a system — use the lifecycle, not `initialize`
+### Ask for a contract, not a class
 
-A system and its clients only connect once everything is **in the live tree**, so
-wiring happens in the tree-lifecycle hooks, never in `initialize` (where a node has
-no anchors). See [Lifecycle](scene_graph.md#lifecycle-constructing-vs-entering-the-tree).
+**The lookup matches by ancestry**, so `klass` can be a module the system
+includes instead of its own class. One question can then have several answers.
 
-The entered-tree cascade guarantees ordering that makes this safe: a scene's own
-components `on_attach` (so a `CollisionWorld` on the scene node exists), then the
-scene's `on_add`, then its children enter — so by the time a child collider attaches,
-the scene-scoped system it looks up is already there.
+"How big is the world" shows this. A flat game mounts
+[`Components::World`](components.md#world). A tile game mounts
+[`Components::TileWorld`](components.md#tileworld), which derives the same two
+numbers from its map. Both include `Components::WorldBounds`, so a component
+that needs bounds asks for the *contract*:
+
+```ruby
+def on_attach
+  world = node.system(RGame::Engine::Components::WorldBounds)
+  @width = world.world_width
+  @height = world.world_height
+end
+```
+
+`ScreenWrap` and `DespawnOffscreen` work this way. They run unchanged in either
+kind of scene and never learn which one they are in. Naming the contract keeps
+the two implementations from drifting apart.
+
+## Registering with a system: use the lifecycle, not `initialize`
+
+**A system and its clients connect in the tree-lifecycle hooks**, never in
+`initialize`. They can only connect once everything is in the live tree, and a
+node under construction has no anchors. See
+[Lifecycle](scene_graph.md#lifecycle-constructing-vs-entering-the-tree).
+
+The entered-tree cascade fixes an order that makes this safe. The scene's own
+components run `on_attach` first, so a `CollisionWorld` on the scene node exists.
+Then the scene's `on_add` runs, then its children enter. By the time a child
+collider attaches, the scene-scoped system it looks up is already there.
 
 ```ruby
 # CircleCollider (engine/components/circle_collider.rb) registers itself when it
 # enters the tree and releases the registration when it leaves — the engine fires
 # both hooks, so a spawned/despawned entity can't leak a registration.
 class CircleCollider < RGame::Engine::Component
-  def on_attach = node.system(CollisionWorld).register(self)
+  def on_attach = node.system(CollisionWorld)&.register(self)
   def on_detach = node.system(CollisionWorld)&.unregister(self)
 end
 ```
 
-## The two the platform mounts for you
+**A collider tolerates a missing world; most clients should not.** Both hooks
+above use `&.`. A collider in a scene without a `CollisionWorld` is a shape that
+reports nothing. A tile-only game wants exactly that: its character carries a
+feet box to be *stopped* by (see [`Mover`](components.md#mover)), and there are no
+pairs to find. The cost is that an `on_hit` handler in such a scene never fires,
+and nothing reports it. Weigh that deliberately. A client that is useless without
+its system raises instead, as a mover's `blocked_by:` does.
+
+## The two systems `Game` mounts
 
-`RGame::Game` puts two systems on the root before the tree comes alive, so any
-node can reach them without a game wiring anything:
+**`RGame::Game` puts two systems on the root before the tree goes live.** Any node
+can reach them without the game wiring anything:
 
 | | |
 |---|---|
 | `node.system(RGame::Engine::Players)` | who is playing — devices, bindings, cameras, and who a newly used controller belongs to |
 | `node.system(RGame::Engine::Viewports)` | how the screen is divided — one `View` per active player, and collapsing the split |
 
-They are ordinary root-scoped systems, mounted the same way a game would mount
-its own. A scene that needs a camera to follow asks the first
-(`players.primary.camera`); a cutscene that needs to collapse the split asks the
-second (`viewports.solo!(camera)`), from wherever in the tree it happens to be
-and with nothing threaded into it. That reachability is the whole reason they
-are systems rather than something `Game` hands down.
+They are ordinary root-scoped systems, mounted the way a game mounts its own. A
+scene that needs a camera to follow asks `Players` (`players.primary.camera`). A
+cutscene that collapses the split asks `Viewports` (`viewports.solo!(camera)`).
+Both work from anywhere in the tree, with nothing passed in. That reach is why
+they are systems and not objects `Game` hands down.
 
 See [Input](input.md#players-seats-and-joining) and
 [Scene graph](scene_graph.md#viewports-and-views).
 
+## Collision: two indexes, one resolver
+
+Collision is the largest structure built from systems. Three pages cover its
+parts: the [components](components.md#boxcollider) a node carries, the
+[systems](#systems-that-index-their-clients-the-tag-registry-pattern) a scene
+mounts, and the
+[building blocks](internals.md#collisionsystem--move-an-actor-against-its-blockers)
+underneath. This section shows how they fit together.
+
+**A node has exactly one collision shape, and exactly one component owns it.** The
+[collider](components.md#boxcollider) *is* the shape. A
+[mover](components.md#mover) that wants to be stopped reads its sibling's box
+instead of building a second one. The rectangle that stops a step is the
+rectangle that reports a contact, so retuning one retunes both.
+
+**Collision uses two indexes, on purpose.** A tile map is already an index: the
+wall a step would hit follows from arithmetic on the step. A `TileWorld` divides
+by the tile size and asks the grid. Actors have no such structure, so a
+`CollisionWorld` buckets them into a
+[`SpatialHash`](internals.md#spatialhash--uniform-grid-broadphase) each step.
+Baking tile shapes into the broadphase would rebuild an index the grid already
+is. It would also cost time every frame on a map of tens of thousands of tiles.
+
+**The unification happens one level up.** A **blocker source** answers one
+question over plain numbers: where does this box land when it moves `dx`? Three
+sources exist:
+
+- `TileBlockers`, over the grid;
+- `ActorBlockers`, over the broadphase;
+- `BoundsBlockers`, over the world's edges.
+
+A blocked mover builds a
+[`CollisionSystem`](internals.md#collisionsystem--move-an-actor-against-its-blockers)
+at attach, from the sources its `blocked_by:` names. That system asks each source
+and takes the most restrictive answer on each axis. The axis-separated order that
+produces wall-sliding therefore exists **once**. An actor slides off a villager
+exactly as it slides off a fence.
+
+A source may also answer `travel?`: can this box move along a segment without
+being stopped? `TileBlockers` does. A [`Navigator`](components.md#navigator) uses
+it to check a route against the same resolver that will stop its walk.
+
+| | Mounted on the scene | Owned by the node |
+|---|---|---|
+| Tiles | [`TileWorld`](components.md#tileworld), which hands out one shared `TileBlockers` | — |
+| Actors | [`CollisionWorld`](components.md#collisionworld), the broadphase | an `ActorBlockers` per mover, holding its own collider and layer list |
+| The world's edge | any [`WorldBounds`](components.md#world) | a `BoundsBlockers` |
+| The step | — | one `CollisionSystem`, built at attach from the names above |
+
+Neither system needs the other, and most scenes mount one. `examples/scroll_map`
+has a map and no broadphase. `examples/collision` has a broadphase and no map.
+`examples/collision_tiles` mounts both, and the difference shows only in the names
+listed in `blocked_by`.
+
+"What stops a mover" and "what a collider touches" remain two questions, and a
+game sees the difference. See
+[Blocking and overlapping](#blocking-and-overlapping-are-two-reports-and-a-pair-gets-one-of-them)
+below, after the broadphase.
+
 ## Systems that index their clients (the tag-registry pattern)
 
-A many-to-many system (broadphase collision) lives on the scene node and keeps its
-own index of registered clients, so it processes only nearby candidates instead of
-walking the tree for every pair. `CollisionWorld`
-(engine/components/collision_world.rb) holds a `SpatialHash` for exactly this — a
-spatial index of registered colliders, rebuilt each `update`. This indexing is the
-same idea as Godot's **groups**: a registry of node references. It is *not* an ECS —
-it indexes references, carries no component data, and gains none of ECS's
-data-locality; it's a lightweight index.
+**A many-to-many system keeps its own index of registered clients**, so it checks
+only nearby candidates instead of walking the tree for every pair. Broadphase
+collision works this way, on the scene node. `CollisionWorld`
+(engine/components/collision_world.rb) holds a `SpatialHash`: a spatial index of
+registered colliders, rebuilt each `update`. The index ignores shape, so
+`CircleCollider` and `BoxCollider` share one and collide with each other. The
+index holds node references only. It carries no component data and gives no
+data-locality benefit; it is a lightweight registry.
 
-`CollisionWorld` is layer-agnostic: it reports every overlapping pair by firing each
-collider's `on_hit` signal with the other collider, and the owning node decides what
-a contact *means* by reading the other's `layer` tag:
+**`CollisionWorld` ignores layers.** It reports every overlapping pair to both
+colliders. The owning node decides what a contact *means* by reading the other
+collider's `layer` tag:
 
 ```ruby
 collider.on_hit { |other| queue_free if other.layer == :bullet } # in a Rock node
 ```
 
-Because it's a normal component on the scene node, it rides the `update` traversal
-(its broadphase runs in `update`) and is torn down with the scene. See
-`examples/14_asteroids` for the whole loop: ship, bullets, and rocks spawning,
-colliding, and despawning through this system.
+**A contact arrives as two edges, not as a state.** `on_hit` fires on the step a
+pair starts overlapping. `on_separated` fires on the step it stops. Each fires
+once per pair, with nothing in between. A handler can therefore count, play a
+sound or spend a life without guarding itself. That is why the system keeps an
+`Engine::ContactSet` per collider, instead of forwarding each step's broadphase
+results.
+
+`CollisionWorld` is a normal component on the scene node. It runs in the
+`update` traversal, where its broadphase runs, and goes away with the scene.
+`examples/collision` shows the whole loop: circles and crates registering,
+overlapping and separating through this system.
+
+### Blocking and overlapping are two reports, and a pair gets one of them
+
+**The same broadphase answers a second question.** A
+[mover](components.md#mover) that names a collider layer in `blocked_by:` is
+*stopped* by every box with that layer. It stops flush against the box's edge, as
+against a solid tile. One `BoxCollider` can thus be a wall to one actor and a
+trigger for another. Who declared the layer decides which; the collider itself
+says nothing.
+
+**The two reports never both fire for one pair.** Blocking leaves the boxes
+exactly touching. `CollisionBox.overlap?` uses the half-open span `[x, x + w)` on
+purpose. On a grid, pieces on neighbouring squares border each other constantly,
+and an inclusive test would report each as a contact. Measured on two 12×6 boxes:
+touching exactly, `on_hit` does not fire; overlapping by half a pixel, it does.
+That convention makes the two reports mutually exclusive by construction.
+
+A blocked pair therefore reports **no** contact. A mover that must both stop and
+react listens to `on_blocked`, not `on_hit`; see [`Mover`](components.md#mover).
+The rule of thumb:
+
+| The question | The report | Where it lives |
+|---|---|---|
+| what may I not pass through | `on_blocked` / `on_unblocked` | the mover that was stopped |
+| what am I touching | `on_hit` / `on_separated` | both colliders of the pair |
+
+`examples/collision_tiles` shows the first, and `examples/collision` the second.