rgame 0.1.0 → 0.3.0

data/docs/api/scene_graph.md

@@ -1,159 +1,539 @@
 # 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.
+**A game is a tree of nodes.** A node holds the state, logic and drawing of one
+game object, and nested nodes build whole scenes. The tree is pure Ruby. Nodes
+draw through the renderer interface and read input from a per-tick snapshot. They
+never name a graphics library.
 
 ## 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:
+`RGame::Engine::Node2D` (`engine/node2d`) is the basic building block. 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).
+- a **transform**: `x`, `y` and `angle` relative to its parent, plus `width` and
+  `height`, and a `z` that orders it among its siblings;
+- **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 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).
+Nodes extend the signal DSL (`RGame::Engine::Signal::DSL`), so any subclass can
+declare and emit signals. See [Signals](signals.md).
 
-### The tick: control → update → draw
+### Elevation
 
-A node is driven in three phases, run in this order every frame:
+`node.elevation` lifts a node's picture above the ground, in pixels, for a
+top-down view. It defaults to 0, and positive is up the screen.
 
-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.
+**Elevation is not part of the transform.** `y`, `world_y`, colliders, cameras and
+children all ignore it. A character can therefore leave the ground while its feet
+box and the camera following it stay put. Components that draw the node's
+picture read it: `Components::Sprite` and `Components::AnimatedSprite` draw
+lifted. `Components::Hop` writes it. A node's own `on_draw` is not lifted, so the
+parts that stay on the ground go there:
 
-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:
+```ruby
+require 'rgame'
 
-- `on_control(actions)`
-- `on_update(dt)`
-- `on_draw(renderer)`
+class Hero < RGame::Engine::Node2D
+  SHADOW = RGame::Util::Color.rgba(0, 0, 0, 90)
 
-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)).
+  def initialize(**)
+    super
+    add_component(RGame::Engine::Components::AnimatedSprite.new(sheet: 'hero.json'))
+    add_component(RGame::Engine::Components::CharacterBody.new(speed: 80))
+    add_component(RGame::Engine::Components::Hop.new(peak: 18, duration: 0.5))
+  end
 
-Because the traversal recurses into children for you, **never re-implement child
-iteration** — add children with `add_node` and let the tree drive them.
+  # A shadow at the feet: drawn in on_draw, so it stays down while the sprite rises.
+  def on_draw(renderer, _view)
+    renderer.rect(2, 19, 12, 3, color: SHADOW)
+  end
+end
+```
 
-### Absolute position
+### The tick: control → update → draw
 
-`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.)
+The engine drives a node in three phases, always in this order:
 
-### View transforms and the camera
+1. `control(actions)` reads intent, from the player (the `actions` snapshot) and
+   from AI or scripted controllers.
+2. `update(dt)` advances game logic and physics over the timestep `dt`.
+3. `draw(renderer, view)` renders the current state into `view`, the viewport
+   being drawn.
+
+**The first two run once per simulation tick; `draw` runs once per rendered
+frame.** The counts differ. The loop uses a fixed timestep, so a slow frame runs
+several ticks before it draws. A frame in which nothing advanced skips the draw.
+A `draw` must therefore depend on state alone and never read a clock. See
+[The frame loop](app.md#the-frame-loop).
+
+**Each phase settles the node first, then descends into its children.** Settling
+means the node's components run, then its own hook. You override the hook, not
+the phase:
+
+- `on_control(actions)`
+- `on_update(dt)`
+- `on_draw(renderer, view)`
+
+`view` is the viewport the node is drawn into: its rectangle and the camera, if
+any. Most nodes ignore it. Two tasks need it. One is laying out against the edges
+of *this* region, not the whole window (`view.x`, `view.width`). The other is
+culling (`view.visible?(x, y, w, h)`), which matters once the world is drawn once
+per player. See [Viewports](#viewports-and-views).
+
+The hooks run self before subtree, but no position depends on that order. A world
+position is computed when read, from wherever everything is at that moment. See
+[The two spaces](#the-two-spaces).
+
+The traversal recurses into children for you. **Never iterate children
+yourself**: add them with `add_node` and let the tree drive them.
+
+**A subclass cannot replace a `Node2D` method whose name starts with `_`.** Those
+methods are the machinery the phases call, such as `_draw_content` and
+`_resolve_inherited`. A subclass method with the same name would take its place
+without warning. So `RGame::Engine::SealedPrivates` raises `NameError` when the
+class loads, naming both methods. `Component` follows the same rule. A non-public method *without*
+the underscore is a seam, meant to be overridden with `super`. `Node2D` has one:
+`draw_children`; see
+[View transforms and the camera](#view-transforms-and-the-camera). Only these two
+classes guard underscored methods; engine subclasses do not.
+
+### The two spaces
+
+**`x`, `y` and `angle` are relative to the parent.** They are the only position a
+node sets, and the space it lives in. `rel_x`, `rel_y` and `rel_angle` are long
+names for the same three.
+
+`world_x`, `world_y` and `world_angle` accumulate that transform over the whole
+ancestry. `world_x` is `parent.world_x + x`, with the parent's rotation applied.
+A node with no parent sits at the origin.
+
+`world_x=` and `world_y=` place a node at a world coordinate. They compute the
+local position that puts it there and leave the other coordinate alone. They
+*write `x` and `y`*; they are not a second position. The node still lives in its
+parent's space. The write stays exact under a rotated ancestor, where moving along
+one world axis changes both local coordinates. On a node without a parent they
+change nothing, because that node sits at the origin.
+
+```ruby
+require 'rgame'
+
+root = RGame::Engine::Node2D.new
+container = root.add_node(RGame::Engine::Node2D.new(x: 100, y: 40))
+child = container.add_node(RGame::Engine::Node2D.new(x: 10, y: 5))
+child.world_x = 250
+child.x       # => 150
+child.world_x # => 250
+```
+
+**World coordinates are computed when read, and cached.** Moving a node marks it
+and its whole subtree stale. The next read walks up to the nearest current node
+and recomputes back down. Two properties follow, and the engine relies on both:
+
+- **A world position is never stale.** No phase takes a snapshot, so nothing goes
+  out of date. Every case answers correctly, at any point in any phase: a node
+  that moved, a node whose *ancestor* moved, a node reparented this tick, and a paused
+  node under a moving ancestor.
+- **The engine computes nothing for a node nobody asks about.** A frame in which
+  nothing moves costs nothing.
+
+Two things invalidate a world position. One is writing `x`, `y` or `angle`. The
+other is a new parent through `add_node` or `remove_node`: the same offset from
+somewhere else is still a move.
+
+**Which one to use.** Drawing needs neither; see "Drawing happens in local space"
+below. Game logic that reasons about the world reads `world_x`: a distance, a
+collision, a camera target. To move a node, write `x`. Write `world_x=` when the
+destination was decided in world space.
+[`ScreenWrap`](components.md#screenwrap) uses it to put a node on the far edge of
+the world, and a [`Mover`](components.md#mover) to write back a resolved step.
+
+**No phase resolves the transform.** Keep that in mind when a spec drives one
+phase and asserts on another's answer. The phases do resolve the *inherited*
+attributes, which are not coordinates:
+
+| Phase | Resolves | Because it reads |
+|---|---|---|
+| `control` | `abs_input_owner` | whose actions to hand each node |
+| `update` | nothing | it reads neither |
+| `draw` | `abs_band` | to open the node's own layer |
+
+**`z` is not among them, and there is no `abs_z`.** A node's depth comes from
+where the traversal reaches it, not from a sum of its ancestors' values. See
+"Draw order" below.
+
+### Drawing happens in local space
+
+**A node's `on_draw` never mentions where the node is.** `Node2D#draw` pushes the
+node's transform onto the renderer before the node and its children draw. Inside
+`on_draw`, the origin *is* the node, turned the way the node is turned:
+
+```ruby
+def on_draw(renderer, _view)
+  renderer.rect(0, 0, width, height)   # this node's own box, wherever it is
+end
+```
+
+Passing a position there applies it twice. Both spellings go wrong. `world_x`
+doubles the whole ancestry, camera included. `x` doubles the node's own offset.
+Neither raises. The mistake shows only when the node sits under a parent away from
+the origin. The `Game/DrawInLocalSpace` cop flags both.
+
+A **component** drawing for its node runs on the same path and also draws at
+`0, 0`. It may still ask the node for `node.world_x`, for example to cull against
+the camera. That reads another object's coordinate, not its own.
+
+The renderer's transform stack makes this work. The same mechanism gives a
+`WorldView` its camera: one `renderer.translated` around a subtree, composed with
+every other.
+
+### Draw order
+
+**A node's `z` orders it among its siblings, and nowhere else.** The traversal
+draws the tree depth-first, with siblings in `z` order:
+
+```ruby
+sky.add_node(Clouds.new(z: 2))
+sky.add_node(Birds.new(z: 1))
+sky.add_node(People.new(z: 0))
+```
+
+This draws people, then birds, then clouds. Each may consist of any number of
+child nodes. **A subtree is atomic**, so no part of `clouds` can end up behind
+`birds`, and no part of `birds` in front of `clouds`.
+
+Only the comparison matters. The engine never adds `z` to anything and never
+passes it to the renderer, so its magnitude means nothing. `1` and `1_000_000`
+behave the same if they are the only two children, and negatives are ordinary.
+Nodes with equal `z` keep the order they were added in.
+
+**A band overrules all of it.** `band:` is `:world` (the default), `:hud`,
+`:overlay` or `:debug`. Children inherit it, like `input_owner`:
+
+```ruby
+scene.add_node(RGame::Engine::PlayerLayer.new(player: player))  # :hud
+scene.add_node(Cutscene.new(band: :overlay))
+```
+
+Everything in `:world` draws under everything in `:hud`, whatever either asked
+for. No `z:` a node passes can cross the gap. `WorldView` declares `:world` and
+`PlayerLayer` declares `:hud`, so most games never name a band. A node that must
+leave its inherited band says so with `band:`, the one explicit way out.
+
+`Node2D#draw` turns all of this into the single number the renderer sorts on. It
+opens a layer per node, taking the next slot in the node's band. See
+[Drawing](drawing.md#draw-order) and `RGame::Util::Z`.
+
+### Who a node answers to
+
+**`control` receives an input source, not one player's snapshot.** The source is
+a [`RGame::Engine::Players`](input.md) registry, or a bare `Actions` when only one
+answer exists. Each node asks the source for the actions of the player who owns
+it. It then hands that plain `Actions` to its components and its own
+`on_control`.
+
+`input_owner` sets ownership. **Children inherit it, the way the transform
+accumulates.** `control`, the one phase that reads ownership, resolves it onto
+`abs_input_owner`:
+
+```ruby
+ship.input_owner = game.players[1]   # the ship and everything under it
+```
+
+A node that names nobody inherits its parent's owner. A tree that names nobody
+anywhere reads the primary player. Single-player games therefore never mention
+ownership.
+
+The *source* descends through the tree, not the resolved snapshot. Two subtrees
+in one traversal can thus read two different controllers, while each component
+still receives a plain `control(actions)`.
+
+> The attribute is `input_owner`, not `player`, because a game's scene usually
+> calls its hero node `@player`. It is not `controller` either, because a
+> controller is the component that produces movement intent.
 
-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.
+### View transforms and the camera
 
-`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`.
+**A node that owns a view transform overrides `draw` and calls `super` inside
+it.** A node's own transform is its place in its **parent**, and `draw` pushes it
+as the traversal descends. A *view* transform differs. It maps the world onto the
+screen, as a camera does. It belongs to no node in the tree. It must wrap a whole
+subtree's draw, including the subtree root's own drawing.
+
+`draw_children` is a separate seam. Override it to wrap or skip the *children's*
+draw while the node still draws itself. `examples/game_menu`'s menu closes by not
+calling `super` from it.
+
+`examples/scroll_map` is the smallest program with a camera: a `WorldView`, a map
+under it, and one node the camera follows.
+
+### Two words that are easy to confuse
+
+**Space** is structural, and the tree enforces it. A node is either inside a
+`WorldView` or not. That decides what its coordinates mean and how often it is
+drawn.
+
+**Band** is an ordering partition: `:world`, `:hud`, `:overlay`, `:debug`. It is
+structural too. Children inherit it, and `WorldView` and `PlayerLayer` declare
+it. But it decides *what covers what*, not what coordinates mean. See
+[Drawing](drawing.md#draw-order).
+
+The two partitions differ. All screen-space content forms one *space* and draws
+once. Bands subdivide that space by what should cover what.
+
+**`RGame::Engine::WorldView` is where world space begins.** Its children draw in
+their own local space and never know about a camera. The `WorldView` draws its
+subtree **once per active viewport**. Each time, it clips to that viewport's
+rectangle and translates by its camera. A child drawing at its own origin lands
+wherever that viewport looks:
+
+```ruby
+view = scene.add_node(RGame::Engine::WorldView.new)
+view.add_node(player)     # world coordinates
+```
+
+Everything *outside* a `WorldView` is screen space and draws once. That one line
+separates a HUD from the world. The game decides where to draw it; the engine
+imposes nothing above the game's root.
+
+**A `WorldView` takes no camera.** Cameras belong to players
+(`RGame::Engine::Player#camera`). The `WorldView` asks
+`node.system(RGame::Engine::Viewports)` which viewports exist. So the same subtree
+serves one player or four, with nothing below it changing. A camera owned by a
+node *inside* the world could not do that. The world would have to know how many
+times it is drawn.
+
+**Only `draw` multiplies.** `control` and `update` run once per node per tick,
+however many players watch. Simulation cost therefore stays independent of player
+count. It also makes the rule that `draw` only renders state essential: a `draw`
+with a side effect runs once per player.
+
+`examples/split_screen` is the smallest program with two viewports: one `Ground`,
+two walkers, a badge each, and a second player who joins mid-session.
+
+## Viewports and views
+
+`RGame::Engine::Viewports` is a root-scoped system that divides the screen.
+`RGame::Engine::Layout` holds the pure arithmetic behind it. A
+`RGame::Engine::View` is one viewport being drawn.
+
+```ruby
+viewports = node.system(RGame::Engine::Viewports)
+viewports.views              # one View per active player — what a WorldView draws through
+viewports.screen             # the whole window, no camera — screen space
+viewports.screen_for(player) # that player's own region, no camera — their HUD and menus
+```
+
+**`screen_for` returns the rectangle that player's world view uses.** A HUD laid
+out at (10, 10) lands ten pixels inside the region of the world beneath it. It
+returns **nil** when the player has nowhere to draw. An empty seat has no
+viewport. While the split is collapsed, nobody owns a part of the screen: a
+cutscene is everyone looking at one thing. Content that must stay on screen
+through a cutscene belongs in the global `:overlay` band.
+
+A **`View`** carries `x`, `y`, `width`, `height`, its `camera` (nil in screen
+space) and its `player`. Nodes mostly use two more members:
+
+| | |
+|---|---|
+| `view.visible?(x, y, w, h)` | is this worth drawing at all |
+| `view.offset_x` / `offset_y` | the translate that maps its contents onto the screen |
+
+**`Viewports` reuses its views instead of rebuilding them.** It updates one `View`
+per viewport each frame, the way `ActionMapper` reuses its `Actions`. Building
+fresh views would allocate every frame. Hold the player or the viewports, never a
+`View`.
+
+**`Layout` answers one question**: given a count and a window, where does each
+viewport go? It keeps no state and no anchors. One viewport gets the window, two
+get a row each, and three or four share a 2x2 grid. It computes edges as
+`(i * total) / count`, so the rectangles tile exactly and an odd-sized window has
+no seam.
+
+```ruby
+require 'rgame'
+
+RGame::Engine::Layout.rects(3, 640, 480) # => [[0, 0, 320, 240], [320, 0, 320, 240], [0, 240, 320, 240]]
+```
+
+`Layout.each_rect(count, width, height)` yields `index, x, y, width, height` for
+each viewport and allocates nothing. `rects` returns the same rectangles as an
+Array. The shapes it picks from are public too: `each_row(count, width, height)`,
+`each_column(count, width, height)` and `each_cell(count, cols, rows, width,
+height)`, which fills a grid left to right, top to bottom.
+
+### A player's own screen
+
+**`RGame::Engine::PlayerLayer` draws its subtree once, inside one player's
+region.** It clips to that player's viewport and translates to its corner, in
+screen space.
+
+```ruby
+layer = scene.add_node(RGame::Engine::PlayerLayer.new(player: game.players[1]))
+layer.add_node(inventory)
+```
+
+A frame holds three kinds of content. `WorldView` draws the world once per
+viewport, under a camera. Any other node draws a global overlay once across the
+window. `PlayerLayer` draws once per player, inside that player's region.
+
+`PlayerLayer` declares the `:hud` band. Everything under it draws over the world
+without saying so.
+
+**Children position themselves relative to the layer.** A node at (10, 10) sits
+ten pixels inside *that player's* region, wherever the layout put it. The same HUD
+class serves any player unchanged. To lay out against the far edge, use the view's
+**size**: `view.width - margin`. `view.x` and `view.y` place the region on the
+window; they belong to the clip, not the layout. Adding them would offset twice.
+
+**`PlayerLayer` sets `input_owner`**, and children inherit ownership. A menu
+anywhere under it reads that player's controller and nobody else's. Two players
+can each have a menu open, and neither menu knows about the other. See
+[Who a node answers to](#who-a-node-answers-to).
+
+It draws nothing when `screen_for` has no region for its player: an empty seat,
+or any player while the split is collapsed.
+
+### Collapsing the split
+
+```ruby
+node.system(RGame::Engine::Viewports).solo!(cutscene_camera)
+node.system(RGame::Engine::Viewports).split!
+```
+
+**`solo!` collapses the screen to one view through the camera you pass.** Use it
+for a cutscene, or anywhere the world should be seen through one camera. **The
+camera is required.** Promoting one player's camera would silently give everyone
+that player's view, and choosing what is on screen is a cutscene's whole job.
+Point an ordinary `Camera` however you like, for example with a `CameraFollow` on
+a cutscene actor, and pass it in.
+
+**Both calls are deferred**, like `queue_free`. They record a request that takes
+effect on the next tick. `solo?` answers for the mode in effect, so it changes on
+that tick too. Any code can reach this system, including a `draw`. A
+`draw` runs once per view, so an immediate change would tear the frame that
+requested it.
+
+A full-screen UI, such as a results screen or a pause panel, usually needs no
+collapse. Draw it in screen space, outside any `WorldView`, with `band: :overlay`.
+It then covers the whole window over the players' views, HUDs included.
 
 ## 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`).
+**A `RGame::Engine::Component` (`rgame/engine/component`) is behaviour you attach
+to a node** instead of building it into a subclass. A component knows its owning
+`node`, and extends the signal DSL like a node.
+
+- `add_component(component, as: nil)` attaches a component in a **named slot**
+  and links it to the node. The slot defaults to the component's class, so a node
+  holds **at most one component per class** by default. A taken slot raises. Pass
+  a name when a node needs several of one type:
+  `add_component(Timer.new, as: :spawn)`.
+- `get_component(key)` looks a component up by slot. The key is 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**, when several components share the type.
+  Name them and look them up by name.
+- `remove_component(key)` detaches the component in that slot (class or name) and
+  returns it, or `nil` if the slot is empty.
+
+A component mirrors the node's three phases: `control(actions)`, `update(dt)` and
+`draw(renderer, view)`. In each phase the node drives its components before its
+own hook and before its children. Components also have two tree-lifecycle hooks,
+`on_attach` and `on_detach`, described below.
 
 ## 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.
+**A node has two distinct moments.** Mixing them up causes bugs that are hard to
+trace.
+
+1. **Construction** (`initialize`): the node and its components exist, but the
+   node is **not yet in the live tree**. Its anchors are unresolved: `root` and
+   `scene` (below) point nowhere useful, and shared systems are out of reach.
+   Build children and attach components here. Do **not** look anything up across
+   the tree.
+2. **Entering the tree**: when the node goes live, the engine runs a depth-first
+   cascade. It fires each component's `on_attach`, then the node's `on_add`, then
+   the same for every child. **Anchors and systems are available here**, so a
+   component registers with a shared system at this point. Leaving the tree runs
+   the mirror cascade: children first, then `on_remove`, then each component's
+   `on_detach` to release its registrations.
+
+The engine drives this; you never call it. It uses `enter_tree`, `exit_tree` and
+`in_tree?`, fired at these points:
+
+- `add_node` enters the child at once **only if** the parent is already live.
+  Otherwise the child enters when its ancestor does. A tree assembled in
+  `initialize` therefore comes alive all at once when it is mounted. `remove_node`
+  exits the subtree the same way.
+- `add_component` and `remove_component` fire `on_attach` and `on_detach` at once
+  when the host node is live. Otherwise attachment happens when the node enters.
+- `SceneStack#push` and `pop` enter and exit a scene. `RGame::Game#start` enters
+  the root once, at boot.
+
+**Put cross-tree lookups in `on_add` or `on_attach`, never in `initialize`.** That
+covers anchors, systems and sibling components. The engine wires the anchors
+before those hooks run, so you cannot read them too early.
+
+The mirror rule is that *attaching* components belongs in `initialize` or a
+builder. Use `on_add` only when the component's constructor needs the tree. See
+[Where to add a component](components.md#where-to-add-a-component).
 
 ## 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):
+Two back-links let any node reach shared state without constructor arguments.
+**The engine resolves both by walking up the parents**, never caching them, so
+they cannot go stale:
+
+- `root` is the top-most node; a node without a parent is its own root. Global
+  systems that live as long as the program belong there.
+- `scene` is the nearest enclosing scene node, marked as a boundary by
+  `SceneStack`. Systems that live as long as a scene belong there.
+
+A *system* is a `Component` on one of those anchor nodes. A node finds one with
+`node.system(SomeSystem)`, which checks the scene first and then the root. See
+[Systems & shared resources](systems.md) for the scoping model and worked
+examples.
+
+## Pausing a subtree
+
+```ruby
+world_view.paused = true    # the world stops; an overlay above it does not
+walker.paused = true        # or one node, while its owner is in a menu
+```
+
+**A paused node skips `control` and `update`, and so does its whole subtree**,
+because the traversal reaches a subtree only through its parent. **It still
+draws.** Pausing concerns time, not visibility. A frozen world can therefore sit
+under a cutscene that keeps animating.
+
+Pausing belongs to a *node*, not to the world. "Pause the world" is
+`world_view.paused = true`, with no new concept. The same flag stops one player's
+character while they browse a menu, without touching everyone else's simulation.
 
-- `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.
+No `abs_paused` exists to match `abs_input_owner`. A node needs its resolved owner
+even when its parent names nobody. A paused node, by contrast, never descends.
 
-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.
+A paused node under a moving ancestor draws where it is now, not where it
+stopped. The engine also culls it against its current position. Neither depends
+on the node running a phase. The traversal pushes the transform as it descends,
+and `world_x` computes itself when read. See [The two spaces](#the-two-spaces).
 
 ## 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`):
+**Removal is deferred.** A node that detached itself or a sibling mid-tick would
+change a parent's `children` while the traversal iterates that list.
 
-- `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`.
+- `queue_free` marks a node for removal, and `freed?` reports the mark. The node
+  stays in the tree and keeps ticking until the sweep.
+- `sweep_freed` detaches every marked node, depth-first, and runs the normal
+  leave-tree cascade (`on_remove` / `on_detach`) on each. The game loop calls it
+  once per step, after `update`, outside the traversal.
 
-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.
+Any component or hook can therefore call `node.queue_free` from inside `update`
+without corrupting the traversal. A component that holds nodes outside the normal
+child list, such as `SceneStack`, overrides `Component#sweep_freed` to pass the
+sweep into the subtree it owns.
 
-`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.
+`enter_tree` clears the freed flag, so a node detached and added again comes back
+alive. Pools rely on this. A despawned node returns to its pool, and acquiring it
+and calling `add_node` revives it cleanly.