rgame 0.2.0 → 0.3.1

data/examples/collision_tiles/main.rb

@@ -0,0 +1,274 @@
+# frozen_string_literal: true
+
+# Collision tiles — walking into a wall.
+#
+# Run it:
+#
+#   ruby examples/collision_tiles/main.rb
+#
+# Arrow keys, WASD, a d-pad or a left stick walk the hero. The trees and the
+# fence are solid; hold a diagonal against the fence and watch what happens.
+# East of the start is a spiky ball that stops the hero and costs a life. It
+# exercises:
+#   - Components::TileWorld — the scene-scoped system that owns the map, and
+#     answers every question about what is solid;
+#   - Components::CollisionWorld — the broadphase the ball's box lives in;
+#   - Components::FeetCollider — the shape at the hero's feet, derived from the
+#     sprite's size, and the one shape both of those stop;
+#   - Components::CharacterBody with `blocked_by: %i[tiles spike]` — steps
+#     resolved against the map *and* the ball, using that shape;
+#   - CharacterBody's `on_blocked` — what stopped a step, as an event;
+#   - Components::CameraFollow — a camera on the feet rather than on the head;
+#   - Engine::Text — the life count, a key with a variable, rendered only when it changes;
+#   - the `:tilemap` asset loader and TileMapLayer, both from `examples/scroll_map`.
+#
+# ## Two indexes, one list of names
+#
+# The walls are not objects. A character against a grid of solid tiles is not a
+# pairwise overlap problem, because there are no pairs to find — a tile map
+# already knows what is where, so the wall a step would hit is arithmetic on the
+# step: divide by the tile size and ask the grid. Bucketing forty thousand tiles
+# into a spatial hash would be building a second index of something already
+# indexed, and then paying for it every frame.
+#
+# The spiky ball is an object, and it is in one. The scene mounts a
+# `CollisionWorld`, the ball wears a box on the `:spike` layer, and the hero
+# names that layer beside `:tiles`. So a step here is resolved against a grid and
+# against a broadphase at once, one axis at a time, stopping at whichever answer
+# is nearer — and the only place in this file where that shows is the list of
+# names in `blocked_by`.
+#
+# `examples/collision` is the third case, and the one neither of those is: shapes
+# that are told when they start and stop *overlapping*, with nothing stopped.
+#
+# ## What is solid is decided in Tiled, not in code
+#
+# A tile is solid because it carries a collision shape in the tileset — an
+# `<objectgroup>` on that tile in `tileset.tsx` — and `Engine::Tileset` reads
+# that. Nothing in this file lists tile ids, and adding a solid tile to the map
+# means drawing it in Tiled.
+#
+# ## A feet box, not the sprite's box
+#
+# The translucent rectangle drawn over the hero is the thing that actually
+# collides. It is twelve by six at the bottom of a sixteen by twenty-two sprite,
+# and everything above it is a picture that nothing tests.
+#
+# A top-down view needs that. The sprite is drawn as though seen from in front,
+# so its upper half is *height* rather than floor, and a character whose whole
+# frame collided could not stand with their head overlapping the fence behind
+# them — which is what standing close to it looks like from this angle.
+#
+# `FeetCollider` builds it from the node's own dimensions, which
+# `AnimatedSprite` fills in from the sprite frame when it attaches. So the box
+# follows the art: re-export the hero at a different size and the feet stay at
+# the feet. Note what the `Hero` does *not* pass — a sprite size, an offset, or
+# the box to anybody else. One component owns the shape and the body reads it.
+#
+# ## Sliding is the whole feel
+#
+# Walk diagonally into the fence and the hero keeps moving. The step is resolved
+# one axis at a time, so the blocked half is dropped and the free half is kept,
+# and a player pressing down-left against a wall travels left along it.
+#
+# It is worth doing deliberately: put the hero against the fence, hold down and
+# left together, and you arrive at the one gap in it without ever steering. A
+# version that stopped dead on contact would be correct by the letter — you did
+# walk into a wall — and would feel broken in a way a player cannot articulate.
+#
+# ## Being stopped is an event
+#
+# `on_blocked` fires on the step something starts stopping the body and
+# `on_unblocked` on the step it stops, each once per blocker. That is what spends
+# a life here: walk into the ball and lose one, keep pushing and lose no more,
+# back off and walk in again and lose another.
+#
+# It has to be that signal rather than `on_hit`, and this is the part worth
+# reading twice. Blocking leaves the two boxes exactly *touching*, and an overlap
+# test is half-open, so a successfully blocked pair does not overlap and reports
+# no contact at all. A ball that hurt through `on_hit` would have to be walked
+# into — which is exactly what blocking it prevents.
+#
+# The handler is given whatever stopped the step, and reads `layer` and `node`
+# off it the same way whichever kind it was. So the hero's one handler asks
+# `by.layer == :spike` and ignores the fence, which arrives as `:tiles` with no
+# node behind it.
+#
+# ## The system is not optional, and says so
+#
+# `blocked_by: [:tiles]` raises at attach when the scene has no `TileWorld`, and
+# again when the node has no collider to resolve, rather than falling back to
+# free movement. The fallback would look like a collision bug — an actor walking
+# through walls — and the cause would be a scene three files away that never
+# mounted the system.
+#
+# ## What this scene does not solve
+#
+# Nothing here moves but the hero. The ball is an ordinary actor with a box in
+# the broadphase, so it could walk about and block just the same — a crowd whose
+# every walker declares `%i[tiles hero npc]` is that, and shoulders past itself. A hazard that holds still is
+# simply the smaller thing to read.
+#
+# Nor is anything here overlapping. Blocking and contact are reports of two
+# different facts and a game usually wants both: a trigger walked through, a
+# pickup that vanishes, a puddle that slows whoever stands in it. Every one of
+# those is `on_hit` on a box nobody named in a `blocked_by`, which is
+# `examples/collision`.
+
+$LOAD_PATH.unshift File.expand_path('../../lib', __dir__)
+require 'rgame/game'
+
+WIDTH  = 640
+HEIGHT = 480
+ASSETS = File.expand_path('../assets', __dir__)
+LOCALES = File.expand_path('locales', __dir__) # the text on screen: locales/en.yml
+
+MAP   = 'town.tmx'
+SPEED = 80.0 # px/s
+
+# The feet: twelve wide and six tall, centred at the bottom of the 16x22 sprite.
+FEET_WIDTH  = 12
+FEET_HEIGHT = 6
+
+# Where the camera looks: the middle of that box rather than the node's origin,
+# which is the sprite's top-left corner. Without it the hero drifts below the
+# centre of the screen by half a sprite, which reads as the camera lagging.
+CAMERA_OFFSET_X = 8
+CAMERA_OFFSET_Y = 19
+
+# North of the fence and a few tiles east of its gap, so that holding a diagonal
+# into it arrives there.
+START_X = 384.0
+START_Y = 272.0
+
+# The spiky ball: three tiles east of the hero, on the open ground between the
+# trees, and low enough that its box sits across the hero's feet.
+BALL_X = 434.0
+BALL_Y = 284.0
+BALL_SIZE = 12
+
+LIVES = 3
+
+# A sprite, a feet box, a body that knows about walls, and a camera. The only
+# thing this class writes itself is the drawing of that box, so what collides is
+# visible.
+class Hero < RGame::Engine::Node2D
+  FEET = RGame::Util::Color.rgba(255, 110, 110, 120)
+
+  attr_reader :lives
+
+  def initialize(camera:, **)
+    super(**)
+    @lives = LIVES
+    add_component(RGame::Engine::Components::AnimatedSprite.new(sheet: 'hero.json'))
+    # The two lines that differ from `examples/walk`: a shape, and a body told
+    # what that shape may not pass through. Everything about the intent — the
+    # controller writing it, the sprite reading it back as a facing, the speed it
+    # is scaled by — is the same CharacterBody as there.
+    @collider = add_component(RGame::Engine::Components::FeetCollider.new(
+                                width: FEET_WIDTH, height: FEET_HEIGHT
+                              ))
+    body = add_component(RGame::Engine::Components::CharacterBody.new(
+                           speed: SPEED, blocked_by: %i[tiles spike]
+                         ))
+    # One handler for everything that can stop a step, because everything that
+    # can stop a step reports the same two things. The fence arrives here too, as
+    # :tiles with no node behind it, and is ignored.
+    body.on_blocked { |by| @lives = [@lives - 1, 0].max if by.layer == :spike }
+    add_component(RGame::Engine::Components::PlayerController.new)
+    add_component(RGame::Engine::Components::CameraFollow.new(
+                    camera: camera, offset_x: CAMERA_OFFSET_X, offset_y: CAMERA_OFFSET_Y
+                  ))
+  end
+
+  # Components draw first, so this lands over the sprite. The box's offsets are
+  # relative to the node's origin, which is exactly where the renderer already
+  # is — a collision box and local space agree about what (0, 0) means.
+  def on_draw(renderer, _view)
+    box = @collider.box
+    renderer.rect(box.offset_x, box.offset_y, box.width, box.height, color: FEET)
+  end
+end
+
+# The hazard: a box on the `:spike` layer, and a drawing of a ball with spikes on
+# it. It has no body and no controller — it never moves — so the only thing it
+# contributes to a step is its rectangle, sitting in the broadphase waiting to be
+# found.
+class SpikyBall < RGame::Engine::Node2D
+  BODY = RGame::Util::Color.rgba(190, 90, 210, 255)
+  SPIKE = RGame::Util::Color.rgba(120, 40, 140, 255)
+  RADIUS = BALL_SIZE / 2.0
+  SPIKE_LENGTH = 5
+
+  def initialize(**)
+    super
+    add_component(RGame::Engine::Components::BoxCollider.new(
+                    width: BALL_SIZE, height: BALL_SIZE, layer: :spike
+                  ))
+  end
+
+  # Local space, like every other on_draw: the node's transform is already
+  # pushed, so the ball is drawn around its own origin and lands wherever the
+  # node is.
+  def on_draw(renderer, _view)
+    renderer.line(RADIUS, -SPIKE_LENGTH, RADIUS, BALL_SIZE + SPIKE_LENGTH, thickness: 2.0, color: SPIKE)
+    renderer.line(-SPIKE_LENGTH, RADIUS, BALL_SIZE + SPIKE_LENGTH, RADIUS, thickness: 2.0, color: SPIKE)
+    renderer.circle(RADIUS, RADIUS, RADIUS, color: BODY)
+  end
+end
+
+# The scene: mount the map, mount the world, put the hero in it. The same three
+# steps as `examples/scroll_map`, with an actor that collides instead of a rig
+# that does not.
+class Scene < RGame::Engine::Node2D
+  def on_add
+    map = root.context.assets.tilemap(MAP).map
+    players = root.system(RGame::Engine::Players)
+
+    # Solidity and the world's size come from the same system, because they are
+    # the same fact about the same map. Handing it the cameras bounds them to
+    # the map's edges.
+    add_component(RGame::Engine::Components::TileWorld.new(
+                    map: map, tilemap_id: MAP, cameras: players.map(&:camera)
+                  ))
+    # The second index, for the things the map knows nothing about. Its cells are
+    # sized to the actors rather than to the 16px tiles: a broadphase cell wants
+    # to hold a handful of the things it buckets, and these are a dozen pixels
+    # across.
+    add_component(RGame::Engine::Components::CollisionWorld.new(cell_size: 32))
+
+    view = add_node(RGame::Engine::WorldView.new)
+    # The node handed back is the gap between the ground layers and anything
+    # Tiled flags `above` — where things that walk around belong.
+    actors = RGame::Engine::TileMapLayer.mount(view)
+    actors.add_node(SpikyBall.new(x: BALL_X, y: BALL_Y))
+    @hero = actors.add_node(Hero.new(camera: players.primary.camera, x: START_X, y: START_Y))
+    # Built here rather than in on_draw: the text renders once per change of the
+    # count, and the frames in between read the string it kept.
+    @lives_label = RGame::Engine::Text.new('hud.lives', :lives)
+    @help_walk = RGame::Engine::Text.new('help.walk')
+    @help_slide = RGame::Engine::Text.new('help.slide')
+    @help_box = RGame::Engine::Text.new('help.box')
+    @help_ball = RGame::Engine::Text.new('help.ball')
+  end
+
+  # Screen space: outside the WorldView, so it stays put while the map scrolls.
+  def on_draw(renderer, _view)
+    renderer.text(@help_walk, 12, 12)
+    renderer.text(@help_slide, 12, 34)
+    renderer.text(@help_box, 12, 56)
+    renderer.text(@help_ball, 12, 78)
+    renderer.text(@lives_label.with(lives: @hero.lives), 12, 100)
+  end
+end
+
+game = RGame::Game.new(
+  root: Scene.new,
+  caption: 'Collision tiles',
+  width: WIDTH,
+  height: HEIGHT,
+  media_root: ASSETS,
+  locales: LOCALES
+)
+
+game.start

data/examples/fullscreen/locales/en.yml

@@ -0,0 +1,10 @@
+# The English table: every string this example draws.
+en:
+  state:
+    fullscreen: fullscreen — F returns to a window
+    windowed: windowed — F goes fullscreen
+  modes:
+    disabled: "left/right — scale_mode :disabled, the view is the window"
+    stretch: "left/right — scale_mode :stretch, fills and distorts"
+    letterbox: "left/right — scale_mode :letterbox, uniform with bars"
+    integer: "left/right — scale_mode :integer, whole-number scale only"

data/examples/fullscreen/main.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+# Fullscreen — starting fullscreen, and switching while the game runs.
+#
+# Run it windowed or fullscreen, and start in any scale mode:
+#
+#   ruby examples/fullscreen/main.rb
+#   RGAME_FULLSCREEN=1 ruby examples/fullscreen/main.rb
+#   RGAME_SCALE=integer ruby examples/fullscreen/main.rb
+#
+# **F** (or Y on a pad) switches fullscreen. **Left and right** cycle through all
+# four scale modes. Watch the circle: it is round in three of them and an ellipse
+# in `:stretch`, which is the whole difference between uniform and per-axis
+# scaling in one shape. It exercises:
+#   - RGame::Game.new(fullscreen:) — the window opens that way;
+#   - App#fullscreen? / #fullscreen= — switching at any time;
+#   - RGame::Game#scale_mode= — switching that at any time too;
+#   - the `view` a node is drawn with — where its size comes from;
+#   - InputMap.default.merge — declaring one action of your own.
+#
+# ## Two ways in, because games need both
+#
+# **Opening fullscreen is a constructor argument, not a switch afterwards.**
+# Both end up fullscreen, but a switch made after the window is up shows one
+# windowed frame first — the flash that reads as a broken startup. Passing
+# `fullscreen: true` creates the window fullscreen and there is no first frame
+# to see. A game whose settings file says fullscreen should pass the setting
+# here, not apply it on the first tick.
+#
+# **A game need not offer a way back.** Nothing here is required: leave the
+# toggle out and the game runs fullscreen for its whole life, which is a
+# perfectly ordinary choice.
+#
+# ## Desktop fullscreen, not a mode change
+#
+# The window takes the whole screen at the screen's own resolution. Nothing asks
+# the display to switch mode, so the change is instant, costs no mode list to
+# choose from, and leaves every other window where it was. What a game gets is a
+# bigger view rather than a different one.
+#
+# ## Two answers to a bigger window, and this file shows both
+#
+# Under `:disabled` the view *is* the window: it grows, and the border below
+# grows with it because it is drawn from `view.width`. Extra screen becomes
+# extra room. That is what a tool or an editor wants, and it is why the mode
+# exists — but it is the opt-out rather than the default.
+#
+# Under any other mode `width` and `height` stop describing the window and start
+# describing the game. The view stays 512x320 however big the window is, and the
+# whole frame is scaled onto it — so the border stays exactly where it is and
+# gets bigger. That is what a play area wants, it is what `RGame::Game` does
+# unless told otherwise, and it is the only one of the two that saves a game
+# whose layout is hardcoded.
+#
+# ## Why 512x320, which is nobody's screen
+#
+# The size is picked to make the four modes *differ*, which is the opposite of
+# what a real game wants and exactly what an example about them needs.
+#
+# A logical size that shares its aspect ratio with the display makes `:stretch`
+# and `:letterbox` compute the same numbers, and one that divides the display
+# evenly makes `:integer` agree with both. Choose 640x360 on a 1920x1080 screen
+# and all three land on 3.000x3.000 — four modes, three of them identical, and
+# nothing to look at. **The prettiest resolution is the one that teaches least.**
+#
+# 8:5 matches no common display, so `:stretch` always distorts. And the fit is
+# never a whole number on a 16:9 screen, so `:integer` always gives up some
+# screen that `:letterbox` keeps. Measured, on the sizes people actually own:
+#
+#   screen       stretch        letterbox   integer
+#   1920x1080    3.75 x 3.375   3.375       3
+#   2560x1440    5.00 x 4.500   4.500       4
+#   3840x2160    7.50 x 6.750   6.750       6
+#
+# A game would choose the other way round. Pick the logical size so that the
+# scale on your players' screens is a whole number, and `:integer` costs nothing
+# at all.
+#
+# Cycling through the four with left and right is the quickest way to see what
+# each costs:
+#
+#   :disabled   the border grows to the window; nothing is scaled
+#   :stretch    fills the window; the circle goes oval
+#   :letterbox  uniform, centred, bars on two sides
+#   :integer    the same but whole-number only, so usually wider bars
+#
+# `:integer` is what keeps pixel art crisp: at 1.875x some source pixels cover
+# two screen pixels and some cover one, and the unevenness crawls as things
+# move. It costs screen — see RGame::Engine::Presentation for the measurements
+# against real screen sizes.
+#
+# ## Layout comes from the view, not from a constant
+#
+# `WIDTH` and `HEIGHT` below are what the *window* opens at and returns to. They
+# are not what to draw against: fullscreen makes the view the size of the
+# screen. Every `draw` is handed the `view` it is being drawn into, and
+# `view.width` / `view.height` are the only honest source for "how big is the
+# thing I am drawing in" — which is why the border below follows the switch with
+# nothing listening for it.
+
+$LOAD_PATH.unshift File.expand_path('../../lib', __dir__)
+require 'rgame/game'
+
+Controls = RGame::Util::Controls
+
+# Deliberately not a shape any display has — see the note above on why an
+# example about scale modes wants a resolution that scales *badly*.
+WIDTH  = 512
+HEIGHT = 320
+ASSETS = File.expand_path('../assets', __dir__)
+LOCALES = File.expand_path('locales', __dir__) # the text on screen: locales/en.yml
+
+# Set in the environment so one file can demonstrate both openings without being
+# edited. A real game reads this from its settings file — see the plan's
+# `examples/save_load`.
+START_FULLSCREEN = ENV.fetch('RGAME_FULLSCREEN', '0') != '0'
+
+# :letterbox (what RGame::Game does unless told otherwise), :integer, :stretch
+# or :disabled. A real game reads this from its settings the same way it reads
+# the fullscreen flag. This one starts on `:disabled` so that pressing right
+# walks the list in the order the prose above discusses them.
+SCALE_MODE = ENV.fetch('RGAME_SCALE', 'disabled').to_sym
+
+class Scene < RGame::Engine::Node2D
+  INSET  = 24
+  MARK   = 40
+  THICK  = 3
+  EDGE   = RGame::Util::Color.new(120, 200, 255)
+  CORNER = RGame::Util::Color.new(255, 210, 120)
+
+  DISC = RGame::Util::Color.new(180, 160, 240)
+
+  # Taken from the engine rather than written out, so this example cannot fall
+  # behind the modes that actually exist.
+  MODES = RGame::Engine::Presentation::MODES
+
+  # One Text per state rather than a string built per frame: a label made with
+  # interpolation in a draw method allocates a String every frame, which is what
+  # Game/NoInterpolationInHotPath refuses. Each mode's line is keyed by the mode.
+  STATE = { true => RGame::Engine::Text.new('state.fullscreen'),
+            false => RGame::Engine::Text.new('state.windowed') }.freeze
+  MODE_LABEL = MODES.to_h { |mode| [mode, RGame::Engine::Text.new(mode, scope: 'modes')] }.freeze
+
+  def initialize(**)
+    super
+    @mode_index = MODES.index(SCALE_MODE) || 0
+  end
+
+  def on_control(actions)
+    # `context` is the Game, which is an App. A node may not *name* RGame::Core,
+    # but it may call methods on an object it is handed — the same duck-typing a
+    # node uses on the renderer.
+    if actions.pressed?(:fullscreen)
+      app = root.context
+      app.fullscreen = !app.fullscreen?
+    end
+
+    # ui_left and ui_right come from the default map, so cycling needs no action
+    # of its own.
+    cycle_mode(-1) if actions.pressed?(:ui_left)
+    cycle_mode(1) if actions.pressed?(:ui_right)
+  end
+
+  # `view` is the region being drawn into. Under fullscreen it is the screen;
+  # windowed it is the window. Reading it rather than WIDTH/HEIGHT is the whole
+  # reason the border below keeps up.
+  def on_draw(renderer, view)
+    right = view.width - INSET
+    bottom = view.height - INSET
+
+    renderer.line(INSET, INSET, right, INSET, thickness: THICK, color: EDGE)
+    renderer.line(INSET, bottom, right, bottom, thickness: THICK, color: EDGE)
+    renderer.line(INSET, INSET, INSET, bottom, thickness: THICK, color: EDGE)
+    renderer.line(right, INSET, right, bottom, thickness: THICK, color: EDGE)
+
+    # Corner marks, so the border is not just a rectangle of unknown size: they
+    # stay put while the edges between them move.
+    renderer.rect(INSET, INSET, MARK, THICK, color: CORNER)
+    renderer.rect(INSET, INSET, THICK, MARK, color: CORNER)
+    renderer.rect(right - MARK, bottom - THICK, MARK, THICK, color: CORNER)
+    renderer.rect(right - THICK, bottom - MARK, THICK, MARK, color: CORNER)
+
+    # Round under every mode but :stretch, which scales the axes by different
+    # factors and turns it into an ellipse. One shape says more about what a
+    # mode does than the two lines of text below it.
+    renderer.circle(view.width / 2, view.height / 2, view.height / 5, color: DISC)
+
+    renderer.text(STATE.fetch(root.context.fullscreen?), INSET + 12, INSET + 12)
+    renderer.text(MODE_LABEL.fetch(MODES[@mode_index]), INSET + 12, INSET + 34)
+  end
+
+  private
+
+  def cycle_mode(step)
+    @mode_index = (@mode_index + step) % MODES.length
+    root.context.scale_mode = MODES[@mode_index]
+  end
+end
+
+game = RGame::Game.new(
+  root: Scene.new,
+  caption: 'Fullscreen',
+  width: WIDTH,
+  height: HEIGHT,
+  media_root: ASSETS,
+  locales: LOCALES,
+  fullscreen: START_FULLSCREEN,
+  scale_mode: SCALE_MODE,
+  # :fullscreen is this game's own action; everything else comes from the
+  # default map. F is a convention players already know.
+  input_map: RGame::Engine::InputMap.default.merge(
+    fullscreen: { buttons: [Controls::KEY_F, Controls::PAD_Y] }
+  )
+)
+
+game.start

data/examples/game_menu/locales/en.yml

@@ -0,0 +1,8 @@
+# The English table: every string this example draws.
+en:
+  help:
+    walk: Walk with the arrow keys — Escape opens the menu
+  menu:
+    resume: Resume
+    save: Save game
+    quit: Quit

data/examples/game_menu/main.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+# Game menu — a menu that opens over a world which keeps running.
+#
+# Run it:
+#
+#   ruby examples/game_menu/main.rb
+#
+# Walk with the arrow keys / WASD / a gamepad. Escape (or B) opens the menu;
+# up and down move the focus, Enter or A activates, Escape closes. It exercises:
+#   - PlayerLayer — one player's own region of the screen, above the world;
+#   - UI::PanelMenu / UI::PanelButton — a focused list on a panel that sizes
+#     itself to the buttons, navigated without a pointer;
+#   - UI::Menu#open / #close — a menu that is built once and shown when wanted;
+#   - Node2D#paused — one node stops while the rest of the tree carries on;
+#   - renderer.nine_slice — chrome drawn at any size from one small piece of art.
+#
+# ## The thing to watch
+#
+# **The villagers keep walking while your menu is open.** Only the hero stops,
+# because pausing is a property of a *node*, not of the world: `hero.paused =
+# true` halts that node's `control` and `update` and everything below it, and
+# nothing else in the tree notices. That is what lets two players each open
+# their own menu while the shared world runs on, and this is the single-player
+# shape of it.
+#
+# The hero and the villagers are the same three components with a different
+# controller in the middle: PlayerController reads the player's actions,
+# WanderController rolls its own directions. Nothing else about them differs.
+#
+# ## What this example does not solve
+#
+# Layout. The menu sits at a fixed margin inside the player's region, because
+# centring needs the region's size and that only arrives at draw time. See
+# docs/api/ui.md, "What this is not" — the UI package is focus and activation,
+# and no more than that yet.
+
+$LOAD_PATH.unshift File.expand_path('../../lib', __dir__)
+require 'rgame/game'
+
+WIDTH  = 640
+HEIGHT = 480
+ASSETS = File.expand_path('../assets', __dir__)
+LOCALES = File.expand_path('locales', __dir__) # the text on screen: locales/en.yml
+
+SHEET       = 'hero.json'
+HERO_SPEED  = 90.0
+NPC_SPEED   = 55.0
+NPC_SPAWNS  = [[140, 120], [430, 170], [220, 330], [480, 360]].freeze
+
+# Seeded so the villagers wander the same way every run and two driven runs can
+# be compared. `tools/drive_test_project.rb --seed N` overrides it.
+DEFAULT_SEED = 0x6E11
+
+# A walker that stays inside the window. Both the hero and the villagers are
+# this; only the controller hung on them differs.
+class Walker < RGame::Engine::Node2D
+  def on_update(_dt)
+    self.x = x.clamp(0, WIDTH - width)
+    self.y = y.clamp(0, HEIGHT - height)
+  end
+end
+
+# The pause menu: a PanelMenu, and the hero it stops.
+#
+# It lives inside a PlayerLayer, so three things are already true without this
+# class arranging any of them — it draws in that player's region, its
+# coordinates are relative to that region, and the input it reads is that
+# player's. Nothing here mentions viewports or players.
+class GameMenu < RGame::Engine::Node2D
+  PADDING     = 16
+  ITEM_WIDTH  = 180
+  ITEM_HEIGHT = 34
+  SPACING     = 8
+
+  def initialize(hero:, **)
+    super(**)
+    @hero = hero
+  end
+
+  def on_add
+    column = RGame::Engine::UI::Column.new(item_width: ITEM_WIDTH, item_height: ITEM_HEIGHT, spacing: SPACING)
+    # The panel reaches PADDING beyond the buttons, so placing the menu PADDING
+    # in puts the panel's corner at this node's origin.
+    @menu = add_node(RGame::Engine::UI::PanelMenu.new(x: PADDING, y: PADDING, padding: PADDING, layout: column,
+                                                      scope: 'menu'))
+    @menu.add(RGame::Engine::UI::PanelButton.new(label: 'resume')).on_activated { close }
+    # Disabled, so the example shows that state of the art — and because saving
+    # is `examples/save_load`'s subject rather than this one's.
+    @menu.add(RGame::Engine::UI::PanelButton.new(label: 'save', enabled: false))
+    @menu.add(RGame::Engine::UI::PanelButton.new(label: 'quit')).on_activated { root.context.close }
+    @menu.close # built once, shown when Escape asks for it
+  end
+
+  # A closed menu draws nothing and takes no focus or confirm, but its parent
+  # still reads Escape, which is what opens it again.
+  def on_control(actions)
+    toggle if actions.pressed?(:ui_cancel)
+  end
+
+  private
+
+  def toggle = @menu.open? ? close : open
+
+  def open
+    @menu.open
+    @hero.paused = true # only the hero: the villagers walk on
+  end
+
+  def close
+    @menu.close
+    @hero.paused = false
+  end
+end
+
+class Scene < RGame::Engine::Node2D
+  MENU_MARGIN = 40
+
+  def initialize
+    super
+    @rng = Random.new(ENV.fetch('RGAME_SEED', DEFAULT_SEED).to_i)
+    @help = RGame::Engine::Text.new('help.walk')
+  end
+
+  def on_add
+    hero = add_node(walker(RGame::Engine::Components::PlayerController.new,
+                           HERO_SPEED, WIDTH / 2, HEIGHT / 2))
+    NPC_SPAWNS.each do |x, y|
+      add_node(walker(RGame::Engine::Components::WanderController.new(rng: @rng), NPC_SPEED, x, y))
+    end
+
+    # The player's own layer, and the menu inside it. With one seat this covers
+    # the whole window; with two it would be half of it, and nothing here or in
+    # GameMenu would change.
+    player = root.system(RGame::Engine::Players).primary
+    layer = add_node(RGame::Engine::PlayerLayer.new(player: player))
+    layer.add_node(GameMenu.new(hero: hero, x: MENU_MARGIN, y: MENU_MARGIN))
+  end
+
+  def on_draw(renderer, _view)
+    renderer.text(@help, 12, 12)
+  end
+
+  private
+
+  def walker(controller, speed, x, y)
+    node = Walker.new(x: x, y: y)
+    node.add_component(RGame::Engine::Components::AnimatedSprite.new(sheet: SHEET))
+    node.add_component(RGame::Engine::Components::CharacterBody.new(speed: speed))
+    node.add_component(controller)
+    node
+  end
+end
+
+game = RGame::Game.new(
+  root: Scene.new,
+  caption: 'Game menu',
+  width: WIDTH,
+  height: HEIGHT,
+  media_root: ASSETS,
+  locales: LOCALES
+)
+
+# The one thing that has to be registered by hand: a nine-slice id names an
+# *element of an atlas*, not a file, so there is nothing for the asset manager
+# to resolve `:panel` to on demand. Registering the atlas binds every element in
+# it under its own name.
+game.renderer.register_ui_atlas(game.assets.ui_atlas('ui.json'))
+
+game.start