rgame 0.1.0 → 0.2.0

data/docs/api/README.md

@@ -1,12 +1,13 @@
 # rgame API guide
 
 Reference documentation for using rgame from Ruby. The engine is written in C
-and exposed as two Ruby extensions; nothing here assumes you will read or write
-any C.
+and exposed as two Ruby extensions, with the scene graph a game is actually
+written in sitting on top of them in pure Ruby; nothing here assumes you will
+read or write any C.
 
 | Page | Covers |
 |---|---|
-| This page | Loading the library, the two namespaces, a working program, testing |
+| This page | Loading the library, the three namespaces, a working program, testing |
 | [App](app.md) | `RGame::Core::App` — the window and the frame loop |
 | [Game](game.md) | `RGame::Game` — the entry point that wires both halves together |
 | [Input](input.md) | `RGame::Core::Input`, `RGame::Util::Controls`, `RGame::Core::Gamepad` |
@@ -15,7 +16,7 @@ any C.
 | [Text](text.md) | `RGame::Core::Font` and `Renderer#text` |
 | [Audio](audio.md) | `RGame::Core::Audio`, `Sample`, `Song` — samples and streamed music |
 | [Sheets, atlases and maps](assets.md) | `RGame::Core::SpriteSheet` and the rest of the asset layer |
-| [Values](values.md) | `RGame::Util::Color`, `RGame::Util::Tensor` |
+| [Values](values.md) | `RGame::Util::Color`, `RGame::Util::Tensor`, `RGame::Util::Z` |
 
 The scene graph — `RGame::Engine`, the layer a game is actually written in:
 
@@ -24,15 +25,18 @@ The scene graph — `RGame::Engine`, the layer a game is actually written in:
 | [Scene graph](scene_graph.md) | `Node2D`, the tree, the lifecycle, transforms and the camera |
 | [Components](components.md) | Reusable behaviour attached to a node |
 | [Systems](systems.md) | Services a subtree shares — collision worlds, tile worlds |
+| [UI](ui.md) | `PlayerLayer` and `UI::Menu` — a player's own screen, navigated by focus |
 | [Signals](signals.md) | The typed observer pattern nodes talk through |
 | [Toolbox](toolbox.md) | What a game author reaches for directly: pooling, timers, camera, i18n, the audio bus |
 | [Internal building blocks](internals.md) | What components are built from: collision maths, the spatial index, animation playback |
 
 **The engine is a work in progress.** A window opens, the loop runs, input
-works, shapes, images and text can be drawn, sound plays, and a scene graph runs
-on top of it — the two games under `examples/` are built on exactly what is
-documented here. What is missing is a UI toolkit and split-screen; pages here
-describe what exists today and grow as more lands.
+works, shapes, images and text can be drawn, sound plays, and a scene graph with
+split-screen players runs on top of it — the games under `examples/` are built
+on exactly what is documented here. What is missing is a UI *toolkit*: [UI](ui.md)
+gives each player a region of the screen, focus and activation, and stops there —
+no layout, no scrolling lists, no text entry. Pages here describe what exists
+today and grow as more lands.
 
 ## Loading it
 
@@ -66,102 +70,145 @@ Both extensions must be compiled before they can be required:
 make ext        # builds both, copies them into lib/rgame/
 ```
 
-## The two namespaces
+## The three namespaces
 
-Everything lives under `RGame`, split in two by what it depends on:
+Everything lives under `RGame`, split three ways — two of them by what they
+depend on, the third by what it is *for*:
 
-| | `RGame::Util` | `RGame::Core` |
-|---|---|---|
-| Contains | shareable *values* — no window, no GPU, nothing to release | things owning a window, GPU or OS handle |
-| Today | `Color`, `Tensor`, `Controls` | `App`, `Input`, `Gamepad`, `Image`, `Renderer`, `Recording`, `Font` |
-| Loading it costs | nothing | SDL2 + OpenGL in your process |
+| | `RGame::Util` | `RGame::Core` | `RGame::Engine` |
+|---|---|---|---|
+| Contains | shareable *values* — no window, no GPU, nothing to release | things owning a window, GPU or OS handle | game concepts: the scene graph a game is written in |
+| Today | `Color`, `Tensor`, `Controls`, `Z` | `App`, `Input`, `Gamepad`, `Image`, `Renderer`, `Recording`, `Font`, `Audio`, `SpriteSheet`, `AssetManager` | `Node2D`, components, systems, signals, `TileMap`, `Player`, `InputMap`, `UI::Menu` |
+| Loading it costs | nothing | SDL2 + OpenGL in your process | nothing |
 
-The rule for deciding where something belongs: **a value goes in `Util`; only a
+The rule for splitting the bottom two: **a value goes in `Util`; only a
 handle-owner goes in `Core`.** A colour is a value. A window is not.
 
-This is not tidiness. Game logic is expected to hold `Util` types freely as
-attributes, and to reach `Core` only through objects handed to it — a node's
-`draw` receives a renderer and calls methods on it, rather than naming a class.
-That is what keeps game code runnable with no window, which the testing section
-below relies on.
+`RGame::Engine` sits above both, and its rule is what makes the split worth
+having:
+
+- it may hold `Util` values freely as attributes — a `Color`, a `Tensor`;
+- it may **not name `Core` at all** — no require, no constant, no attribute;
+- it reaches `Core` only through objects handed to it. A node's `on_draw`
+  receives a renderer and calls methods on it by name, never storing it and
+  never asking what class it is.
+
+This is not tidiness. It is what keeps a whole game — its rules, its scenes, its
+collisions — runnable and testable with no window, which the testing section
+below relies on. Two RuboCop cops enforce it in both directions, so a stray
+reference is a failing lint rather than a discovery made later.
+
+`RGame::Game` is the single exception, and the only class directly under
+`RGame`: introducing the two halves to each other is exactly what it is for, and
+confining that to one file is what keeps the rule checkable everywhere else.
 
 ## A complete program
 
+A game is a tree of nodes plus `RGame::Game` to run it.
+
 ```ruby
-require 'rgame'
-require 'rgame/core'
+require 'rgame/game'
 
-class MyGame < RGame::Core::App
-  Controls = RGame::Util::Controls
+# One game object: a square the player walks around. Pure Engine — it names no
+# graphics class, so it runs just as happily in a spec with no window.
+class Hero < RGame::Engine::Node2D
+  SPEED = 200.0
 
   def initialize
-    super(width: 800, height: 600, caption: 'My Game')
-    @input = RGame::Core::Input.new(self)
-    @renderer = RGame::Core::Renderer.new(self)
-    @x = 400.0
-    @y = 300.0
+    super(x: 400, y: 300, width: 16, height: 16)
+    @vx = 0.0
+    @vy = 0.0
   end
 
-  # One fixed simulation tick. `dt` is always the same fixed step, never
-  # wall-clock frame time, so movement is deterministic.
-  def update(dt)
-    speed = 200.0 * dt
-    @x -= speed if @input.down?(:left)
-    @x += speed if @input.down?(:right)
-    @y -= speed if @input.down?(:up)
-    @y += speed if @input.down?(:down)
+  # Intent, read once per simulation tick. Never a key: `move_x` is whatever
+  # this player's input map binds it to — arrows, WASD or a stick.
+  def on_control(actions)
+    @vx = actions.axis(:move_x) * SPEED
+    @vy = actions.axis(:move_y) * SPEED
   end
 
-  # Everything is drawn here, through a renderer built in initialize. See
-  # docs/api/drawing.md.
-  def draw
-    @renderer.rect(@x - 8, @y - 8, 16, 16)
+  # `dt` is always the same fixed step, never wall-clock frame time, so
+  # movement is deterministic. `x`/`y` are relative to the parent.
+  def on_update(dt)
+    self.x += @vx * dt
+    self.y += @vy * dt
   end
 
-  def button_down(id)
-    close if id == Controls::KEY_ESCAPE
+  # The renderer is handed in and never stored; `view` is the viewport being
+  # drawn into, which most nodes ignore. Draw from the resolved absolute
+  # position, not from `x`/`y`. See docs/api/drawing.md.
+  def on_draw(renderer, _view)
+    renderer.rect(abs_x, abs_y, width, height)
   end
 end
 
-MyGame.new.run
+# The root of the tree. Children are added in `on_add`, once the node is in a
+# tree and can reach the game around it.
+class Scene < RGame::Engine::Node2D
+  def on_add
+    add_node(Hero.new)
+  end
+end
+
+RGame::Game.new(root: Scene.new, width: 800, height: 600, caption: 'My Game').start
 ```
 
-You subclass `App` and override the hooks you care about. Everything you do not
-override is an inherited no-op — there is no `super` to remember, and no way to
-break the loop by forgetting one. See [App](app.md) for the full list.
+You subclass `Node2D` and override the hooks you care about — `on_control`,
+`on_update`, `on_draw`, and the lifecycle hooks around them. Everything you do
+not override is an inherited no-op, and the phase methods that do the
+bookkeeping (resolving the transform, driving components, descending into
+children) are not the ones you override — so there is no `super` to remember and
+no way to break the tree by forgetting one. See [Scene graph](scene_graph.md)
+for the full list, and [Game](game.md) for what `Game` assembles around it: the
+window, the renderer, the asset manager, the sound device, the input mapper and
+the players.
+
+Pass no `input_map:` and you get the default one used above: eight-way `move_x`
+/ `move_y` on the arrows, WASD, the d-pad or the left stick, plus `fire`. See
+[Input](input.md).
 
 ## Testing a game built on this
 
 The namespace split exists so that game logic can be tested without opening a
-window. Drive `update` directly and it runs as fast as the CPU allows:
+window. `require 'rgame'` gives you `Util` and the whole scene graph with no SDL
+and no OpenGL in the process, and the nodes from the program above run there
+unchanged — drive their phases directly and a simulated hour takes milliseconds:
 
 ```ruby
-# A plain object holding your game's rules — no RGame::Core anywhere.
-class Player
-  attr_reader :x
-
-  def initialize = @x = 0.0
-
-  def update(dt, moving_right:)
-    @x += 200.0 * dt if moving_right
-  end
-end
+require 'rgame'
 
-RSpec.describe Player do
+RSpec.describe Hero do
   it 'walks right at 200 units a second' do
-    player = Player.new
+    hero = Hero.new
+    # The same snapshot object the input mapper hands a node at runtime, built
+    # by hand with the stick pushed fully right.
+    actions = RGame::Engine::Actions.new(axes: { move_x: 1.0, move_y: 0.0 })
+
     # One simulated second, sixty ticks, no window and no clock.
-    60.times { player.update(1.0 / 60.0, moving_right: true) }
+    60.times do
+      hero.control(actions)
+      hero.update(1.0 / 60.0)
+    end
 
-    expect(player.x).to be_within(0.01).of(200.0)
+    expect(hero.x).to be_within(0.01).of(600.0)
   end
 end
 ```
 
-The engine deliberately makes this easy: `update` takes `dt` as an argument
-rather than reading a clock, so a test can pass whatever timestep it likes and
-simulate an hour in milliseconds.
+Two things make that work:
+
+- **`update` takes `dt` as an argument rather than reading a clock**, so a test
+  passes whatever timestep it likes. That means tests are not dependent on real time and can simulate game behavior based on time in miliseconds.
+- **A node never holds a renderer.** `on_draw` is given one, so drawing can be
+  checked by passing a recording double and asserting on what the node asked
+  for — see the renderer contract in `spec/support/shared_examples/`. All tests can be run completely headless.
+
+`hero.x` is asserted rather than `abs_x` because this node has no parent here.
+Absolute position accumulates from the parent, and a node with no parent resolves
+to the origin. Put it under a root and `abs_x` is what the rest of the engine
+reads. See [Scene graph](scene_graph.md#absolute-position).
 
-Keep the parts of your game that decide *what happens* free of `RGame::Core`,
-and hand them a renderer at draw time rather than storing one. Then the only
-code that needs a window is the thin layer that puts pixels on screen.
+Keep the parts of your game that decide *what happens* in `RGame::Engine` — the
+layer cannot name `RGame::Core`, so it cannot accidentally acquire a dependency
+on a window. Then the only code that needs one is the thin layer that puts
+pixels on screen.

data/docs/api/assets.md

@@ -361,25 +361,24 @@ frame and culled to the viewport.
 ```ruby
 tiles = app.assets.tilemap('map/island.tmx')
 
-renderer.tilemap('map/island.tmx', camera_x, camera_y, view_w, view_h, elapsed: seconds)
+renderer.tilemap('map/island.tmx', 0, camera_x, camera_y, view_w, view_h, elapsed: seconds)
 # ... the scene draws its actors here ...
-renderer.tilemap_overlay('map/island.tmx', camera_x, camera_y, view_w, view_h,
-                         z: 20, elapsed: seconds)
+renderer.tilemap('map/island.tmx', 1, camera_x, camera_y, view_w, view_h, elapsed: seconds)
 ```
 
-### Two bands, with the actors between them
+### One call per layer, because the actors go between them
 
-Layers split by Tiled's `above` custom property. The **below** band — ground and
-same-level detail — is drawn under the actors; the **above** band — tree
-canopies, roofs — over them, at a `z` the scene picks. Two calls rather than
-one, because the scene draws its actors in between; collapsing them would put
-every canopy behind every character.
+A layer is drawn on its own, in the order the caller asks for — which is what
+lets a scene put its actors between two of them, trunks under and canopies over.
+Which layers those are is a question about the scene, not about the map, so no
+`z` is passed: in a game it is [`TileMapLayer`](components.md#tileworld) mounting
+a node per layer, and the scene tree deciding the rest.
 
 ### What it costs
 
-Within each band, every tile that is **not** animated is baked into a
+Within each layer, every tile that is **not** animated is baked into a
 [recording](drawing.md#recordings-bake-once-replay-cheaply) the first time that
-band is drawn. Scrolling it afterwards is one call per texture, however many
+layer is drawn. Scrolling it afterwards is one call per texture, however many
 thousand tiles went into it. The handful that *are* animated are drawn
 individually, **culled to the viewport** — so a map far larger than the screen
 costs only what is on screen.
@@ -394,7 +393,7 @@ the asset manager rather than being loaded by the map.
 ```ruby
 def update(dt) = @elapsed += dt
 def draw(renderer)
-  renderer.tilemap(@id, camera.x, camera.y, w, h, elapsed: @elapsed)
+  renderer.tilemap(@id, @layer, camera.x, camera.y, w, h, elapsed: @elapsed)
 end
 ```
 

data/docs/api/components.md

@@ -16,9 +16,13 @@ nodes, it extends the signal DSL, so a component can declare and emit signals.
 Per-tick hooks (a node runs its components in each phase, before its own hook and
 before its children):
 
-- `control(actions)` — read intent from the per-frame action snapshot.
+- `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
+  component never learns there is more than one player.
 - `update(dt)` — advance state over the timestep.
-- `draw(renderer)` — render against the renderer interface.
+- `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.
 
 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,
@@ -102,21 +106,6 @@ draws them; this component only manages their pool membership.
   still attached. So despawning is just `node.queue_free` anywhere; the pool recycles it with
   no game-side wiring. Allocation-free in steady state.
 
-### `Clickable`
-
-Makes the owning node a world-space click target: on the click-down edge it hit-tests the
-pointer against a circle of `radius` about the node's absolute origin and emits `on_clicked`
-(no payload — the node identifies the click, like a button). It reads the pointer from the
-Actions snapshot, so it assumes screen == world (a fixed, unscrolled board; a scrolling
-camera would need the pointer unprojected first).
-
-- **Construct:** `Clickable.new(radius:, action: :ui_click)`. The action must be bound to the
-  pointer button — `action_map: { ui_click: { button: %i[pointer] } }`.
-- **Signal:** `on_clicked` fires once per press inside the radius —
-  `spot.on_clicked { build_tower }`.
-- **Phase:** `control(actions)` hit-tests and emits; allocation-free. Add it named (`as:`)
-  when a node needs more than one click region.
-
 ### `ScreenWrap`
 
 Wraps the node's position toroidally within a rectangle, so an entity leaving one edge
@@ -208,11 +197,30 @@ acts. Because enemies already register with the broadphase through their
 Draws a single registered image centered on the node's absolute origin.
 
 - **Construct:** `Sprite.new(id:, scale: 1.0, z: 0)` — `id` is a renderer image id; `z`
-  is the render layer (distinct from the node's transform `z`/`abs_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)` 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.
+- **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.
+
+### `CameraFollow`
+
+Points a camera at the node it is attached to.
+
+- **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.
+
+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.
 
 ### `ThrustController`
 
@@ -247,17 +255,19 @@ sibling's movement: `walk_left`/`walk_right`/`walk_up`/`walk_down` while moving
 on a diagonal), `stand` when still. 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` the
-  render layer.
+- **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` renders the current frame via
-  `renderer.sprite` at the node's **world** origin (`abs_x`/`abs_y`) with no angle — a
-  [`CameraView`](scene_graph.md) ancestor applies the camera offset, so the component never touches
-  the camera. (`Sprite` above is the single-image counterpart.)
+- **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.)
 
 ### `CharacterBody`
 
@@ -297,15 +307,29 @@ deterministic in tests.
 
 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`), the world bounds, and drawing the map through the scene's camera. Found
-with `node.system(TileWorld)`.
+`RGame::Engine::CollisionSystem`) and the world bounds. Found with `node.system(TileWorld)`.
+
+**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.
 
-- **Construct:** `TileWorld.new(map:, tilemap_id:, camera:)`.
+- **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`.
-- **Phase:** `draw(renderer)` draws the below band at `GROUND_Z` and the above band at `OVERLAY_Z`
-  (canopies/roofs). Actors draw at a z in between, so the renderer's z-sort composites ground < actors <
-  canopy regardless of draw-call order.
+  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.
+- **Phase:** `update(dt)` advances the map's animation clock.
+
+```ruby
+world  = scene.add_node(RGame::Engine::WorldView.new)
+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`.
 
 ```ruby
 # A node composing components, with collision meaning decided by the owner:

data/docs/api/drawing.md

@@ -34,7 +34,7 @@ would be silently discarded — and an invisible failure is worse than a loud on
 
 **Nothing is drawn immediately.** Calls accumulate, and the frame is sorted and
 sent to the GPU once, after `draw` returns. So the order you make calls in does
-not decide what ends up on top — `z:` does.
+not decide what ends up on top — the scene tree does. See "Draw order" below.
 
 ## Coordinates, colours and z
 
@@ -42,15 +42,77 @@ not decide what ends up on top — `z:` does.
 |---|---|
 | Origin | Top-left. x grows right, y grows **down**. |
 | Angles | Degrees. A **positive angle turns clockwise** on screen. |
-| `z:` | Higher is nearer the viewer. Equal z keeps call order. |
+| `z:` | Where this call sits among **this node's own** drawing. −512…511. |
 | `color:` | `nil` (white), `[r, g, b]`, `[r, g, b, a]`, or a `RGame::Util::Color`. |
 
-`z` defaults to `50` for shapes and `0` for images, so a debug box or a health
-bar drawn without a `z:` lands on top of the scene rather than under it.
+`z:` is an offset inside the current layer, not a global number. It orders a
+node's panel under its label and its shadow under its sprite, and it can reach
+nothing else — passing anything outside −512…511 raises.
 
-Equal-z stability matters more than it sounds: without it, two sprites on the
-same layer would swap places whenever the sort felt like it, which reads as
-flicker.
+It defaults to `50` for shapes, `10` for text and `0` for images, so a debug box
+or a health bar drawn without a `z:` lands on top of *that node's* sprite. Equal
+z keeps call order, which matters more than it sounds: without it two sprites on
+the same layer would swap places whenever the sort felt like it, and that reads
+as flicker.
+
+## Draw order
+
+Order is decided in three steps, coarsest first, and only the last of them is a
+number a drawing call passes.
+
+1. **The band.** `:world` (the default), `:hud`, `:overlay`, `:debug`.
+   Everything in one band is under everything in the next, whatever either drew.
+2. **The slot.** The scene tree is walked depth-first with siblings in `z`
+   order, and each node takes the next slot in its band as it is reached. So
+   draw order is **tree order**, and a node's subtree is one contiguous run —
+   a subtree is atomic and cannot straddle a sibling.
+3. **The offset.** The `z:` above, inside one node's slot.
+
+A scene graph arranges all of this for you: `RGame::Engine::Node2D#draw` opens a
+layer per node, so a game writes `z` on nodes and a `band` on the handful that
+mark one. See [scene_graph.md](scene_graph.md), "Draw order".
+
+### Opening a layer by hand
+
+Anything drawing outside the scene tree — the debug overlay, a spec, a script —
+opens its own:
+
+```ruby
+renderer.layered(:hud) do
+  renderer.nine_slice(:panel, x, y, w, h)
+  renderer.text(score, x + 8, y + 6, z: 1)   # above this layer's own panel
+end
+```
+
+`layered` takes the next slot in that band, makes it the base every `z:` inside
+is measured from, and restores the previous base afterwards (including when the
+block raises). Nesting *replaces* rather than accumulates — a node's slot is
+decided by where the traversal reached it, not by summing what its ancestors
+picked. Outside any block the base is 0, so a bare script gets exactly the z it
+passes.
+
+`renderer.layer` reports the base currently in effect.
+
+### Why bands exist at all
+
+A frame holds three kinds of content:
+
+- **World** — inside a `WorldView`, drawn once per viewport, under a camera.
+- **A player's own screen space** — their HUD, their menu, drawn once and
+  clipped to their viewport (`PlayerLayer`).
+- **Global screen space** — a cutscene, a results panel, drawn once across the
+  whole window.
+
+The first is a different *space* from the other two, and the tree enforces that:
+`WorldView` is what draws its subtree once per viewport. The last two share one
+space, and the band is what tells them apart.
+
+Two viewports interleaving in the sort is harmless — their commands carry
+different clips and land on different pixels. Order *within* one viewport is
+not, and nothing about drawing a HUD after the world puts it above the world.
+Its band does. Bands are `2**40` apart and a `z:` spans 1024, so no arithmetic
+below can carry one band into the next: containment is arithmetic rather than
+convention. See `RGame::Util::Z`.
 
 ### Colours and allocation
 
@@ -146,8 +208,7 @@ An id is normally a **root-relative path**, resolved through the app's
 renderer.sprite('example 09/player.json', row, col, x, y, flip_x: false, z: 0)
 renderer.image('space.png', cx, cy, angle: 0, scale: 1)
 renderer.background('space.png')
-renderer.tilemap('map/island.tmx', camera_x, camera_y, viewport_w, viewport_h)
-renderer.tilemap_overlay('map/island.tmx', camera_x, camera_y, viewport_w, viewport_h, z: 20)
+renderer.tilemap('map/island.tmx', layer, camera_x, camera_y, viewport_w, viewport_h)
 ```
 
 Nothing has to be set up for that: `Renderer.new(app)` takes the app's own
@@ -201,6 +262,7 @@ renderer.translated(dx, dy) { ... }
 renderer.rotated(angle, pivot_x, pivot_y) { ... }
 renderer.scaled(sx, sy = sx) { ... }
 renderer.clipped(x, y, width, height) { ... }
+renderer.layered(band) { ... }               # see "Draw order" above
 ```
 
 They nest, and they compose in the order they are opened:
@@ -238,6 +300,12 @@ def draw
 end
 ```
 
+**A game does not write that.** It is what
+[`RGame::Engine::WorldView`](scene_graph.md#view-transforms-and-the-camera) does for you,
+once per active player, with the rectangles from the layout and each player's own camera.
+Reach for `clipped` directly for a region of your own — a minimap, a scrolling list — and
+let the world band handle the split.
+
 ## Recordings: bake once, replay cheaply
 
 A tile layer is a couple of thousand quads that have not changed since the level