rgame 0.1.0

data/docs/api/input.md

@@ -0,0 +1,179 @@
+# Input
+
+Three pieces work together:
+
+- **`RGame::Util::Controls`** — the vocabulary: which number means "the left
+  arrow key", "the A button", "player 2's controller". Plain values, usable
+  without loading any graphics library.
+- **`RGame::Core::Input`** — translates your game's *actions* (`:fire`,
+  `:confirm`) into those ids and asks the app whether they are held.
+- **`RGame::Core::Gamepad`** — which controllers are plugged in, for menus.
+
+There is no mouse support, by design.
+
+## `RGame::Core::Input`
+
+```ruby
+input = RGame::Core::Input.new(app)
+
+input.down?(:fire)                 # keyboard — the single-player default
+input.down?(:fire, device: pad)    # a specific controller
+input.axis(:move_x, device: pad)   # => Float
+```
+
+`down?` and `axis` read a snapshot the engine takes **once per frame**, when it
+pumps events. That is what makes them safe to call from `update`: a frame can
+run several simulation ticks, and every tick sees the same answer. Reading
+hardware directly would make a held key behave differently depending on how
+slow the previous frame was.
+
+### Actions, not keys
+
+You ask for `:fire`, not for the space bar. The mapping lives in a binding
+table, so the same game code works for a keyboard player and a controller
+player:
+
+| Action | Keyboard | Gamepad |
+|---|---|---|
+| `:left` `:right` `:up` `:down` | arrow keys | dpad |
+| `:confirm` | Return | A |
+| `:fire` | Space | A |
+
+Asking for an action nothing is bound to raises `KeyError`.
+
+### Devices
+
+Device 0 is the keyboard, and it is the default — so single-player code never
+mentions devices at all. Controllers follow, one per player slot:
+
+```ruby
+Controls = RGame::Util::Controls
+
+Controls::KEYBOARD       # => 0
+Controls.gamepad(0)      # the first controller
+Controls.gamepad(1)      # the second
+Controls::MAX_GAMEPADS   # how many slots exist
+```
+
+A device only answers for its own kind of input. Asking a gamepad about a
+keyboard key is `false`, never the keyboard's answer — otherwise player two's
+pad would echo player one. The keyboard has no axes, so `axis` on it is `0.0`.
+
+### Rebinding
+
+A binding table is just a Hash of action to id, and the ids are ordinary values
+from `Util`, so a game can build its own and hand it over:
+
+```ruby
+controls = RGame::Util::Controls
+bindings = controls::DEFAULT_KEYBOARD.merge(fire: controls::KEY_RETURN)
+
+input = RGame::Core::Input.new(app, bindings: bindings)
+```
+
+`Input.new` accepts three optional tables:
+
+| Keyword | Default | Used for |
+|---|---|---|
+| `bindings:` | `Controls::DEFAULT_KEYBOARD` | keyboard buttons |
+| `pad_bindings:` | `Controls::DEFAULT_PAD` | controller buttons |
+| `axis_bindings:` | `Controls::DEFAULT_AXES` | analog axes |
+
+The defaults are frozen, so `merge` a copy rather than mutating them.
+
+## `RGame::Util::Controls`
+
+The id vocabulary. Available from `require 'rgame'` **and** from
+`require 'rgame/core'`, because these are plain integers with nothing behind
+them — a game's configuration screen can name a key without pulling in a window.
+
+**Keys** — `KEY_LEFT`, `KEY_RIGHT`, `KEY_UP`, `KEY_DOWN`, `KEY_RETURN`,
+`KEY_SPACE`, `KEY_ESCAPE`, `KEY_F1`.
+
+**Gamepad buttons** — `PAD_A`, `PAD_B`, `PAD_X`, `PAD_Y`, `PAD_BACK`,
+`PAD_GUIDE`, `PAD_START`, `PAD_LEFT_STICK`, `PAD_RIGHT_STICK`,
+`PAD_LEFT_SHOULDER`, `PAD_RIGHT_SHOULDER`, `PAD_DPAD_UP`, `PAD_DPAD_DOWN`,
+`PAD_DPAD_LEFT`, `PAD_DPAD_RIGHT`.
+
+**Axes** — `AXIS_LEFT_X`, `AXIS_LEFT_Y`, `AXIS_RIGHT_X`, `AXIS_RIGHT_Y`,
+`AXIS_TRIGGER_LEFT`, `AXIS_TRIGGER_RIGHT`. Sticks read −1.0 to 1.0 with **y
+positive downwards**; triggers read 0.0 to 1.0. No dead zone is applied — where
+to put one is a game decision, and a resting stick genuinely does report small
+non-zero values.
+
+**Devices** — `KEYBOARD`, `GAMEPAD_FIRST`, `MAX_GAMEPADS`, and
+`Controls.gamepad(slot)`.
+
+**Default tables** — `DEFAULT_KEYBOARD`, `DEFAULT_PAD`, `DEFAULT_AXES`.
+
+Buttons and keys share one numbering, partitioned into ranges, so a single
+"is it held" query serves every device. You never need the numbers themselves —
+use the constants.
+
+## `RGame::Core::Gamepad`
+
+A readout for menus — "Player 2: connect a controller". Reading a *button* goes
+through `Input`; this answers what is plugged in.
+
+```ruby
+pads = RGame::Core::Gamepad.new(app)
+
+pads.count                                # how many are connected
+pads.max_slots                            # how many slots exist
+pads.connected?(0)                        # is slot 0 filled?
+pads.name(0)                              # => "Xbox Controller", or nil
+pads.device(0)                            # the id Input wants for that slot
+pads.each_connected { |slot, name| ... }  # lowest slot first
+```
+
+`device(slot)` is the bridge to `Input`: a menu that has just found a pad can
+drive it without knowing how devices are numbered.
+
+Out-of-range slots answer rather than raising, so a UI loop needs no bounds
+checks.
+
+### Slots are stable across a replug
+
+A controller that falls out and comes back returns to the **same** slot, so
+player 2 stays player 2. The engine remembers which device last occupied each
+slot; a genuinely new controller takes the lowest free one.
+
+Two identical controllers report the same hardware id, so "the slot that
+remembers this controller" is ambiguous for them. The rule resolves it the way
+a player expects: two matching pads take slots 0 and 1, and whichever is
+unplugged gets its own slot back when it returns.
+
+## Reacting to hot-plug
+
+Polling with `Gamepad` answers "what is connected now". The `App` hooks tell you
+when that changes:
+
+```ruby
+class MyGame < RGame::Core::App
+  def initialize
+    super(width: 800, height: 600, caption: 'demo')
+    @pads = RGame::Core::Gamepad.new(self)
+    @input = RGame::Core::Input.new(self)
+  end
+
+  def gamepad_connected(slot)
+    puts "controller in slot #{slot}: #{@pads.name(slot)}"
+  end
+
+  def gamepad_disconnected(slot)
+    puts "controller left slot #{slot}"
+  end
+
+  # Read whichever device player one currently has.
+  def frame_begin
+    @device = @pads.connected?(0) ? @pads.device(0) : RGame::Util::Controls::KEYBOARD
+  end
+
+  def update(_dt)
+    @moving_left = @input.down?(:left, device: @device)
+  end
+end
+```
+
+A controller unplugged mid-press has its buttons and axes cleared, so a button
+held at that moment does not stay stuck down.

data/docs/api/internals.md

@@ -0,0 +1,110 @@
+# Internal building blocks
+
+Low-level, pure-Ruby classes the engine's [components](components.md) and
+[systems](systems.md) are built on. A game author rarely constructs these directly —
+they sit *behind* a component (a `CharacterBody` resolves through `CollisionSystem`, an
+`AnimatedSprite` plays through an `Animator`, a `CollisionWorld` indexes through a
+`SpatialHash`) — but they are documented here because they carry the load-bearing
+algorithms and are the seams the component tests drive. None `require "gosu"`.
+
+For the helpers a game *does* reach for directly (pools, localization, the camera,
+collision boxes, …), see [Utilities](toolbox.md).
+
+## `SpatialHash` — uniform-grid broadphase
+
+`RGame::Engine::SpatialHash` (`rgame/engine/spatial_hash`) is a broadphase index for collision:
+bucket colliders into fixed-size grid cells, then test only candidates that share a
+cell instead of every pair. It is the index inside
+[`CollisionWorld`](components.md#collisionworld).
+
+```ruby
+hash = RGame::Engine::SpatialHash.new(cell_size: 64)
+hash.clear                                  # reuse bucket arrays, keep capacity
+rocks.each { |r| hash.insert(r, *r.aabb) }  # insert the static set
+hash.query(*bullet.aabb) { |rock| ...narrowphase... }
+```
+
+Typical per-frame use is `clear`, `insert` every collider of one set, then `query`
+around each moving collider. Both `insert` and `query` take an AABB (`x, y, w, h`);
+an item spanning several cells is inserted into each and so **may be yielded more than
+once** by `query`. That dedup is deliberately the narrowphase caller's job — guard with
+`next if a.dead? || b.dead?` to keep hits idempotent — which lets the hash skip a
+per-query visited set and stay allocation-free. Cell keys are packed into a single
+tagged Fixnum (with an offset so off-screen / mid-wrap negative cells stay
+non-negative), so keying allocates nothing either.
+
+`query_circle(cx, cy, r, &)` is the radial counterpart to `query`: it yields the items
+in the cells the circle's bounding box covers (delegating to the same cell walk), for
+range and nearest lookups. It is still broadphase — it carries the same may-yield-twice
+contract, and the caller refines candidates by true distance (see
+[`CollisionWorld`](components.md#collisionworld)'s `query_circle`/`nearest`).
+
+## `TileCollision` — axis-separated AABB-vs-tile resolution
+
+`RGame::Engine::TileCollision` (`rgame/engine/tile_collision`) resolves an axis-aligned box against a
+grid of solid tiles. `solid` is a callable `solid.call(col, row) -> bool`, so the tile
+source is decoupled (a `TileMap`, a fake in tests). It moves the box **one axis at a
+time** — `resolve_x` then `resolve_y` (fed the resolved x) — which gives wall-sliding: a
+diagonal push into a wall keeps the component that's still free.
+
+```ruby
+tiles = RGame::Engine::TileCollision.new(tile_width: 16, tile_height: 16,
+                                  solid: ->(col, row) { map.solid_tile?(col, row) })
+nx = tiles.resolve_x(x, y, w, h, dx) # snaps flush against a solid in the dx direction
+ny = tiles.resolve_y(nx, y, w, h, dy)
+```
+
+It assumes per-step movement smaller than a tile (no tunneling), which holds for the
+engine's speeds. It is the maths inside [`CollisionSystem`](#collisionsystem--move-an-actor-against-the-tiles-and-the-world).
+
+## `CollisionSystem` — move an actor against the tiles and the world
+
+`RGame::Engine::CollisionSystem` (`rgame/engine/collision_system`) wraps `TileCollision` with a
+world-bounds clamp and an actor-facing `move`. It is what
+[`TileWorld`](components.md#tileworld) delegates to (and what a `CharacterBody` moves
+through).
+
+```ruby
+collision = RGame::Engine::CollisionSystem.new(
+  tile_collision: tiles, world_width: map.pixel_width, world_height: map.pixel_height
+)
+collision.move(actor, dx, dy) # actor responds to x / y / x= / y= / collision_box
+```
+
+`move` reads the actor's [`CollisionBox`](toolbox.md#collisionbox--an-actors-feet-box)
+AABB, resolves it through `TileCollision` on both axes, clamps the box inside the world
+as a backstop, and writes the resolved position back to the actor (accounting for the
+box's offset from the sprite origin).
+
+## `AnimationSet` — pure frame maths
+
+`RGame::Engine::AnimationSet` (`rgame/engine/animation_set`) turns an atlas's animation table plus an
+elapsed time into the sprite-sheet cell to show — no renderer, no images, fully testable.
+
+```ruby
+set = RGame::Engine::AnimationSet.new(
+  stand:      { row: 0, col: 1, frames: 1, fps: 1 },
+  walk_right: { row: 1, frames: 3, fps: 6 }
+)
+set.frame(:walk_right, elapsed) # => [row, col, flip_x]
+```
+
+Each animation is `{ row:, col: (start column, default 0), frames:, fps:, flip_x: }`.
+`frame(name, elapsed)` advances `frames` columns from `col` at `fps`, wrapping — so a
+held animation cycles.
+
+## `Animator` — animation playback state
+
+`RGame::Engine::Animator` (`rgame/engine/animator`) owns the playback state on top of an
+`AnimationSet`: the current animation name and elapsed time. It is what
+[`AnimatedSprite`](components.md#animatedsprite) drives.
+
+```ruby
+animator = RGame::Engine::Animator.new(set, initial: :stand)
+animator.play(:walk_right) # switch (a no-op if already playing, so a walk keeps cycling)
+animator.update(dt)        # advance elapsed time
+animator.frame             # => [row, col, flip_x] for the current animation now
+```
+
+`play` only restarts elapsed time on an actual change, so calling it every frame with the
+current intent keeps a continuing walk smooth rather than stuttering on frame 0.

data/docs/api/scene_graph.md

@@ -0,0 +1,159 @@
+# Scene graph
+
+The engine builds a game out of a tree of nodes — a classic scene graph. A node
+holds state, logic and drawing for one game object; nesting nodes builds up whole
+scenes. Everything is pure Ruby: nodes draw through the renderer interface and
+read input from a per-frame snapshot, never naming a graphics library at all.
+
+## Node2D
+
+`RGame::Engine::Node2D` (`engine/node2d`) is the basic building block. (The `2D` in the
+name leaves room for a future 3D node; today everything is 2D.) A node carries:
+
+- a **transform** — relative `x`, `y`, `z` plus `width`/`height`;
+- **children** — other nodes nested under it (`add_node`);
+- **components** — reusable pieces of behaviour attached to it (`add_component`);
+- a **parent** — the node it hangs off (set automatically when it is added).
+
+Nodes extend the signal DSL (`RGame::Engine::Signal::DSL`), so any subclass can declare
+and emit signals without opting in. See [Signals](signals.md).
+
+### The tick: control → update → draw
+
+A node is driven in three phases, run in this order every frame:
+
+1. `control(actions)` — read intent, both from the player (the `actions`
+   snapshot) and from AI/scripted controllers.
+2. `update(dt)` — advance game logic and physics over the timestep `dt`.
+3. `draw(renderer)` — render the current visual state.
+
+Each phase **settles the node itself first — its components, then its own hook —
+and only then descends into the children**. So you override the hook, not the
+phase itself:
+
+- `on_control(actions)`
+- `on_update(dt)`
+- `on_draw(renderer)`
+
+Self-before-subtree keeps the transform flowing downward: a component or hook
+that moves the node does so before its children resolve their origin from it (see
+[Absolute position](#absolute-position)).
+
+Because the traversal recurses into children for you, **never re-implement child
+iteration** — add children with `add_node` and let the tree drive them.
+
+### Absolute position
+
+`x`/`y`/`z` are **relative to the parent**. At the start of each phase a node
+resolves its absolute position by accumulating onto the parent's origin
+(`abs_x = parent.abs_x + x`, and likewise for `y`/`z`); a node with no parent
+sits at the origin. Moving or re-layering a node therefore moves and re-layers
+its whole subtree. (Rotation, dirty-flag caching and smarter `z`/depth handling
+are noted as future work in the source.)
+
+### View transforms and the camera
+
+A node's transform is its place in the **world**. A *view* transform is different: it
+maps that world onto the screen (a camera), and it must wrap a whole subtree's draw
+without being baked into any node's position. So `draw` calls a `draw_children` step a
+subclass can override to wrap the subtree in a renderer transform.
+
+`RGame::Engine::CameraView` is that subclass: built with an `RGame::Engine::Camera`, it wraps its
+children's draw in `renderer.translated(-camera.x, -camera.y)`. Its children draw at
+their own world origin (they never know about the camera); the translate maps them to
+the screen. Because the offset is a draw-time transform rather than a node position, the
+same world can later be drawn through several cameras — split-screen is repeating the
+pass under different offsets/clips. The owning scene drives the camera (e.g. centring it
+on the player); `CameraView` only applies it. See `examples/15_tiled_world`.
+
+## Components
+
+`RGame::Engine::Component` (`rgame/engine/component`) is a piece of behaviour you attach to a
+node instead of baking it into a subclass. A component knows its owning `node`,
+and like nodes it extends the signal DSL.
+
+- `add_component(component, as: nil)` attaches one in a **named slot** and back-links
+  it to the node. The slot defaults to the component's class, so by default a node
+  still holds **at most one component per class** — a taken slot raises. Pass a name
+  (`add_component(Timer.new, as: :spawn)`) when a node needs several of one type.
+- `get_component(key)` looks a component up by its slot: a class (matched by ancestry,
+  so a base class finds a subclass instance) or a Symbol name. A class lookup **raises
+  if it is ambiguous** — several components share that type — so name them and look up
+  by name.
+- `remove_component(key)` detaches and unlinks the component in that slot (class or
+  name), returning it (or `nil` if the slot is empty).
+
+A component mirrors the node's three phases — `control(actions)`, `update(dt)`,
+`draw(renderer)` — and the node drives its components in each phase, before its
+own hook and before its children. It also has the two tree-lifecycle hooks below
+(`on_attach`/`on_detach`).
+
+## Lifecycle: constructing vs. entering the tree
+
+A node has two distinct moments, and conflating them is a classic source of bugs
+(it is why mature engines split Godot's `_init`/`_ready`, Unity's `Awake`/`OnEnable`,
+Unreal's constructor/`BeginPlay`):
+
+1. **Construction** (`initialize`) — the node and its components exist, but the node
+   is **not yet in the live tree**. It has no resolved anchors: `root`/`scene` (below)
+   don't point anywhere useful, and shared systems aren't reachable. Build children
+   and attach components here; do **not** look anything up across the tree.
+2. **Entering the tree** — when the node becomes live, the engine runs a depth-first
+   cascade that fires, in order: each component's `on_attach`, then the node's
+   `on_add`, then the same for every child. **This is where anchors and systems are
+   available**, so it's where a component registers with a shared system. Leaving the
+   tree runs the mirror cascade — children first, then `on_remove`, then component
+   `on_detach` to release those registrations.
+
+The engine drives this; you never call it. The relevant calls are `enter_tree` /
+`exit_tree` (and `in_tree?`), fired automatically:
+
+- `add_node` enters the child immediately **iff** the parent is already live;
+  otherwise the child waits and is entered when its ancestor enters. So a node tree
+  assembled in `initialize` (before it's mounted) comes alive all at once when it
+  is. `remove_node` exits the subtree the same way.
+- `add_component` / `remove_component` fire `on_attach` / `on_detach` immediately when
+  the host node is already live (otherwise attach happens during the node's entry).
+- `SceneStack#push` / `pop` enter/exit a scene; the platform enters the root once at
+  boot (`RGame::Game#start`).
+
+**The split is load-bearing for the `on_add`/`initialize` divide:** put cross-tree
+lookups (anchors, systems, sibling components) in `on_add` / `on_attach`, never in
+`initialize`. The engine guarantees the anchors are wired before those hooks run, so
+you can't accidentally read them too early.
+
+## Anchors and shared systems
+
+Two back-links let any node reach shared state without it being threaded through
+constructors, both **resolved by walking parents** (never cached, so they can't go
+stale):
+
+- `root` — the top-most node (a node with no parent is its own root). Home for
+  global, program-lifetime systems.
+- `scene` — the nearest enclosing scene node (marked as a boundary by `SceneStack`).
+  Home for scene-lifetime systems.
+
+A *system* is just a `Component` living on one of those anchor nodes; nodes find one
+with `node.system(SomeSystem)` (scene scope first, then the global root). See
+[Systems & shared resources](systems.md) for the scoping model and worked examples.
+
+## Deferred free
+
+A node that detaches itself or a sibling mid-tick would mutate a parent's `children`
+while that list is being iterated — the classic scene-graph footgun. So removal is
+**deferred** (as in Godot's `queue_free`):
+
+- `queue_free` marks a node for removal; `freed?` reports the mark. The node stays in
+  the tree and keeps ticking until the sweep.
+- `sweep_freed` detaches every marked node, depth-first, running the normal leave-tree
+  cascade (`on_remove` / `on_detach`) on each. It runs from a safe point **outside** the
+  tick — the platform loop flushes it once per step, after `update`.
+
+Because it's deferred, any component or hook can call `node.queue_free` from inside
+`update` without corrupting the traversal. Container components that hold nodes off the
+normal child list (e.g. `SceneStack`) override `Component#sweep_freed` to forward the
+sweep into the subtree they own.
+
+`enter_tree` clears the freed flag, so a node detached and later re-added comes back
+alive. This is what lets a pool recycle nodes: a despawned (freed) node is returned to
+its pool, and re-acquiring it and `add_node`-ing it revives it cleanly.

data/docs/api/signals.md

@@ -0,0 +1,142 @@
+# 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
+`lib/rgame/engine/signal.rb`.
+
+## The Signal class: `Signal.define`
+
+`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
+
+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
+```
+
+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`.
+
+### 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**:
+
+```ruby
+ChangeSignal = Signal.define(:index, :value)
+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)`.
+
+A single-field signal does not follow this keyword convention, in this case the single parameter is non-keyworded.
+
+```ruby
+PlaySound = Signal.define(:id)
+sig.connect { @audio.play_sound(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).
+
+## 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:
+
+```ruby
+# Without the DSL:
+ClickSignal = Signal.define
+def initialize(...) = @on_clicked = ClickSignal.new
+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`:
+
+```ruby
+class Button < Control
+  extend RGame::Engine::Signal::DSL
+
+  signal :on_clicked                          # a no-arg signal
+  # signal :on_changed, Signal.define(:index, :value)  # a typed one
+
+  def activate = on_clicked_signal.emit
+end
+```
+
+`signal :on_clicked` 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`.
+
+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.
+
+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.
+
+## 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).
+
+**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.
+
+## 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.