rgame 0.2.0 → 0.3.0

data/docs/api/examples.md

@@ -0,0 +1,263 @@
+# Examples
+
+`examples/` holds one small program per concept. Each is a single `main.rb` that
+runs on its own:
+
+```
+ruby examples/walk/main.rb
+```
+
+**An example answers "how do I do *X*".** The complete games under
+`test_projects/` answer that poorly. An example shows one concept in one file,
+and its header comment explains the concept at length. This page is the index;
+the file is the long version.
+
+Every example has an acceptance test as well. A scripted input track lives at
+`tools/drive/examples/<name>.rb`. The harness feeds that track to the unmodified
+program and reports what the game asked for:
+
+```
+ruby tools/drive_test_project.rb examples/walk/main.rb --ticks 240
+```
+
+The examples' assets live under `examples/assets/` and are redistributable, so
+every example runs from a fresh clone. Most examples need no art at all.
+
+## Movement and drawing
+
+### walk
+
+A player-controlled sprite: the smallest complete game. It is a plain node with
+three components, and no component knows about the others.
+
+**Uses:** `Node2D`, `Components::AnimatedSprite`, `Components::CharacterBody`,
+`Components::PlayerController`, `InputMap.default`.
+
+### sprite
+
+One frame drawn at a node, with no animation. Most things in a game look like
+this. The draw passes no position and no angle, because the node's transform
+already applies.
+
+**Uses:** `Components::Sprite`, `Image#subimage`, `renderer.register_image`.
+
+### velocity
+
+The second way a node moves. A character has an *intent*. A rock has a velocity,
+and a component integrates it, spin included.
+
+**Uses:** `Components::Velocity`, `Components::ScreenWrap`, `Components::World`,
+`Components::WorldBounds`.
+
+## The world
+
+### scroll_map
+
+A Tiled map larger than the window, scrolled by a player. No call pans the
+camera. A component on a node points the camera, so scrolling is walking.
+
+**Uses:** the `:tilemap` asset loader, `Components::TileWorld`, `TileMapLayer`,
+`WorldView`, `Camera`, `Components::CameraFollow`.
+
+### collision
+
+Object-to-object collision. A scene-scoped system pairs up shapes each step and
+tells both sides they overlapped. It never learns what either object is.
+
+**Uses:** `Components::CollisionWorld`, `Components::CircleCollider`,
+`Components::BoxCollider`, `Components::Velocity`, `Engine::Text`.
+
+### collision_tiles
+
+A character against a grid of solid tiles, sliding along a wall while walking
+diagonally. East of the start, a spiky ball stops the hero and costs a life. One
+feet box is thus stopped by two indexes: the map's grid and the broadphase.
+`blocked_by: %i[tiles spike]` is the only place the difference shows. The life is
+spent in `on_blocked`, because a blocked pair ends up touching, not overlapping.
+`on_hit` never fires for it.
+
+**Uses:** `Components::TileWorld`, `Components::CollisionWorld`,
+`Components::FeetCollider`, `Components::CharacterBody` with
+`blocked_by: %i[tiles spike]` and `on_blocked`, `Components::CameraFollow`,
+`Engine::Text`.
+
+### jump_topdown
+
+A hop in a top-down view. "Up" on screen is north, so a jump cannot move the
+character. The sprite rises along `Hop`'s parabola. The feet box, the shadow and
+the camera stay on the ground. A hop at the fence therefore does not clear it,
+because the part that collides never leaves the ground. The game decides what a
+hop may cross, through `airborne?`.
+
+**Uses:** `Components::Hop`, `Node2D#elevation`, `Components::AnimatedSprite`,
+`Components::FeetCollider`, `Components::CharacterBody`, `Components::TileWorld`,
+`Components::CameraFollow`, `InputMap.default.merge`.
+
+### pathfinding
+
+Pick a tile, and the hero works out how to get there. Small dots show the route
+the search found, one per tile. Lines show the route the hero walks. The
+navigator pulls the route tight, keeping each line straight as long as the hero's
+feet box fits.
+
+**Uses:** `Components::Navigator`, `Components::TileWorld#nav_grid`,
+`Components::AnimatedSprite`, `Components::ActionTrigger`,
+`Components::CameraFollow`, `Engine::Text.computed` over `I18n.t` with plurals.
+
+## Structure
+
+### signals
+
+Declaring your own signal. A pressure plate announces that it was pressed, and
+does nothing more. The door and the lamp connect to it; the plate never names
+them.
+
+**Uses:** `Signal::DSL`, `Signal.define`, `Components::ActionTrigger`, the
+connect handle.
+
+### timer
+
+Periodic behaviour that no input drives: a spawn cadence and a one-shot, with two
+cadences on one node.
+
+**Uses:** `Components::Timer` (repeating and `repeating: false`, and `as:`),
+`Engine::Timer`.
+
+### pooling
+
+Spawning many things without building any of them. The allocation count on
+screen makes the case.
+
+**Uses:** `Components::Pool`, `Engine::Pool`, `Components::DespawnOffscreen`,
+`Components::Timer`, `Engine::Text`.
+
+## UI
+
+### game_menu
+
+A menu that opens over a running world. Pausing belongs to a node, so only the
+hero stops while the villagers walk on.
+
+**Uses:** `PlayerLayer`, `UI::PanelMenu`, `UI::PanelButton`, `UI::Menu#open` /
+`#close`, `Node2D#paused`, `renderer.nine_slice`.
+
+### menu_navigation
+
+Several screens (title, settings, back) and settings that change something real
+and survive a restart. It contrasts pushing a scene with replacing one.
+
+**Uses:** `Scene::SceneStack`, `UI::OptionButton`, `Util::SaveFile`,
+`RGame::Game`'s fullscreen, scale mode and volume.
+
+### radial_menu
+
+Choosing by pointing. Eight icons sit on a wheel, focused by the direction of the
+stick or the arrow keys. A released stick selects nothing, so pressing A at rest
+never picks what the stick passed on its way back.
+
+**Uses:** `UI::RadialMenu`, `UI::IconButton` on a disc `UI::ShapeStyle`,
+`ui_radial_x` / `ui_radial_y`, and a UI atlas's `images` (`icons.json`).
+
+### quick_wheel
+
+The same eight icons, on a wheel held open by Tab or the left shoulder button.
+Releasing the button chooses. A stick released a moment before the button still
+chooses; a stick at rest chooses nothing. The world drifts at a quarter speed
+while the wheel is open.
+
+**Uses:** `UI::RadialMenu` with `trigger:`, `UI::Pointing`'s grace window,
+`UI::Menu#on_opened` / `#on_closed`, `InputMap.default.merge`.
+
+### skill_bar
+
+A tool bar with five tools in a row. Left and right step through them and Enter
+uses one. The number keys use a tool directly, without moving the focus. Holding
+a number uses its tool once. Pressing a tool's number and Enter together also
+uses it once.
+
+**Uses:** `UI::Row`, `UI::Stepping` taking its axis from the layout,
+`UI::Button`'s `hotkey:` and `activate_on: :press`, captioned `UI::IconButton`s
+on a disc `UI::ShapeStyle`, `InputMap.default.merge`, and a UI atlas's `images`
+(`skills.json`).
+
+## Audio
+
+### sound
+
+A sound effect fired by a button, and the path it travels. A node may not name
+the audio device, so it emits a fact and a director plays it.
+
+**Uses:** `Core::Sample`, `Engine::AudioBus`, `Engine::AudioDirector`,
+`Engine::Text`.
+
+### music
+
+The other kind of sound: one streamed voice. You can stop it and ask whether it
+plays, and starting it again does not restart it.
+
+**Uses:** `Core::Song`, `AudioBus.play_music` / `.stop_music`,
+`Engine::AudioDirector`.
+
+## Players and input
+
+### split_screen
+
+Two players in one world. `WorldView` draws the world once per viewport, through
+that viewport's camera. The world never knows how often it is drawn.
+
+**Uses:** `Game.new(players: 2)`, `Engine::Players`, `Engine::WorldView`,
+`Engine::PlayerLayer`, `Engine::Camera`, `Components::CameraFollow`,
+`input_owner`.
+
+### input_glyphs
+
+Prompts that match the device in the player's hands. They switch between
+keyboard and controller mid-session. Nothing listens for a plugged-in pad; using
+the pad takes the seat.
+
+**Uses:** `Controls.gamepad?`, `InputMap#button_for`, `Engine::Players` with
+`on_unassigned_input` defaulting to `:takeover`, `renderer.sprite`.
+
+## The window
+
+### fullscreen
+
+Opening fullscreen, switching while the game runs, and all four scale modes with
+the layout following each.
+
+**Uses:** `RGame::Game.new(fullscreen:)`, `App#fullscreen?` / `#fullscreen=`,
+`RGame::Game#scale_mode=`, the `view` a node is drawn with,
+`InputMap.default.merge`.
+
+## Language
+
+### localization
+
+The same screen in English and German. A `Text` with a `count` picks its plural
+form, and one with a variable shows the current locale. German lacks one key, so
+that line falls back to English. The player's language choice overrides the
+operating system's and is saved.
+
+**Uses:** `Engine::I18n`, `Engine::Text` and `Text.literal`, `UI::Menu`'s
+`scope:`, `RGame::Game.new(locales:)`, `RGame::Core.preferred_locales`,
+`Util::SaveFile`.
+
+## Persistence
+
+### save_load
+
+Writing game state to disk and restoring it. The tree is not saved: a scene is a
+recipe, and a save file is state. The variable holding a singular thing restores
+it, and array order restores a flock.
+
+**Uses:** `Util::SaveFile`, the `examples/walk` composition with a
+`WanderController`.
+
+### save_load_ids
+
+The case `save_load` leaves out: a collection whose members can be lost, and one
+saved object that refers to another. A reference forces ids; a changing
+collection alone does not.
+
+**Uses:** `Components::Identity`, `Util::SaveFile`, a save of records rather
+than positions.

data/docs/api/game.md

@@ -1,10 +1,9 @@
 # `RGame::Game`
 
-The entry point of a game, and the one class that knows both halves of the
+`Game` is a game's entry point, and the one class that knows both halves of the
 engine.
 
 ```ruby
-$LOAD_PATH.unshift File.expand_path('../lib', __dir__)
 require 'rgame/game'
 
 class HelloScene < RGame::Engine::Node2D
@@ -14,13 +13,16 @@ end
 RGame::Game.new(root: HelloScene.new, caption: 'Hello').start
 ```
 
-A complete game is a root node plus that. `Game` assembles what a running game
-needs around it — the window and its loop, the renderer, the asset manager, the
-sound device, the input mapper, the debug overlay — and drives the root node.
+A root node plus those lines make a complete game. `Game` builds what a running
+game needs and drives the root node. It builds the window and its loop, the
+renderer, the asset manager, the sound device, the input mapper and the debug
+overlay.
 
 ```ruby
 RGame::Game.new(root:, width: 640, height: 480, caption: 'RGame',
-                media_root: 'media', input_map: nil, device: Controls::KEYBOARD)
+                media_root: 'media', input_map: nil, device: Controls::KEYBOARD,
+                players: 1, input: nil, fullscreen: false, scale_mode: :letterbox,
+                locales: 'locales')
 ```
 
 | Reader | |
@@ -28,46 +30,140 @@ RGame::Game.new(root:, width: 640, height: 480, caption: 'RGame',
 | `root` | the node tree |
 | `renderer` | what scenes draw through |
 | `players` | who is playing: their devices, bindings and cameras |
+| `viewports` | how the screen is divided between players |
+| `scale_mode`, `scale_mode=` | how the logical size maps onto the window; switchable while the game runs |
 | `assets`, `audio`, `media_root`, `width`, `height`, `fps` | inherited from [App](app.md) |
 
-`start` brings the tree live — it hands the game to the root as its `context`,
-calls `enter_tree`, and runs the loop until the window closes. `F1` toggles the
-debug overlay and `F2` quits.
+A node reaches `players` and `viewports` as systems:
+`node.system(RGame::Engine::Players)` and `node.system(RGame::Engine::Viewports)`.
 
-**Both development keys are function keys, and `Esc` is deliberately left
-alone.** Escape is the button a player expects to back out of a menu, so it
-belongs to the game rather than to the engine's debug shortcuts — binding it
-here would take it away from every game built on this one.
+`input:` replaces the input backend. A test harness passes a scripted backend
+here to drive a game without hardware. A game passes nothing.
 
-## Why this class exists at all
+### `scale_mode:` — what `width` and `height` mean
 
-`RGame::Engine` holds game concepts and may not name
-`RGame::Core`; `RGame::Core` owns windows, textures and sound devices and may
-not know Engine exists. Two RuboCop cops enforce that. Something still has to
-introduce them, and **this is that something** — keeping the introduction in one
-file is what makes the rule checkable everywhere else.
+**`width` and `height` are the logical size**: the resolution the game is
+designed in. `Game` maps the whole frame onto the window, whatever its size. The
+view a node draws into keeps the logical size. A layout written against fixed
+numbers therefore works at any window size, fullscreen included.
 
-The tile map is the clearest case: parsing a `.tmx` is Engine's job, drawing one
-is Core's, and neither may call the other. So `Game` installs the loader that
-joins them, and `app.assets.tilemap('map/island.tmx')` works from then on.
+| | |
+|---|---|
+| `:letterbox` | The default. Largest uniform scale that fits, centred, bars on two sides. |
+| `:integer` | The same, rounded down to a whole number. |
+| `:stretch` | Fill the window, distorting if the aspect ratios differ. |
+| `:disabled` | No scaling at all: `width` and `height` are the window, and the view is too. |
+
+**`:disabled` turns scaling off and changes what the numbers mean.** The view
+becomes the window, so a bigger window hands every `draw` a bigger view. A layout
+written against `view.width` grows into the space. A layout written against fixed
+numbers stays in the top-left corner. Choose `:disabled` for a program that uses
+whatever space it gets: a tool, an editor, a program that is all HUD. Do not
+choose it for a game with a designed play area. It is the only mode that pushes
+no clip, translate or scale.
+
+```ruby
+require 'rgame/game'
+
+class Root < RGame::Engine::Node2D; end
+
+RGame::Game.new(root: Root.new, width: 320, height: 180, scale_mode: :integer).start
+```
+
+**Choose `:integer` for pixel art.** A whole-number factor draws every source
+pixel as the same square on screen. A fractional factor gives some pixels two
+screen pixels and some three, and the unevenness crawls whenever anything moves.
+The mode can waste a lot of screen. A 640x480 design gets only 1x on a 1600x900
+window, because 2x needs 960 rows. `RGame::Engine::Presentation` holds the
+arithmetic and documents the measurements. It is pure and has its own specs.
+
+A resize refits the mode and changes nothing else. Viewports, split-screen rects
+and camera clamps already use logical units.
+
+`examples/fullscreen` runs in every mode, chosen by an environment variable.
+
+`fullscreen:` opens the window fullscreen, so the game shows no windowed frame
+at startup. `width` and `height` then give the size the window returns to, if
+the game offers a way back. See [Fullscreen](app.md#fullscreen) and
+`examples/fullscreen`.
+
+`start` brings the tree live. It hands the game to the root as its `context`,
+mounts `Players` and `Viewports` on the root, and subscribes an `AudioDirector` to
+the [`AudioBus`](toolbox.md#audiobus--decoupled-audio-facts). It then calls
+`enter_tree` and runs the loop until the window closes. When the loop ends, it
+unsubscribes the director. `F1` toggles the debug overlay and `F2` quits.
+
+The debug overlay is an `RGame::Engine::DebugOverlay`. It shows frames per
+second, the total objects allocated, and the objects allocated since its last
+frame, in the bottom-right corner. `F1` calls its `toggle`.
+
+Each tick, `Game` polls input, runs `control` and `update` on the tree, and sweeps
+freed nodes. It redraws only when a tick ran or the debug overlay is visible.
+
+**Both development keys are function keys, and `Esc` stays free.** Players expect
+Escape to back out of a menu, so it belongs to the game. A debug shortcut on it
+would take it away from every game built on `Game`.
+
+## Why this class exists
+
+`RGame::Engine` holds game concepts and may not name `RGame::Core`.
+`RGame::Core` owns windows, textures and sound devices, and may not know Engine
+exists. **`Game` connects the two.** Keeping that connection in one file lets the
+rule hold everywhere else. Inside rgame's own repository, two RuboCop cops enforce
+it.
+
+The tile map shows why. Engine parses a `.tmx`; Core draws it; neither may call
+the other. `Game` installs the loader that joins them, so
+`app.assets.tilemap('map/island.tmx')` works.
+
+## Translations and the player's language
+
+**`Game.new` loads every translation table and picks the player's language**, so
+a game writes no i18n setup. It lists every `.yml` under `locales:` with
+`AssetManager#glob`, sorted by path, and loads each through the asset manager's
+`:locale` loader into [`RGame::Engine::I18n`](localization.md).
+Two files that define one locale merge in that order, so a key the later file
+sets wins. It then sets `I18n.locale` to
+`I18n.choose(RGame::Core.preferred_locales)`: the first locale the OS prefers
+that a table covers, unshortened, or the default.
+
+`locales:` is relative to `media_root` unless it is absolute. A directory that
+does not exist loads nothing, and every key then shows as itself.
+
+```ruby
+game = MyGame.new(root: Root.new, media_root: 'media')   # loads media/locales/**/*.yml
+RGame::Engine::I18n.locale = saved_language if saved_language
+game.start
+```
+
+A language the player chose and the game saved belongs between `new` and
+`start`, as above: `new` has already chosen from the OS by then. Loading the same
+file again through `assets.locale(path)` returns the cached result and parses
+nothing.
 
 ## Reaching the game from a node
 
-A node deep in the tree gets at the asset manager through the root's context,
-so nothing has to be threaded through constructors:
+A node anywhere in the tree reaches the asset manager through the root's
+context. No constructor has to pass it along:
 
 ```ruby
-sheet = node.root.context.assets.sheet('player.json')
+sheet = node.context.assets.sheet('player.json')   # node.context is node.root.context
 ```
 
+A component reaches the same object as `context`.
+
 ## Input
 
-`input_map:` names the actions a game has, in terms of physical ids from
+`input_map:` names a game's actions in terms of physical ids from
 [`RGame::Util::Controls`](input.md):
 
 ```ruby
+require 'rgame/game'
+
 Controls = RGame::Util::Controls
 
+class Root < RGame::Engine::Node2D; end
+
 RGame::Game.new(
   root: Root.new,
   input_map: RGame::Engine::InputMap.new(
@@ -75,42 +171,45 @@ RGame::Game.new(
               stick: Controls::AXIS_LEFT_X },
     fire:   { buttons: [Controls::KEY_SPACE, Controls::PAD_A] } # held / pressed / released
   )
-)
+).start
 ```
 
-Pass nothing and you get [`InputMap.default`](input.md): eight-way `move_x` /
-`move_y` on the arrows or the left stick, plus `fire`. Either way the map is
-merged over the universal UI set, so `ui_confirm` and `ui_cancel` work without
-being declared.
+Without it, `Game` uses [`InputMap.default`](input.md). The default binds
+eight-way `move_x` / `move_y` to the arrows, WASD, the d-pad and the left stick,
+and adds `fire`. Every map merges over the universal UI set, so `ui_confirm` and
+`ui_cancel` work without a declaration.
 
-`device:` picks what drives player one — the keyboard by default, or
-`Controls.gamepad(slot)` for a controller.
+`device:` picks the device that drives player one. It defaults to the keyboard;
+pass `Controls.gamepad(slot)` for a controller.
 
-`players:` is how many seats the game has (default 1). Extra seats start empty
-and fill when somebody picks up a controller and presses confirm; an empty seat
-draws no viewport, so a two-seat game played by one person is an ordinary
-full-screen game. See [Players, seats and joining](input.md#players-seats-and-joining).
+`players:` sets how many seats the game has (default 1). Extra seats start
+empty. A seat fills when someone picks up a controller and presses confirm. An
+empty seat draws no viewport, so one person playing a two-seat game sees an
+ordinary full-screen game. See
+[Players, seats and joining](input.md#players-seats-and-joining).
 
-A scene reads the resulting snapshot in `on_control(actions)` — `actions.axis(:move_x)`,
-`actions.pressed?(:fire)` — and never sees a key.
+A scene reads the resulting snapshot in `on_control(actions)`, with calls like
+`actions.axis(:move_x)` and `actions.pressed?(:fire)`. It never sees a key.
 
-**Input is polled once per simulation tick**, not once per rendered frame. That
-matters for edge queries: `pressed?` means "held now, not held at the previous
-poll", so whatever polls decides what a press *is*. A loop that renders faster
-than it simulates would otherwise consume the press between two ticks, and
-menus would stop responding on fast machines only.
+**`Game` polls input once per simulation tick**, not once per rendered frame.
+Edge queries depend on this. `pressed?` means "held now, not held at the previous
+poll", so the poll rate decides what a press *is*. Polling per frame would let a
+fast-rendering loop consume a press between two ticks. Menus would then ignore
+input, but only on fast machines.
 
-Polling per tick costs nothing and loses nothing, because the C layer snapshots
-the keyboard once per frame: several ticks inside one frame read identical
-state, and the edge lands on the first of them. One press, one `pressed?`.
+Polling per tick costs nothing and loses nothing. The C layer snapshots the
+keyboard once per frame, so every tick inside one frame reads identical state.
+The edge lands on the first tick. One press gives one `pressed?`.
 
 ## Subclassing it
 
-`Game` is an [`App`](app.md), so anything an App can override it can too. The
-loop, the fixed timestep and the catch-up cap are the engine's; a subclass adds
-behaviour around the tree rather than replacing the shell.
+`Game` is an [`App`](app.md), so a subclass can override any `App` hook. The
+engine owns the loop, the fixed timestep and the catch-up cap. A subclass adds
+behaviour around the tree; it does not replace the shell.
 
 ```ruby
+require 'rgame/game'
+
 class MyGame < RGame::Game
   def button_down(id)
     super                      # keeps F1 and F2 working