rgame 0.1.0 → 0.2.0

data/docs/api/scene_graph.md

@@ -10,7 +10,8 @@ read input from a per-frame snapshot, never naming a graphics library at all.
 `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`;
+- a **transform** — relative `x`, `y`, `angle` plus `width`/`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 automatically when it is added).
@@ -25,7 +26,8 @@ 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.
+3. `draw(renderer, view)` — render the current visual state into `view`, the
+   viewport being drawn.
 
 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
@@ -33,7 +35,14 @@ phase itself:
 
 - `on_control(actions)`
 - `on_update(dt)`
-- `on_draw(renderer)`
+- `on_draw(renderer, view)`
+
+`view` is the viewport this node is being drawn into — its rectangle, and the camera (if
+any) it is seen through. Most nodes ignore it and just draw. Two things need it: laying
+out against the edges of *this* region rather than the whole window
+(`view.x`, `view.width`), and culling (`view.visible?(x, y, w, h)`), which stops being an
+optimisation once the world is drawn once per player. See
+[Viewports](#viewports-and-views).
 
 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
@@ -44,12 +53,81 @@ 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
+`x`/`y` 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.)
+(`abs_x = parent.abs_x + x`, and likewise for `y`, with the parent's rotation
+applied); a node with no parent sits at the origin. Moving a node therefore
+moves its whole subtree. (Dirty-flag caching is noted as future work in the
+source.)
+
+**`z` is not among them, and there is no `abs_z`.** Depth is decided by where
+the traversal reaches a node, not by summing what its ancestors picked — see
+"Draw order" below.
+
+### Draw order
+
+A node's `z` says where it sits among its **siblings**, and nowhere else. The
+tree is drawn depth-first with siblings in `z` order, so:
+
+```ruby
+sky.add_node(Clouds.new(z: 2))
+sky.add_node(Birds.new(z: 1))
+sky.add_node(People.new(z: 0))
+```
+
+draws people, then birds, then clouds. Each of them may be built out of as many
+child nodes as it likes: **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. `z` is never added to anything and never reaches
+the renderer, so its magnitude means nothing — `1` and `1_000_000` behave
+identically if they are the only two children — and negatives are ordinary.
+Equal `z` keeps the order the nodes were added in.
+
+A **band** overrules all of it. `band:` is `:world` (the default), `:hud`,
+`:overlay` or `:debug`, and it is inherited down the tree 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, and nothing a node passes as `z:` can cross the gap. `WorldView` declares
+`:world` and `PlayerLayer` declares `:hud`, so most games never name a band at
+all; a node that must escape the band it inherits says so with `band:`, which is
+the one way out and is explicit.
+
+The engine turns all of this into the single number the renderer sorts on:
+`Node2D#draw` opens a layer per node, taking the next slot in its band. See
+[Drawing](drawing.md#draw-order) and `RGame::Util::Z`.
+
+### Who a node answers to
+
+`control` is handed an input **source**, not one player's snapshot — a
+[`RGame::Engine::Players`](input.md) registry, or a bare `Actions` when there is
+only ever one answer. Each node asks the source for the actions of whichever
+player owns it, and hands its components and its own `on_control` that plain
+`Actions`.
+
+Ownership is `input_owner`, and it is **inherited down the tree exactly like the
+transform**, resolved onto `abs_input_owner` alongside `abs_x`/`abs_y`:
+
+```ruby
+ship.input_owner = game.players[1]   # the ship and everything under it
+```
+
+A node that names nobody inherits its parent's; a tree that names nobody
+anywhere reads the primary player. That is what keeps single-player free of
+ceremony — no game that has one player ever mentions this.
+
+Because the *source* descends rather than the resolved snapshot, two subtrees in
+one traversal can read two different controllers, while a component still sees
+the `control(actions)` it always did.
+
+> It is `input_owner` rather than `player` because `@player` is what a game's own
+> scene usually calls its hero node, and rather than `controller` because
+> `Actor#controller` already means the thing producing movement intent.
 
 ### View transforms and the camera
 
@@ -58,13 +136,138 @@ maps that world onto the screen (a camera), and it must wrap a whole subtree's d
 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`.
+### Two words that are easy to confuse
+
+**Space** is structural and the tree enforces it: a node is either inside a
+`WorldView` or it is not, and that decides what its coordinates mean and how
+many times it is drawn.
+
+**Band** is an ordering partition: `:world`, `:hud`, `:overlay`, `:debug`. It is
+structural too — inherited down the tree, declared by `WorldView` and
+`PlayerLayer` — but it decides *what covers what* rather than what coordinates
+mean. See [Drawing](drawing.md#draw-order).
+
+They are not the same partition. All screen-space content is one *space* and is
+drawn once; the bands subdivide it by what should cover what.
+
+`RGame::Engine::WorldView` is that subclass, and it is where **world space begins**.
+Its children draw at their own world origin and never know about a camera; the node
+draws them **once per active viewport**, clipping to that viewport's rectangle and
+translating by its camera:
+
+```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 distinction
+is what separates a HUD from the world, and where it goes is the game's choice — nothing
+is imposed above the game's own root.
+
+A `WorldView` takes no camera. Cameras belong to players
+(`RGame::Engine::Player#camera`), and the node 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 — it would force the world to know how many times it is drawn.
+
+**Only `draw` multiplies.** `control` and `update` still run once per node per tick
+however many players are watching, which is what keeps simulation cost independent of
+player count — and what makes the standing "draw renders state" rule load-bearing rather
+than stylistic: a `draw` with a side effect now runs once per player.
+
+See `examples/15_tiled_world`.
+
+## Viewports and views
+
+`RGame::Engine::Viewports` is a root-scoped system holding how the screen is divided;
+`RGame::Engine::Layout` is the pure arithmetic behind it, and 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` is the same rectangle that player's world view is drawn into, so a
+HUD laid out at (10, 10) lands ten pixels inside the region the world beneath it
+occupies. It is **nil** when they have nowhere to draw: an empty seat has no
+viewport, and while the split is collapsed nobody owns a half of the screen —
+a cutscene is everyone looking at one thing, so something that must stay on
+screen through it belongs in the global overlay band instead.
+
+A **`View`** carries `x`, `y`, `width`, `height`, its `camera` (nil in screen
+space) and its `player`, plus two things nodes actually use:
+
+| | |
+|---|---|
+| `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 |
+
+**Views are reused, not rebuilt.** `Viewports` mutates one per viewport each frame, the
+way `ActionMapper` reuses its `Actions` — building fresh ones would allocate every frame.
+Hold the player or the viewports, never a `View`.
+
+**`Layout`** answers only "given a count and a window, where does each one go", with no
+state and no anchors: one viewport gets the window, two get a row each, three or four
+share a 2x2 grid. Edges are computed as `(i * total) / count`, so the rects tile exactly
+and no seam is left down the middle of an odd-sized window.
+
+### A player's own screen
+
+`RGame::Engine::PlayerLayer` is the node for it: its subtree is drawn **once**,
+clipped to that player's viewport and translated to its corner, in screen space.
+
+```ruby
+layer = scene.add_node(RGame::Engine::PlayerLayer.new(player: game.players[1]))
+layer.add_node(inventory)
+```
+
+That is the third kind of content a frame holds. The world is drawn once per
+viewport under a camera (`WorldView`), a global overlay once across the whole
+window (anything else in the tree), and this once per player inside their own
+region.
+
+It is also where the `:hud` band comes from: `PlayerLayer` declares it, so
+everything under here draws over everything in the world without any of it
+saying so.
+
+**Children are positioned relative to the layer**, so a node at (10, 10) is ten
+pixels inside *that player's* region wherever the layout put it, and the same
+HUD class serves either player unchanged. Lay out against the far edge with the
+view's **size** — `view.width - margin`. `view.x` and `view.y` are where the
+region sits on the window and are the clip's business, not a layout origin;
+adding them would offset a second time.
+
+**It sets `input_owner`**, and ownership is inherited, so a menu anywhere under
+it reads that player's controller and nobody else's. Two players with a menu
+open at once are independent without either knowing the other exists — see
+[Who a node answers to](#who-a-node-answers-to).
+
+It draws nothing when `screen_for` has no region for that player: an empty seat,
+or anybody 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 to one screen-wide view — for a cutscene, or anywhere the world should
+be seen through a single camera. **The camera is required**: promoting one player's would
+silently give everyone else their view, and choosing what is on screen is what a cutscene
+is for. Point an ordinary `Camera` however you like (a `CameraFollow` on a cutscene actor
+works) and hand it over.
+
+Both are **deferred**, like `queue_free`: they record a request and it takes effect on the
+next tick. This system is reachable from anywhere including a `draw`, and a `draw` runs
+once per view, so applying immediately would tear the frame it was requested in.
+
+A full-screen UI — a results screen, a pause panel — usually wants no collapse at all:
+draw it in screen space, outside any `WorldView`, with `band: :overlay` so it covers
+the whole window over whatever the players are seeing, HUDs included.
 
 ## Components
 
@@ -137,6 +340,30 @@ A *system* is just a `Component` living on one of those anchor nodes; nodes find
 with `node.system(SomeSystem)` (scene scope first, then the global 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 just one node, while its owner is in a menu
+```
+
+A paused node skips `control` and `update` — and so does everything under it,
+because a subtree is only ever reached through its parent. **It still draws.**
+Pausing is about time, not visibility, which is what lets a frozen world sit
+under a cutscene that keeps animating.
+
+It is a property of a *node* rather than of the world on purpose. "Pause the
+world" is `world_view.paused = true` with no new concept, and the same flag
+stops one player's character while they browse a menu without touching the
+simulation everyone else is in.
+
+There is no `abs_paused` to go with `abs_input_owner`: ownership has to be
+resolved because a node needs to know whose input it reads even when its parent
+claims nobody, while a paused node simply never descends.
+
+`draw` still resolves the transform, so a paused node under an ancestor that is
+still moving is drawn where it now is rather than where it was when it stopped.
+
 ## Deferred free
 
 A node that detaches itself or a sibling mid-tick would mutate a parent's `children`

data/docs/api/systems.md

@@ -73,6 +73,26 @@ class CircleCollider < RGame::Engine::Component
 end
 ```
 
+## The two the platform mounts for you
+
+`RGame::Game` puts two systems on the root before the tree comes alive, so any
+node can reach them without a 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.
+
+See [Input](input.md#players-seats-and-joining) and
+[Scene graph](scene_graph.md#viewports-and-views).
+
 ## Systems that index their clients (the tag-registry pattern)
 
 A many-to-many system (broadphase collision) lives on the scene node and keeps its

data/docs/api/toolbox.md

@@ -40,7 +40,7 @@ path (e.g. in `on_add`), then read it by value in `on_draw`:
 ```ruby
 @score_label = RGame::Engine::CachedLabel.new { |score| "Score: #{score}" }  # built once
 
-def on_draw(renderer)
+def on_draw(renderer, _view)
   renderer.text(@score_label[@score], 12, 10)   # cached; rebuilds only when @score changes
 end
 ```
@@ -129,24 +129,28 @@ you poll `ready?`/`consume`.
 
 ## `Camera` — follow a point, clamp to the world
 
-`RGame::Engine::Camera` (`rgame/engine/camera`) is the pure follow-and-clamp maths for a scrolling
-view: `center_on(world_x, world_y)` parks its top-left so the point is centred, but
-clamped so it never shows past the map edges (near a corner the target drifts off-centre
-instead). A scene constructs one, sizes it with the viewport and the world, and centres
-it on the player each frame.
+`RGame::Engine::Camera` (`rgame/engine/camera`) is the pure follow-and-clamp maths for a
+scrolling view. It splits into two calls, and the split is the whole design:
 
 ```ruby
-camera = RGame::Engine::Camera.new(
-  viewport_width: 640, viewport_height: 480,
-  world_width: map.pixel_width, world_height: map.pixel_height
-)
-camera.center_on(player_x, player_y) # camera.x / camera.y now hold the clamped offset
+camera = RGame::Engine::Camera.new(world_width: map.pixel_width, world_height: map.pixel_height)
+camera.center_on(player_x, player_y)   # in update: what to look at
+camera.resolve(view_width, view_height) # at draw: the offset for *this* viewport
+camera.x, camera.y                      # the resolved offset
 ```
 
-It only computes the offset; applying it is a *view transform* —
-[`CameraView`](scene_graph.md#view-transforms-and-the-camera) wraps the world subtree in
-`renderer.translated(-camera.x, -camera.y)`, and a [`TileWorld`](components.md#tileworld)
-draws the map at the same offset. See `examples/15_tiled_world`.
+`center_on` records the target; `resolve` works out the offset, clamped so the view never
+shows past the world's edges (near a corner the target drifts off-centre instead).
+**The viewport size is an argument rather than state** because the same camera is drawn
+through viewports of different sizes — a half-width one clamps differently from a
+full-width one, and the difference is visible near a world edge.
+
+**A camera belongs to a player** ([`RGame::Engine::Player#camera`](input.md#players-seats-and-joining)),
+not to a scene: a scene may have any number of viewers. Nothing calls `resolve` by hand —
+the platform resolves each camera against the viewport it is about to draw. Pointing one
+is a [`CameraFollow`](components.md#camerafollow) component on the node being followed,
+and applying it is a [`WorldView`](scene_graph.md#view-transforms-and-the-camera). See
+`examples/15_tiled_world`.
 
 ## `CollisionBox` — an actor's feet box
 

data/docs/api/ui.md

@@ -0,0 +1,98 @@
+# UI
+
+A menu you navigate with a keyboard or a controller, and the region one player's
+UI lives in.
+
+**There is no pointer**, deliberately — `RGame::Core::Input` has no mouse and the
+id range one would occupy is left unused. So there is no hover, and the thing a
+mouse-driven control takes from the cursor being over it, a control here takes
+from being the **focused** one. That is the whole design; the rest follows.
+
+## A player's own screen
+
+`RGame::Engine::PlayerLayer` is the region. Its subtree is drawn once, clipped
+to that player's viewport, translated to its corner, and driven by their
+controller:
+
+```ruby
+layer = scene.add_node(RGame::Engine::PlayerLayer.new(player: game.players[1]))
+layer.add_node(inventory)
+```
+
+See [Scene graph](scene_graph.md#a-players-own-screen) for what it does and how
+it decides there is nothing to draw.
+
+## `RGame::Engine::UI::Menu`
+
+A vertical list of things to choose from.
+
+```ruby
+menu = layer.add_node(RGame::Engine::UI::Menu.new(item_width: 220, item_height: 44))
+menu.add_item('Resume').on_activated { close }
+menu.add_item('Save').on_activated   { save }
+menu.add_item('Quit', enabled: false)
+```
+
+| | |
+|---|---|
+| `ui_up` / `ui_down` | move focus, wrapping at the ends |
+| `ui_confirm` | activate the focused item |
+| `add_item(label, enabled: true)` | append an item and return it |
+| `items`, `focused`, `focused_index` | what it holds and where focus is |
+| `focus(index)`, `focus_by(delta)` | move focus directly |
+
+Those three actions come from the [universal set](input.md#the-universal-ui-set)
+that every `InputMap` is merged over, so a menu works without a game declaring
+anything.
+
+### Focus is per player, and it costs nothing
+
+A menu inside a `PlayerLayer` inherits that player as its `input_owner`, and
+ownership is inherited down the tree — so the `actions` its `on_control`
+receives are already that player's. **Two players with a menu open at once are
+independent, and neither menu mentions players at all.**
+
+That is not a feature of the menu; it is [ownership
+routing](scene_graph.md#who-a-node-answers-to) doing its job one layer down.
+
+### `RGame::Engine::UI::MenuItem`
+
+One entry: a label on a nine-slice, and an `on_activated` signal. It draws
+itself from its **state**, which is why the shipped atlas has an element for
+each:
+
+| State | Element |
+|---|---|
+| focused | `button_focus` |
+| focused, confirm held | `button_pressed` |
+| not focused | `button_idle` |
+| `enabled: false` | `button_disabled` |
+
+A disabled item is skipped by focus movement and cannot be activated by any
+route, so a caller never has to check first.
+
+The element names are `MenuItem::STYLE`, and a menu can be built with a
+different hash — a game with its own art is not obliged to name it the way the
+shipped atlas does.
+
+### Getting the art on screen
+
+Nine-slice ids name an *element of an atlas*, not a file, so there is nothing
+for the asset manager to resolve on demand. Register the atlas once:
+
+```ruby
+game.renderer.register_ui_atlas(game.assets.ui_atlas('ui/ui_atlas.json'))
+```
+
+`media/ui/ui_atlas.json` ships with `panel` and the four button elements above.
+See [Sheets, atlases and maps](assets.md).
+
+## What this is not
+
+It is a menu, not a widget library. Items are stacked vertically at a fixed
+size, and that is the whole of its layout — no nesting, no scrolling lists, no
+text entry, and no general answer to how UI should be laid out.
+
+The package this replaces positioned everything absolutely and hit-tested a
+mouse cursor. It was deleted with the mouse, none of it is a reference, and its
+API is deliberately not preserved.

data/docs/api/values.md

@@ -99,3 +99,35 @@ grid.depth.times do |z|
   end
 end
 ```
+
+## `RGame::Util::Z`
+
+The vocabulary of draw order: which band a thing is drawn in, and the arithmetic
+that turns a band plus a position in the tree into the single number the renderer
+sorts a frame by.
+
+```ruby
+RGame::Util::Z::BANDS     # => [:world, :hud, :overlay, :debug]
+RGame::Util::Z::DEFAULT   # => :world
+RGame::Util::Z::Z_MIN     # => -512, the smallest `z:` a drawing call may pass
+RGame::Util::Z::Z_MAX     # =>  511
+```
+
+It lives here for the same reason [`Controls`](input.md) does: both the scene
+graph (which decides a node's band) and the renderer (which turns one into a z)
+have to name it, and neither may name the other's layer.
+
+Games rarely touch it. What a game writes is a node's `z` and, occasionally, a
+`band:` — see [the scene graph](scene_graph.md#draw-order). What it buys is that
+`z` numbers cannot leak between nodes and bands cannot leak into each other:
+
+| | |
+|---|---|
+| `SLOT` | 1024 — the room one node has for ordering its own drawing |
+| `Z_MIN`…`Z_MAX` | what a `z:` on a drawing call may be; anything else raises |
+| `STRIDE` | `2**40` — the gap between bands, which no `z:` can cross |
+
+Every value is an integer below `2**42`, and the `double` the draw queue sorts on
+is exact below `2**53`, so two different slots can never compare equal by
+rounding — which would show up as two sprites swapping places between frames, and
+would be very hard to recognise as a precision problem.

data/ext/README.md

@@ -29,7 +29,7 @@ ext/rgame_core/
     transform.c/.h      # pure 2D affine transform stack (unit-tested)
     clip.c/.h           # pure rects + intersecting clip stack (unit-tested)
     draw_queue.c/.h     # pure z-sort + batching of draw commands (unit-tested)
-    canvas.c/.h         # pure transform+clip+queue composition (unit-tested)
+    canvas.c/.h         # pure transform+clip+layer+queue composition (unit-tested)
     backend.h/.c        # the GL seam: function-pointer table + submit loop
     texture.c/.h        # pure texture sheets, sub-rects and UVs (unit-tested)
     primitives.c/.h     # pure rects/lines/circles/sprites -> canvas (unit-tested)
@@ -177,11 +177,11 @@ app.fps                # => Float, most recent FPS reading
 controls = RGame::Util::Controls
 input = RGame::Core::Input.new(app)
 input.down?(:fire)                                        # keyboard (the default)
-input.down?(:fire, device: controls.gamepad(0))
-input.axis(:move_x, device: controls.gamepad(0))          # => Float
+input.down?(controls::PAD_A, device: controls.gamepad(0))
+input.axis(controls::AXIS_LEFT_X, device: controls.gamepad(0))   # => Float
 
-# Rebinding is just a different table:
-RGame::Core::Input.new(app, bindings: controls::DEFAULT_KEYBOARD.merge(fire: controls::KEY_RETURN))
+# Input is the raw query: physical ids, per device. What an id *means* to a game
+# is RGame::Engine::InputMap, one table per player, a layer up.
 
 # Which controllers are plugged in — a readout for menus, not the frame path:
 pads = RGame::Core::Gamepad.new(app)
@@ -203,6 +203,7 @@ renderer.line(0, 0, 100, 100, thickness: 4)
 renderer.image(sheet, 400, 300, angle: 45, scale: 2)      # centred, clockwise
 renderer.rotated(30, 400, 300) { renderer.rect(380, 280, 40, 40) }
 renderer.clipped(0, 0, 400, 600) { renderer.background(sheet) }
+renderer.layered(:hud) { renderer.text("Score: 1200", 10, 10) }   # over the world
 
 # Text. The renderer has a font already; Font.new(app, size) makes another.
 renderer.text("Score: 1200", 10, 10)