rgame 0.2.0 → 0.3.0

data/docs/api/internals.md

@@ -1,20 +1,25 @@
 # Internal building blocks
 
-Low-level, pure-Ruby classes the engine's [components](components.md) and
-[systems](systems.md) are built on. A game author rarely constructs these directly —
-they sit *behind* a component (a `CharacterBody` resolves through `CollisionSystem`, an
-`AnimatedSprite` plays through an `Animator`, a `CollisionWorld` indexes through a
-`SpatialHash`) — but they are documented here because they carry the load-bearing
-algorithms and are the seams the component tests drive. None `require "gosu"`.
+**The engine's [components](components.md) and [systems](systems.md) are built on
+these low-level, pure-Ruby classes.** A game author rarely constructs them. They
+sit *behind* components:
 
-For the helpers a game *does* reach for directly (pools, localization, the camera,
-collision boxes, …), see [Utilities](toolbox.md).
+- a blocked `Mover` resolves through `CollisionSystem`;
+- an `AnimatedSprite` plays through an `Animator`;
+- a `CollisionWorld` indexes through a `SpatialHash` and remembers contacts
+  through a `ContactSet`.
+
+This page documents them because they hold the core algorithms, and component
+specs drive them directly.
+
+[Toolbox](toolbox.md) covers the helpers a game *does* use directly: pools,
+the camera, collision boxes. [Localization](localization.md) covers `I18n`.
 
 ## `SpatialHash` — uniform-grid broadphase
 
-`RGame::Engine::SpatialHash` (`rgame/engine/spatial_hash`) is a broadphase index for collision:
-bucket colliders into fixed-size grid cells, then test only candidates that share a
-cell instead of every pair. It is the index inside
+**`RGame::Engine::SpatialHash` (`rgame/engine/spatial_hash`) is a broadphase index
+for collision.** It buckets colliders into fixed-size grid cells, then tests only
+candidates that share a cell, not every pair. It is the index inside
 [`CollisionWorld`](components.md#collisionworld).
 
 ```ruby
@@ -24,87 +29,261 @@ rocks.each { |r| hash.insert(r, *r.aabb) }  # insert the static set
 hash.query(*bullet.aabb) { |rock| ...narrowphase... }
 ```
 
-Typical per-frame use is `clear`, `insert` every collider of one set, then `query`
-around each moving collider. Both `insert` and `query` take an AABB (`x, y, w, h`);
-an item spanning several cells is inserted into each and so **may be yielded more than
-once** by `query`. That dedup is deliberately the narrowphase caller's job — guard with
-`next if a.dead? || b.dead?` to keep hits idempotent — which lets the hash skip a
-per-query visited set and stay allocation-free. Cell keys are packed into a single
-tagged Fixnum (with an offset so off-screen / mid-wrap negative cells stay
-non-negative), so keying allocates nothing either.
-
-`query_circle(cx, cy, r, &)` is the radial counterpart to `query`: it yields the items
-in the cells the circle's bounding box covers (delegating to the same cell walk), for
-range and nearest lookups. It is still broadphase — it carries the same may-yield-twice
-contract, and the caller refines candidates by true distance (see
-[`CollisionWorld`](components.md#collisionworld)'s `query_circle`/`nearest`).
-
-## `TileCollision` — axis-separated AABB-vs-tile resolution
-
-`RGame::Engine::TileCollision` (`rgame/engine/tile_collision`) resolves an axis-aligned box against a
-grid of solid tiles. `solid` is a callable `solid.call(col, row) -> bool`, so the tile
-source is decoupled (a `TileMap`, a fake in tests). It moves the box **one axis at a
-time** — `resolve_x` then `resolve_y` (fed the resolved x) — which gives wall-sliding: a
-diagonal push into a wall keeps the component that's still free.
+A typical frame calls `clear`, inserts every collider of one set, then runs
+`query` around each moving collider. `insert` and `query` both take an AABB
+(`x, y, w, h`).
+
+`remove(item, x, y, w, h)` undoes one `insert`. Pass the box the item was
+inserted at, not where it is now: the hash does not remember where it put
+anything. Removing an item that is not there does nothing.
+
+**`query` may yield an item more than once.** An item spanning several cells sits
+in each of them. Removing repeats is the narrowphase caller's job, which spares the
+hash a per-query visited set and keeps it allocation-free. `CollisionWorld` checks
+each pair against the [`ContactSet`](#contactset--the-two-edges-of-a-contact) it
+fills for the step, which it needs anyway. A caller that only *selects*, like
+`nearest`, ignores repeats instead. The hash packs each cell key into one tagged
+Fixnum, offset so negative cells stay non-negative. Keying therefore allocates
+nothing either.
+
+`query_circle(cx, cy, r, &)` is the radial form of `query`. It yields the items in
+the cells the circle's bounding box covers, through the same cell walk. Use it for
+range and nearest lookups. It remains a broadphase with the same may-yield-twice
+contract. The caller refines candidates by true distance (see
+[`CollisionWorld`](components.md#collisionworld)'s `query_circle` and `nearest`).
+
+`cell_empty?(x, y)` asks whether the single cell *containing the point* `(x, y)`
+is empty. It takes a point, not a region, so pass any coordinate inside the cell
+you mean. It allocates nothing. Unlike a plain read of the bucket Hash, a miss
+creates no bucket.
+
+**The cell walk is half-open on the far edge.** The hash buckets an item by its
+bounding box. A box ending exactly on a cell boundary stops at the cell before it.
+A piece filling one cell therefore lands in that cell only. "Bucketed here" means
+exactly "overlaps this cell's area", so `cell_empty?` tests occupancy, not
+candidacy. `CollisionBox.overlap?` uses the same convention, and the two must
+agree. Bucketing one cell too far would only cost extra candidates. Bucketing one
+cell short would miss a real contact.
+
+The index cannot know whether an occupant still counts.
+[`CollisionWorld#cell_empty?`](components.md#collisionworld) therefore wraps this
+method and skips colliders whose node is queued for removal.
+
+## `ContactSet` — the two edges of a contact
+
+**`RGame::Engine::ContactSet` (`rgame/engine/contact_set`) turns a per-step overlap
+test into two edges**: the step a pair *starts* touching and the step it *stops*.
+[`CollisionWorld`](components.md#collisionworld) owns one per registered collider
+and is its only driver there. Nothing in the class concerns overlap, though, and
+it has a second user. Every [`Mover`](components.md#mover) keeps one of what
+stopped its step, and derives `on_blocked` / `on_unblocked` from it the same way.
+Underneath its names, the class is "the set of things true this step and last".
 
 ```ruby
-tiles = RGame::Engine::TileCollision.new(tile_width: 16, tile_height: 16,
-                                  solid: ->(col, row) { map.solid_tile?(col, row) })
-nx = tiles.resolve_x(x, y, w, h, dx) # snaps flush against a solid in the dx direction
-ny = tiles.resolve_y(nx, y, w, h, dy)
+contacts.begin_frame              # last step's list becomes the one to compare against
+contacts.touching?(other)         # already recorded this step? (the broadphase repeats)
+contacts.started?(other)          # not touching last step, so this is an on_hit
+contacts.add(other)               # record it for this step
+contacts.each_ended { |o| ... }   # touching last step, not now, so this is an on_separated
+contacts.reset                    # forget both steps — a pooled collider registering again
 ```
 
-It assumes per-step movement smaller than a tile (no tunneling), which holds for the
-engine's speeds. It is the maths inside [`CollisionSystem`](#collisionsystem--move-an-actor-against-the-tiles-and-the-world).
+**It uses two arrays, swapped each step, and checks membership by a linear scan
+on identity.** Both choices serve the per-frame path. `Array#clear` keeps the
+capacity the array grew to, so a lasting contact allocates nothing after the first
+few steps. A Set or a Hash would allocate on every insert. A collider touching more
+than a handful of things at once points to a design problem elsewhere; it is no
+reason to index this.
+
+`started?` reads only the previous step's list. It answers the same before and
+after `add`, so the world can use it as a guard in step order.
 
-## `CollisionSystem` — move an actor against the tiles and the world
+## `TileBlockers` — the tile grid as a blocker source
 
-`RGame::Engine::CollisionSystem` (`rgame/engine/collision_system`) wraps `TileCollision` with a
-world-bounds clamp and an actor-facing `move`. It is what
-[`TileWorld`](components.md#tileworld) delegates to (and what a `CharacterBody` moves
-through).
+**`RGame::Engine::TileBlockers` (`rgame/engine/tile_blockers`) resolves an
+axis-aligned box against the solid tiles of a
+[`Util::SolidGrid`](values.md#rgameutilsolidgrid)**, at a given tile size.
+[`TileWorld`](components.md#tileworld) builds one over the grid it reads the map
+into; a spec builds the grid itself. `TileBlockers` reads the grid and never copies
+it, so a cell changed with `set_solid` stops the next step. It resolves each
+axis on its own. [`CollisionSystem`](#collisionsystem--move-an-actor-against-its-blockers)
+feeds one axis's result into the other.
 
 ```ruby
-collision = RGame::Engine::CollisionSystem.new(
-  tile_collision: tiles, world_width: map.pixel_width, world_height: map.pixel_height
-)
+require 'rgame'
+
+grid = RGame::Util::SolidGrid.build(20, 15) { |col, _row| col == 5 }   # a wall at x 80..96
+tiles = RGame::Engine::TileBlockers.new(grid: grid, tile_width: 16, tile_height: 16)
+
+x, y, w, h = 58.0, 32.0, 12, 6
+nx = tiles.resolve_x(x, y, w, h, 14.0)   # => 68.0 — snapped flush against the wall's left edge
+ny = tiles.resolve_y(nx, y, w, h, 4.0)   # => 36.0
+tiles.travel?(10.0, 32.0, w, h, 50.0, 0.0)   # => true
+tiles.travel?(10.0, 32.0, w, h, 90.0, 0.0)   # => false — the wall is in the way
+```
+
+[`Util::TileSweep`](values.md#rgameutiltilesweep) does the arithmetic, in C;
+`TileBlockers` presents it as a blocker source. Results are Floats. It assumes each
+step moves less than a tile, so nothing tunnels. The engine's speeds meet that.
+
+**`travel?(x, y, w, h, dx, dy)` answers whether the box can move `(dx, dy)`
+without any resolve stopping it short.** It is the optional extra question of the
+[blocker-source protocol](#collisionsystem--move-an-actor-against-its-blockers).
+It sweeps the box in overlapping windows half a tile long and a quarter tile
+apart. It resolves each window x-then-y and y-then-x. A `true` holds for a walker
+that resolves its own steps against this source, as long as each step is under a
+quarter tile: 240 px/s at 60 ticks a second on 16 px tiles. It may refuse a segment
+such a walker could manage. It never clears one the walker could not.
+[`Navigator`](components.md#navigator) smooths its routes with it.
+
+`blocker` returns the sentinel `TileBlockers::TILES`: one object for the life of
+the process, answering `layer` → `:tiles` and `node` → `nil`. `TileBlockers` holds
+no per-step state, so every body on the map can share one.
+[`TileWorld#blockers`](components.md#tileworld) hands out that shared instance.
+
+## `ActorBlockers` — the registered colliders as a blocker source
+
+**`RGame::Engine::ActorBlockers` (`rgame/engine/actor_blockers`) does the same
+arithmetic, with the edge coming from another collider instead of a grid line.**
+It asks a broadphase what lies near the swept box, and snaps flush against the
+nearest candidate.
+
+```ruby
+actors = RGame::Engine::ActorBlockers.new(world: collision_world, owner: my_collider,
+                                          layers: %i[npc hero])
+```
+
+**Unlike the other two sources, it belongs to one mover.** It holds that mover's
+own collider, to exclude it by identity, and the layer list the mover declared.
+Two movers with different `blocked_by` cannot share one. That is why a
+[`Mover`](components.md#mover) builds its own `CollisionSystem` instead of
+borrowing the scene's.
+
+It does three things a grid does not need:
+
+- **The nearest candidate wins**, tracked as a running minimum. The broadphase can
+  therefore offer one collider once per shared cell without harm.
+- **It leaves an existing overlap unresolved.** A step is blocked only if it
+  *crosses* an edge the mover started on the near side of. A pair that starts
+  overlapping stays overlapping and is not teleported apart.
+- **It handles boxes only.** It skips a `CircleCollider` on a declared layer.
+
+Its `moved` passes the mover to
+[`CollisionWorld#reindex`](components.md#collisionworld). That keeps a later query
+in the same step exact.
+
+## `BoundsBlockers` — the edge of the world as a blocker source
+
+**`RGame::Engine::BoundsBlockers` (`rgame/engine/bounds_blockers`) stops a box from
+leaving the region a [`WorldBounds`](components.md#world) describes.** It reads
+the two numbers once at construction, because those bounds are immutable by
+contract. Its `blocker` is the sentinel `BoundsBlockers::BOUNDS`, answering
+`layer` → `:bounds`.
+
+**A mover declares the edge as a source; the engine applies no automatic clamp.**
+Stopping at the edge is one of three responses to it. `ScreenWrap` and
+`DespawnOffscreen` are the others, and a node may carry only one
+([`WorldBounds.one_response!`](components.md#world)). A mover that did not ask is
+not held.
+
+## `CollisionSystem` — move an actor against its blockers
+
+**`RGame::Engine::CollisionSystem` (`rgame/engine/collision_system`) holds a list of
+blocker sources and moves an actor against them.** A blocked
+[`Mover`](components.md#mover) builds one at attach, from the sources its
+`blocked_by:` names, and passes itself as the actor.
+
+```ruby
+collision = RGame::Engine::CollisionSystem.new(blockers: [tiles, actors])
 collision.move(actor, dx, dy) # actor responds to x / y / x= / y= / collision_box
 ```
 
-`move` reads the actor's [`CollisionBox`](toolbox.md#collisionbox--an-actors-feet-box)
-AABB, resolves it through `TileCollision` on both axes, clamps the box inside the world
-as a backstop, and writes the resolved position back to the actor (accounting for the
-box's offset from the sprite origin).
+`move` reads the actor's
+[`CollisionBox`](toolbox.md#collisionbox--an-actors-feet-box) AABB and resolves it
+on both axes. It writes the resolved position back to the actor, accounting for the
+box's offset from the sprite origin. Finally it tells every source that the step
+happened. **It has no clamp of its own.** Everything that can stop a step is a
+source, the world's edge included.
+
+A blocker source answers four questions. Only the first two involve arithmetic:
+
+```ruby
+source.resolve_x(x, y, w, h, dx)          # -> where the box's left edge lands moving dx
+source.resolve_y(x, y, w, h, dy)          # -> where the box's top  edge lands moving dy
+source.blocker                            # -> what produced that edge, or nil
+source.moved(actor, from_x, from_y, w, h) # -> the step has been written back
+```
+
+A fifth is optional. Of the three sources, only `TileBlockers` answers it:
+
+```ruby
+source.travel?(x, y, w, h, dx, dy)        # -> can the box move (dx, dy) without being stopped?
+```
+
+**"Stopped" means a resolve lands short of where the step was heading.** A landing
+past it does not count: `move` ignores it, and it does not stop a travel either.
+`BoundsBlockers` gives such a landing to a box that starts outside the world. Under
+this reading, a box travels past several sources exactly when it travels past each
+one alone. The shared example group `a blocker source answering travel?`
+(`spec/support/shared_examples/`) states that meaning. It checks a source's answer
+against a walker stepping through the source's own resolves.
+
+The three sources are `TileBlockers`, `ActorBlockers` and `BoundsBlockers`. **The
+system asks each source and takes the most restrictive answer on each axis**: the
+smallest landing for a rightward or downward step, the largest for a leftward or
+upward one. No source needs to know the others exist, and `blockers: []` means free
+movement.
+
+`blocked_x` and `blocked_y` hold what the winning source reported for each axis, or
+nil when that axis was free. The system asks each winner during the resolve, not
+afterwards, because a source's `blocker` is per axis and the next resolve overwrites
+it. Every blocker answers `layer` and `node`, tiles and world edges included. A
+caller reads `blocked_x.layer` without checking what kind of thing stopped it.
+
+The system calls `moved` on every source with the box the step **started** from. A
+source over a moving index can then re-bucket the mover, without anyone storing a
+box for it; see `ActorBlockers` above.
+
+Keeping the list in the system, not inside a source, has two consequences. First,
+the axis-separated order exists once for every source: resolve x, then resolve y
+with the resolved x. That order produces wall-sliding, where a diagonal push into a
+wall keeps the component that is still free. Second, the loop walks an index
+instead of using `map` or `min`. It runs per actor, per axis, per frame, and both a
+block and an intermediate array would allocate.
 
 ## `AnimationSet` — pure frame maths
 
-`RGame::Engine::AnimationSet` (`rgame/engine/animation_set`) turns an atlas's animation table plus an
-elapsed time into the sprite-sheet cell to show — no renderer, no images, fully testable.
+**`RGame::Engine::AnimationSet` (`rgame/engine/animation_set`) turns an animation
+table and an elapsed time into the sprite-sheet cell to show.** It needs no
+renderer and no images, so specs test it fully.
 
 ```ruby
+require 'rgame'
+
 set = RGame::Engine::AnimationSet.new(
   stand:      { row: 0, col: 1, frames: 1, fps: 1 },
   walk_right: { row: 1, frames: 3, fps: 6 }
 )
-set.frame(:walk_right, elapsed) # => [row, col, flip_x]
+set.frame(:walk_right, 0.4) # => [1, 2, false] — [row, col, flip_x]
 ```
 
 Each animation is `{ row:, col: (start column, default 0), frames:, fps:, flip_x: }`.
-`frame(name, elapsed)` advances `frames` columns from `col` at `fps`, wrapping — so a
-held animation cycles.
+`frame(name, elapsed)` advances through `frames` columns from `col` at `fps`, and
+wraps around. A held animation therefore cycles.
 
 ## `Animator` — animation playback state
 
-`RGame::Engine::Animator` (`rgame/engine/animator`) owns the playback state on top of an
-`AnimationSet`: the current animation name and elapsed time. It is what
-[`AnimatedSprite`](components.md#animatedsprite) drives.
+**`RGame::Engine::Animator` (`rgame/engine/animator`) owns playback state on top of
+an `AnimationSet`**: the current animation name and its elapsed time.
+[`AnimatedSprite`](components.md#animatedsprite) drives it.
 
 ```ruby
 animator = RGame::Engine::Animator.new(set, initial: :stand)
 animator.play(:walk_right) # switch (a no-op if already playing, so a walk keeps cycling)
 animator.update(dt)        # advance elapsed time
-animator.frame             # => [row, col, flip_x] for the current animation now
+animator.frame             # => [row, col, flip_x] — for the current animation now
 ```
 
-`play` only restarts elapsed time on an actual change, so calling it every frame with the
-current intent keeps a continuing walk smooth rather than stuttering on frame 0.
+`play` resets elapsed time only when the animation changes. Calling it
+every frame with the current intent keeps a walk smooth instead of stuttering on
+frame 0.

data/docs/api/localization.md

@@ -0,0 +1,285 @@
+# Localization
+
+**Text a game draws is a translation key, and the words live in YAML tables.**
+`RGame::Game` loads the tables and picks the player's language at startup. A
+node draws an [`Engine::Text`](toolbox.md#text--the-string-a-node-draws) built
+from a key. A UI button's `label:` [is a key too](ui.md#labels-are-translation-keys).
+`RGame::Engine::I18n` (`rgame/engine/i18n`) holds the tables and the current
+language, and every `Text` reads through it.
+
+`examples/localization` shows all of it on one screen: plurals, a variable, a
+fallback, a language menu and a saved choice. See [Examples](examples.md#localization).
+
+## Where the tables go
+
+**A game on `RGame::Game` keeps its tables under `locales/` in its media root**,
+one or more `.yml` files in Rails' format. The top-level key is the locale, and
+keys nest below it:
+
+```yaml
+# media/locales/en.yml
+en:
+  title_menu:
+    play: Play
+  hud:
+    score: "Score: %{score}"
+    apples:
+      zero: No apples
+      one: "%{count} apple"
+      other: "%{count} apples"
+```
+
+```yaml
+# media/locales/de.yml
+de:
+  title_menu:
+    play: Spielen
+  hud:
+    score: "Punkte: %{score}"
+    apples:
+      one: "%{count} Apfel"
+      other: "%{count} Äpfel"
+```
+
+`Game.new` lists every `.yml` under `locales:` and loads each through the asset
+manager, sorted by path. `locales:` defaults to `'locales'`. It is relative to
+`media_root` unless it is absolute. A directory that does not exist loads
+nothing, and every key then shows as itself. See
+[Game](game.md#translations-and-the-players-language) for the loading order.
+
+A project from `rgame new` keeps its tables in `assets/locales/`, which is its
+media root plus the default. See
+[The `rgame` command](cli.md#text-comes-from-a-translation-table).
+
+One file may hold several locales, and several files may hold one. A second load
+of a locale merges key by key into what is loaded. A key set twice takes the
+later value.
+
+## Drawing translated text
+
+A node builds a `Text` once and reads it in `on_draw`. A read with unchanged
+variables and an unchanged language returns the same String and allocates
+nothing:
+
+```ruby
+class Hud < RGame::Engine::Node2D
+  def initialize(**)
+    super
+    @score = RGame::Engine::Text.new('hud.score', :score)
+    @apples = RGame::Engine::Text.new('hud.apples', :count)
+    @title = RGame::Engine::Text.new('hud.title')
+  end
+
+  def on_draw(renderer, _view)
+    renderer.text(@score.with(score: @points), 12, 10)
+    renderer.text(@apples.with(count: @apples_held), 12, 30)
+    renderer.text(@title, 12, 50)
+  end
+end
+```
+
+A `Text` with no variables goes to `text` as it is, because it answers `to_str`.
+
+A switch of `I18n.locale` renders every `Text` again on its next read. Nothing
+subscribes to the switch. [`Text`](toolbox.md#text--the-string-a-node-draws)
+covers variables, scopes, `Text.literal` for text that never translates, and
+`Text.computed`.
+
+`I18n` itself is a global module, so this works headless, in a spec or anywhere
+else:
+
+```ruby
+require 'rgame'
+
+i18n = RGame::Engine::I18n
+i18n.load(<<~YAML, source: 'locales/game.yml')
+  en:
+    menu:
+      title: Main Menu
+      greeting: "Hello, %{name}"
+    apples:
+      zero: No apples
+      one: "%{count} apple"
+      other: "%{count} apples"
+  de:
+    menu:
+      title: Hauptmenü
+    apples:
+      one: "%{count} Apfel"
+      other: "%{count} Äpfel"
+YAML
+
+i18n.locale = 'de_AT'
+i18n.chain                                   # => [:"de-AT", :de, :en]
+i18n.t('menu.title')                         # => "Hauptmenü" — from the de table
+i18n.t('greeting', scope: 'menu', name: 'Ada') # => "Hello, Ada" — de lacks it, en has it
+i18n.t('apples', count: 3)                   # => "3 Äpfel"
+i18n.missing_keys(:de)                       # => ["menu.greeting"]
+i18n.choose(%w[fr-CA de-CH])                 # => :"de-CH" — the de table covers it
+```
+
+## Tables
+
+`load(yaml, source:)` parses a String. `source:` names the file in error
+messages. `load_hash` does the same for a Hash, with Symbol or String keys.
+`I18n` never opens a file: `RGame::Game` reads the files and hands `load` their
+text.
+
+`load` uses `YAML.safe_load` with aliases allowed. It raises
+`Psych::DisallowedClass` for an object tag and `Psych::SyntaxError` for broken
+YAML. YAML reads an unquoted `on`, `off`, `yes`, `no`, `true`, `false` or `~` as
+a boolean or `nil`. `load` raises `ArgumentError` for such a key or value, naming
+where it is, so quote it. A number value becomes its text, and so does a
+whole-number key. Any other key, such as `1.5`, raises `ArgumentError` too.
+
+Each load compiles every value once. A String becomes a template with its
+placeholders already found. `%%{` writes a literal `%{`. A key without
+placeholders returns the same frozen String on every call.
+
+`available` lists the locales that have a table, in load order.
+
+## Variables and `t`
+
+`%{name}` in a translation prints a variable. A `Text` declares its variables as
+names and receives them as keywords to `with`.
+
+`t(key, scope: nil, **vars)` looks `key` up, or `"scope.key"` when `scope:` is
+given, and interpolates `vars`. It raises `ArgumentError` when the translation
+uses a variable `vars` does not hold. Variables it does not use are ignored.
+`t` allocates on every call, so keep it off the per-frame path.
+
+`render(key, names, vars)` is what a `Text` reads through. It resolves `key` like
+`t`, with `vars` holding exactly `names`. A translation whose placeholders are
+not `names` goes to the [missing policy](#missing-keys), as
+[`Text`](toolbox.md#when-it-renders-again) describes.
+
+## Plurals
+
+A key whose nested keys are all CLDR plural categories (`zero`, `one`, `two`,
+`few`, `many`, `other`), with text values and `other` among them, is a plural.
+Any other nested Hash is a level of keys. `t` needs `count:` for a plural and
+raises `ArgumentError` without it. `count` is also available as `%{count}`. A
+`Text` for a plural needs `:count` among its names.
+
+`t` picks the form by these rules, in order:
+
+1. An explicit `zero` form wins for a count of 0, in every language. A table
+   without one uses its language's rule: German reads `0 Äpfel` from `other`.
+2. The plural rule sorts the count into a category. The rule belongs to the
+   table that supplied the key, not to the current locale. English text reached
+   through a fallback from `:pl` counts like English.
+3. A category the table leaves out reads `other`.
+
+`I18n::PluralRules::BUILT_IN` holds whole-number rules for en, de, nl, sv, da,
+nb, fi, it, es, pt, fr, ru, uk, pl, cs, ja, zh, ko and ar. A built-in rule puts a
+count that is not an Integer in `other`. A language without a rule counts like
+English. `plural_rule(language) { |count| ... }` adds or replaces a rule; its
+block returns a category Symbol. A rule for a regional locale, such as `'pt-PT'`,
+wins over its language's rule for tables of that locale.
+
+## Locales and the fallback chain
+
+`locale=` switches the language, and `default=` sets the last locale every lookup
+falls back to. Both start at `:en`. Both normalize what they are given:
+`de_AT`, `'de-at'` and `:'de-AT'` all become `:'de-AT'`, and `normalize` is
+public. A locale needs no table of its own.
+
+`chain` lists where a lookup looks, in order: the locale, each shorter prefix of
+it, then the default. `I18n` rebuilds it on a switch, not on every lookup. A key
+the German table lacks therefore shows the English text in German, when English
+is the default.
+
+`choose(preferred)` takes the player's locales, most wanted first. It returns the
+first whose own chain meets a table, normalized but not shortened. The default
+does not count as a match, and with no match `choose` returns the default.
+
+## The player's language
+
+**`Game.new` sets `I18n.locale` to `I18n.choose(RGame::Core.preferred_locales)`**
+after loading the tables: the first locale the operating system prefers that a
+table covers, or the default. [App](app.md) describes what
+`RGame::Core.preferred_locales` returns on each platform.
+
+A language the player picked belongs between `new` and `start`, because `new`
+has already chosen from the OS by then. `examples/localization` saves it with
+[`Util::SaveFile`](values.md) and restores it this way:
+
+```ruby
+game = MyGame.new
+saved = save.read[:language]
+if saved.is_a?(String) && !saved.empty?
+  RGame::Engine::I18n.locale = RGame::Engine::I18n.choose([saved, *RGame::Core.preferred_locales])
+end
+game.start
+```
+
+Passing the saved locale through `choose` ignores a saved language the game has
+no table for. A menu that switches language sets `I18n.locale` and writes the
+save. `I18n` holds one language for the whole process, so split-screen players
+share it.
+
+## Missing keys
+
+A key is missing when no locale in the chain has it. `missing=` decides what
+`t` returns then:
+
+| `missing` | `t` on a missing key |
+|---|---|
+| `:key` (the start) | returns the key, with its scope |
+| `:raise` | raises `I18n::MissingKey`, whose `key` and `chain` say where it looked |
+| a callable | calls it with the key and the chain, and returns its result |
+
+Any other value raises `ArgumentError`. A game on `RGame::Game` keeps `:key`, so
+a missing key shows as itself on screen.
+
+`missing_keys(locale)` lists the keys the default's table has and the locale's
+own chain lacks, in the default table's order. It skips a key the locale gets
+from a parent, such as `de-AT` from `de`.
+
+## Specs
+
+**Specs raise on a missing key and check every table against the default.** A
+project from `rgame new` does both. Its `spec/spec_helper.rb` loads the tables
+before every example:
+
+```ruby
+LOCALES = Dir[File.expand_path('../assets/locales/**/*.yml', __dir__)]
+          .to_h { |path| [path, File.read(path)] }.freeze
+
+RSpec.configure do |config|
+  config.before do
+    RGame::Engine::I18n.reset
+    LOCALES.each { |path, yaml| RGame::Engine::I18n.load(yaml, source: path) }
+    RGame::Engine::I18n.missing = :raise
+  end
+end
+```
+
+Its `spec/locales_spec.rb` expects `missing_keys` to be empty for every locale in
+`available`. A key added to `en.yml` and not to `de.yml` then fails `rake`.
+[The `rgame` command](cli.md#text-comes-from-a-translation-table) describes both
+files.
+
+## `generation`
+
+**`generation` is an Integer that moves whenever what a key resolves to may have
+changed.** It moves on every load, on a switch to a different locale or default,
+on every `plural_rule`, and on `reset`. A switch to the locale already current leaves it alone. Cached
+text compares `generation` with the value it last saw, and resolves again only
+when it differs.
+
+`reset` forgets every table and added plural rule. It restores `:en` as locale
+and default, and `:key` as the missing policy. rgame's own headless suite calls
+`reset` and sets `missing = :raise` before every example.
+
+## What this is not
+
+- **Text is not measured in the engine layer.** A button slot has a fixed width,
+  so choose one wide enough for the longest translation.
+- **One language per process.** Split-screen players cannot read different
+  languages.
+- **No right-to-left text or shaping.** The shipped font covers Latin, Greek and
+  Cyrillic; nothing selects a font per locale.
+- **Only text translates.** Images, audio and other assets have no per-locale
+  variant.
+- **No `default:`, lazy lookup, array values or symbol links** from Rails.