rgame 0.2.0 → 0.3.0

data/docs/api/README.md

@@ -1,46 +1,51 @@
 # rgame API guide
 
-Reference documentation for using rgame from Ruby. The engine is written in C
-and exposed as two Ruby extensions, with the scene graph a game is actually
-written in sitting on top of them in pure Ruby; nothing here assumes you will
-read or write any C.
+These pages document how to use rgame from Ruby. The engine is written in C and
+ships as two Ruby extensions. The scene graph sits on top of them in pure Ruby,
+and a game is written against that scene graph. Nothing here asks you to read
+or write C.
 
 | Page | Covers |
 |---|---|
 | This page | Loading the library, the three namespaces, a working program, testing |
+| [The `rgame` command](cli.md) | `rgame new NAME` — starting a project, and the layout it gives you |
 | [App](app.md) | `RGame::Core::App` — the window and the frame loop |
 | [Game](game.md) | `RGame::Game` — the entry point that wires both halves together |
 | [Input](input.md) | `RGame::Core::Input`, `RGame::Util::Controls`, `RGame::Core::Gamepad` |
 | [Drawing](drawing.md) | `RGame::Core::Renderer` — shapes, images, transforms, clipping, recordings |
-| [Images](images.md) | `RGame::Core::Image` — loading PNGs, subimages, sprite sheets |
+| [Images](images.md) | `RGame::Core::Image` — loading PNGs, subimages, tiles |
 | [Text](text.md) | `RGame::Core::Font` and `Renderer#text` |
 | [Audio](audio.md) | `RGame::Core::Audio`, `Sample`, `Song` — samples and streamed music |
-| [Sheets, atlases and maps](assets.md) | `RGame::Core::SpriteSheet` and the rest of the asset layer |
-| [Values](values.md) | `RGame::Util::Color`, `RGame::Util::Tensor`, `RGame::Util::Z` |
+| [Assets](assets.md) | `RGame::Core::AssetManager`, `SpriteSheet`, `NineSlice`, `UiAtlas`, `TileMapRenderer` |
+| [Values](values.md) | `RGame::Util::Color`, `Tensor`, `SolidGrid`, `RouteSearch`, `TileSweep`, `Z`, `SaveFile` |
+| [Examples](examples.md) | What each program under `examples/` demonstrates |
 
-The scene graph — `RGame::Engine`, the layer a game is actually written in:
+The scene graph is `RGame::Engine`, the layer a game is written in:
 
 | Page | Covers |
 |---|---|
 | [Scene graph](scene_graph.md) | `Node2D`, the tree, the lifecycle, transforms and the camera |
 | [Components](components.md) | Reusable behaviour attached to a node |
 | [Systems](systems.md) | Services a subtree shares — collision worlds, tile worlds |
-| [UI](ui.md) | `PlayerLayer` and `UI::Menu` — a player's own screen, navigated by focus |
+| [Tile maps](tile_maps.md) | `TileMap` and `Tileset` — a Tiled map as data: loading, cells, solidity, animated tiles |
+| [UI](ui.md) | `PlayerLayer` and `UI::Menu` — a player's own screen, and a list or wheel navigated by focus |
 | [Signals](signals.md) | The typed observer pattern nodes talk through |
-| [Toolbox](toolbox.md) | What a game author reaches for directly: pooling, timers, camera, i18n, the audio bus |
+| [Toolbox](toolbox.md) | What a game author reaches for directly: the text a node draws, pooling, paths and routes, timers, the camera, collision boxes, the audio bus |
+| [Localization](localization.md) | `I18n` and translation tables — where they go, plurals, the fallback chain, the player's language, missing keys in specs |
 | [Internal building blocks](internals.md) | What components are built from: collision maths, the spatial index, animation playback |
 
-**The engine is a work in progress.** A window opens, the loop runs, input
-works, shapes, images and text can be drawn, sound plays, and a scene graph with
-split-screen players runs on top of it — the games under `examples/` are built
-on exactly what is documented here. What is missing is a UI *toolkit*: [UI](ui.md)
-gives each player a region of the screen, focus and activation, and stops there —
-no layout, no scrolling lists, no text entry. Pages here describe what exists
-today and grow as more lands.
+**The engine is a work in progress.** It opens a window, runs the loop, reads
+input, draws shapes, images and text, and plays sound. A scene graph with
+split-screen players runs on top. The games under `test_projects/` use exactly
+what these pages document. The missing piece is a UI *toolkit*. [UI](ui.md)
+gives each player a region of the screen, menus with focus and activation, and a
+column, row or ring of equal-sized buttons. It has no general layout, no scrolling
+lists and no text entry. These pages describe
+what exists and grow with the engine.
 
 ## Loading it
 
-Three requires, each a strict superset of the last:
+rgame has three entry points. Each one loads everything the one before it does:
 
 ```ruby
 require 'rgame'       # RGame::Util + RGame::Engine — no graphics libraries at all
@@ -48,23 +53,22 @@ require 'rgame/core'  # adds the window, the GPU and the sound device (SDL2 + Op
 require 'rgame/game'  # all of it, wired together — what a game writes
 ```
 
-A game wants the last one. `RGame::Game` is the entry point; see
+A game requires the last one. Its entry point is `RGame::Game`; see
 [Game](game.md).
 
-The first is **everything that runs without a window**: the value types and the
-whole scene graph, in a process with no SDL and no OpenGL loaded. That is what
-lets game logic and its specs run with no display present, and it is asserted
-rather than assumed — `spec/rgame/no_graphics_spec.rb` reads the process's own
-memory map.
+`require 'rgame'` loads **everything that runs without a window**: the value
+types and the whole scene graph. The process loads no SDL and no OpenGL, so game
+logic and its specs run with no display. `spec/rgame/no_graphics_spec.rb` checks
+this by reading the process's own memory map.
 
-Nothing is forced through those files: `rgame/util`, `rgame/engine` and
-`rgame/core` are separately requirable, which is how the Core spec suite loads
-exactly one layer.
+You can also require `rgame/util`, `rgame/engine` and `rgame/core` on their own.
+The Core spec suite does this to load exactly one layer.
 
-For convenience, `rgame/core` also defines `RGame::Util::Controls` (the input
-id vocabulary), because the input classes need it.
+`rgame/core` also loads `RGame::Util::Controls`, the input id vocabulary,
+because the input classes need it.
 
-Both extensions must be compiled before they can be required:
+`gem install rgame` compiles both extensions. In a checkout of the repository,
+compile them before you require anything:
 
 ```
 make ext        # builds both, copies them into lib/rgame/
@@ -72,45 +76,45 @@ make ext        # builds both, copies them into lib/rgame/
 
 ## The three namespaces
 
-Everything lives under `RGame`, split three ways — two of them by what they
-depend on, the third by what it is *for*:
+Everything lives under `RGame`. What a class depends on decides between `Util`
+and `Core`. `Engine` holds what a game is written in.
 
 | | `RGame::Util` | `RGame::Core` | `RGame::Engine` |
 |---|---|---|---|
 | Contains | shareable *values* — no window, no GPU, nothing to release | things owning a window, GPU or OS handle | game concepts: the scene graph a game is written in |
-| Today | `Color`, `Tensor`, `Controls`, `Z` | `App`, `Input`, `Gamepad`, `Image`, `Renderer`, `Recording`, `Font`, `Audio`, `SpriteSheet`, `AssetManager` | `Node2D`, components, systems, signals, `TileMap`, `Player`, `InputMap`, `UI::Menu` |
+| Classes | `Color`, `Tensor`, `Controls`, `Z`, `SolidGrid`, `RouteSearch`, `TileSweep`, `SaveFile` | `App`, `Input`, `Gamepad`, `Image`, `Renderer`, `Recording`, `Font`, `Audio`, `SpriteSheet`, `NineSlice`, `UiAtlas`, `TileMapRenderer`, `AssetManager` | `Node2D`, components, systems, signals, `TileMap`, `Player`, `InputMap`, `UI::Menu` |
 | Loading it costs | nothing | SDL2 + OpenGL in your process | nothing |
 
-The rule for splitting the bottom two: **a value goes in `Util`; only a
-handle-owner goes in `Core`.** A colour is a value. A window is not.
+**A value goes in `Util`; only a handle-owner goes in `Core`.** A colour is a
+value. A window is not.
 
-`RGame::Engine` sits above both, and its rule is what makes the split worth
-having:
+`RGame::Engine` sits above both and follows three rules:
 
-- it may hold `Util` values freely as attributes — a `Color`, a `Tensor`;
-- it may **not name `Core` at all** — no require, no constant, no attribute;
-- it reaches `Core` only through objects handed to it. A node's `on_draw`
-  receives a renderer and calls methods on it by name, never storing it and
-  never asking what class it is.
+- It may hold `Util` values as attributes, such as a `Color` or a `Tensor`.
+- It may **not name `Core` at all**: no require, no constant, no attribute.
+- It reaches `Core` only through objects it receives. A node's `on_draw`
+  receives a renderer and calls its methods by name. The node never stores the
+  renderer and never checks its class.
 
-This is not tidiness. It is what keeps a whole game — its rules, its scenes, its
-collisions — runnable and testable with no window, which the testing section
-below relies on. Two RuboCop cops enforce it in both directions, so a stray
-reference is a failing lint rather than a discovery made later.
+These rules keep a whole game runnable and testable with no window: its rules,
+its scenes, its collisions. The testing section below relies on that. RuboCop
+cops enforce the rules in both directions inside rgame's own repository, and a
+project from `rgame new` runs the first of them over its `nodes/` and `spec/`.
+See [the generated RuboCop configuration](cli.md#the-generated-rubocop-configuration).
 
-`RGame::Game` is the single exception, and the only class directly under
-`RGame`: introducing the two halves to each other is exactly what it is for, and
-confining that to one file is what keeps the rule checkable everywhere else.
+`RGame::Game` is the one exception: the only class that names both `Engine` and
+`Core`. It exists to connect the two halves. Keeping that in one file lets the
+rule hold everywhere else.
 
 ## A complete program
 
-A game is a tree of nodes plus `RGame::Game` to run it.
+A game is a tree of nodes, run by `RGame::Game`.
 
 ```ruby
 require 'rgame/game'
 
 # One game object: a square the player walks around. Pure Engine — it names no
-# graphics class, so it runs just as happily in a spec with no window.
+# graphics class, so it runs unchanged in a spec with no window.
 class Hero < RGame::Engine::Node2D
   SPEED = 200.0
 
@@ -135,10 +139,11 @@ class Hero < RGame::Engine::Node2D
   end
 
   # The renderer is handed in and never stored; `view` is the viewport being
-  # drawn into, which most nodes ignore. Draw from the resolved absolute
-  # position, not from `x`/`y`. See docs/api/drawing.md.
+  # drawn into, which most nodes ignore. Draw in the node's own space: the
+  # traversal has already put the renderer on this node, so (0, 0) is here.
+  # See docs/api/scene_graph.md, "Drawing happens in local space".
   def on_draw(renderer, _view)
-    renderer.rect(abs_x, abs_y, width, height)
+    renderer.rect(0, 0, width, height)
   end
 end
 
@@ -153,27 +158,26 @@ end
 RGame::Game.new(root: Scene.new, width: 800, height: 600, caption: 'My Game').start
 ```
 
-You subclass `Node2D` and override the hooks you care about — `on_control`,
-`on_update`, `on_draw`, and the lifecycle hooks around them. Everything you do
-not override is an inherited no-op, and the phase methods that do the
-bookkeeping (resolving the transform, driving components, descending into
-children) are not the ones you override — so there is no `super` to remember and
-no way to break the tree by forgetting one. See [Scene graph](scene_graph.md)
-for the full list, and [Game](game.md) for what `Game` assembles around it: the
+Subclass `Node2D` and override the hooks you need: `on_control`, `on_update`,
+`on_draw`, and the lifecycle hooks around them. A hook you do not override does
+nothing. Separate phase methods do the bookkeeping: they push the node's
+transform, drive components and descend into children. You never override
+those, so there is no `super` to forget. [Scene graph](scene_graph.md) lists
+every hook. [Game](game.md) describes what `Game` builds around the tree: the
 window, the renderer, the asset manager, the sound device, the input mapper and
 the players.
 
-Pass no `input_map:` and you get the default one used above: eight-way `move_x`
-/ `move_y` on the arrows, WASD, the d-pad or the left stick, plus `fire`. See
-[Input](input.md).
+Without an `input_map:`, `Game` uses the default map shown above. It binds
+eight-way `move_x` / `move_y` to the arrows, WASD, the d-pad and the left stick,
+and adds `fire`. See [Input](input.md).
 
 ## Testing a game built on this
 
-The namespace split exists so that game logic can be tested without opening a
-window. `require 'rgame'` gives you `Util` and the whole scene graph with no SDL
-and no OpenGL in the process, and the nodes from the program above run there
-unchanged — drive their phases directly and a simulated hour takes milliseconds:
+`require 'rgame'` loads `Util` and the whole scene graph with no SDL and no
+OpenGL. The nodes from the program above run there unchanged. A spec drives
+their phases directly, so a simulated hour takes milliseconds:
 
+<!-- doc-example: skip — an RSpec file for the Hero above, run by rspec -->
 ```ruby
 require 'rgame'
 
@@ -195,20 +199,20 @@ RSpec.describe Hero do
 end
 ```
 
-Two things make that work:
+Two properties make this work:
 
-- **`update` takes `dt` as an argument rather than reading a clock**, so a test
-  passes whatever timestep it likes. That means tests are not dependent on real time and can simulate game behavior based on time in miliseconds.
-- **A node never holds a renderer.** `on_draw` is given one, so drawing can be
-  checked by passing a recording double and asserting on what the node asked
-  for — see the renderer contract in `spec/support/shared_examples/`. All tests can be run completely headless.
+- **`update` takes `dt` as an argument and reads no clock.** A test passes any
+  timestep it likes, so it can simulate minutes of play in milliseconds.
+- **A node never holds a renderer.** `on_draw` receives one. A spec passes a
+  recording double and asserts on what the node asked it to draw. rgame's own
+  suite checks its fake renderer against the real one with a shared contract in
+  `spec/support/shared_examples/`. The whole suite runs headless.
 
-`hero.x` is asserted rather than `abs_x` because this node has no parent here.
-Absolute position accumulates from the parent, and a node with no parent resolves
-to the origin. Put it under a root and `abs_x` is what the rest of the engine
-reads. See [Scene graph](scene_graph.md#absolute-position).
+The spec asserts `hero.x`, not `world_x`, because this hero has no parent. The
+world transform accumulates from the parent, and a node without one resolves to
+the origin. Under a root, game logic reads `world_x`. Drawing reads neither; see
+[Scene graph](scene_graph.md#drawing-happens-in-local-space).
 
-Keep the parts of your game that decide *what happens* in `RGame::Engine` — the
-layer cannot name `RGame::Core`, so it cannot accidentally acquire a dependency
-on a window. Then the only code that needs one is the thin layer that puts
-pixels on screen.
+Keep the code that decides *what happens* in `RGame::Engine`. That layer cannot
+name `RGame::Core`, so it cannot come to depend on a window. Only the thin layer
+that puts pixels on screen then needs one.

data/docs/api/app.md

@@ -1,7 +1,7 @@
 # `RGame::Core::App`
 
-The window and the frame loop. Subclass it, override the hooks you need, call
-`run`.
+`App` owns the window and runs the frame loop. Subclass it, override the hooks
+you need, and call `run`.
 
 ```ruby
 require 'rgame/core'
@@ -13,44 +13,44 @@ end
 MyGame.new.run   # returns when the loop stops
 ```
 
-`App.new` takes keyword arguments only. `width:`, `height:` and `caption:` are
-required; `media_root:` is optional and defaults to `'media'`. Creating one
-opens a real window immediately.
+`App.new` takes keyword arguments only. It requires `width:`, `height:` and
+`caption:`. `media_root:` is optional and defaults to `'media'`. The constructor
+opens a real window at once.
 
 ## What the app owns
 
-Two things a game needs exactly one of, built on first use:
+The app builds two objects on first use. A game needs exactly one of each:
 
 ```ruby
+require 'rgame/core'
+
 class MyGame < RGame::Core::App
-  def initialize = super(width: 640, height: 480, caption: 'demo', media_root: MEDIA)
+  def initialize = super(width: 640, height: 480, caption: 'demo', media_root: 'assets')
 end
 
-app.assets   # => RGame::Core::AssetManager, rooted at media_root
-app.audio    # => RGame::Core::Audio, the sound device
+app = MyGame.new
+app.assets   # => RGame::Core::AssetManager — rooted at media_root
+app.audio    # => RGame::Core::Audio — the sound device
 ```
 
 **A game never constructs either of them.** An image belongs to one OpenGL
-context and has to be told which, so something must hold the app — and since the
-asset manager is the only thing in the engine that loads from a path, that
-something is the app itself, once, rather than a parameter threaded through
-every class that ends up owning an image.
+context, so whatever loads it must know the app. The app builds its asset manager
+once, and scenes load through it by path. No class has to pass the app along to
+reach an image.
 
-Both are lazy, and that matters in each case. An app that draws only shapes
-builds no asset manager; an app that never plays anything never opens a sound
-device — and asking for a sound is the first thing that needs one, so that is
-also the right moment to open it.
+Both objects are built on first use. `RGame::Core::Renderer.new(app)` asks for the
+asset manager, so any app that draws has one. An app that never plays a sound
+never opens a sound device; the first sound request opens it.
 
-`media_root` is read-only and set at construction. There is deliberately no
-writer: changing it after an asset had loaded would leave one cache keyed
-against two roots.
+`media_root` is read-only and fixed at construction. It has no writer: changing
+the root after a load would leave one cache keyed against two roots.
 
-See [Sheets, atlases and maps](assets.md) for what the asset manager does.
+[Assets](assets.md) describes the asset manager.
 
 ## The frame loop
 
-`run` drives the loop until something stops it, calling back into your object.
-One rendered frame looks like this:
+`run` drives the loop until something stops it, and calls back into your object.
+One rendered frame runs these steps:
 
 ```
   poll input and window events   →  button_down / button_up / resize
@@ -59,33 +59,30 @@ One rendered frame looks like this:
   update(dt)                     →  zero or more times (see below)
   needs_redraw?                  →  once; false skips the draw
   draw                           →  once, unless skipped
+  frame_end                      →  once, after draw, unless skipped
 ```
 
 ### `update(dt)` runs a *fixed* number of times, not once per frame
 
-This is the most important thing to understand about the loop.
+**The simulation advances in fixed steps.** Each frame adds the real elapsed
+time to an accumulator. The frame then runs every whole step that has come due.
+That can be **zero** steps, when the machine renders faster than the simulation
+needs. It can be **several**, when a slow frame forces the simulation to catch
+up. The loop caps catch-up, so a slow frame slows time down instead of spiralling.
 
-The simulation advances in fixed steps. Real elapsed time accumulates, and each
-frame runs however many whole steps have come due — which may be **zero**
-(the machine is rendering faster than the simulation needs) or **several** (a
-frame took a long time and the simulation is catching up). Catch-up is capped,
-so a very slow frame makes time slow down rather than spiral.
+`dt` is always the same fixed step: **1/60 second**. It is never wall-clock
+frame time. A fixed step makes movement reproducible. It also lets a test call
+`update` directly and simulate any amount of time.
 
-`dt` is always the same fixed step, currently **1/60 second**. It is never
-wall-clock frame time. That is deliberate: it makes movement reproducible, and
-it is why a test can drive `update` directly and simulate any amount of time.
-
-The practical consequence: **do not sample input inside `update`.** A key held
-for one frame would be read once or five times depending on how slow the last
-frame was. Sample it in `frame_begin` instead, or rely on `Input`, which reads
-a snapshot taken once per frame and therefore answers identically for every
-tick of that frame.
+**Do not sample input inside `update`.** A frame may run one tick or five, so a
+key held for one frame would be read a varying number of times. Sample input in
+`frame_begin`, or use `Input`. `Input` reads a snapshot taken once per frame, so
+it answers the same for every tick of that frame.
 
 ### `needs_redraw?`
 
-Return `false` and the draw is skipped for that frame; the simulation still
-advances. Useful when nothing has changed and drawing is expensive. The default
-is `true`.
+Return `false` to skip the draw for that frame. The simulation still advances.
+Use it when nothing changed and drawing costs a lot. The default is `true`.
 
 ```ruby
 def update(_dt)
@@ -100,12 +97,12 @@ def draw
 end
 ```
 
-Because `update` running at all means a step happened, `@dirty = true` inside
-`update` is usually the whole rule you need.
+`update` runs only when a step happened. Setting `@dirty = true` there is usually
+the whole rule.
 
 ## Hooks you can override
 
-Every one has an inherited no-op default, so override only what you use.
+Every hook inherits a default that does nothing. Override only what you use.
 
 | Hook | When |
 |---|---|
@@ -113,20 +110,23 @@ Every one has an inherited no-op default, so override only what you use.
 | `update(dt)` | One fixed simulation tick. |
 | `needs_redraw?` | Before drawing; `false` skips `draw`. Default `true`. |
 | `draw` | Render one frame. |
-| `button_down(id)` | A key was pressed. Auto-repeats are filtered, so a held key fires once. |
+| `frame_end` | After `draw` reaches the GPU, before the buffer swap. Not called when the draw was skipped. |
+| `button_down(id)` | A key was pressed. The loop filters auto-repeats, so a held key fires once. |
 | `button_up(id)` | A key was released. |
 | `resize(width, height)` | The window changed size. |
 | `gamepad_connected(slot)` | A controller arrived in a player slot. |
 | `gamepad_disconnected(slot)` | A controller left a slot. |
 
-`id` is a value from [`RGame::Util::Controls`](input.md) — for example
+`id` is a value from [`RGame::Util::Controls`](input.md), such as
 `Controls::KEY_ESCAPE`.
 
+`frame_end` is the one point where a test can read back the frame it drew.
+Game code rarely needs it.
+
 ### There is no built-in quit key
 
-Closing the window stops the loop, because that really is the platform's
-decision. Quitting on Escape is *your* decision, so the engine does not make it
-for you:
+Closing the window stops the loop, because the platform decides that. Quitting
+on Escape is *your* decision, so the engine leaves it to you:
 
 ```ruby
 def button_down(id)
@@ -142,17 +142,56 @@ end
 | `close` | Asks the loop to stop. Safe to call from inside any hook. |
 | `width`, `height` | Current window size. |
 | `caption`, `caption=` | The window title. |
-| `ticks_ms` | Monotonic milliseconds since startup. For animation phase. |
+| `fullscreen?`, `fullscreen=` | Whether the window covers the screen. |
+| `ticks_ms` | Monotonic milliseconds since startup. For measuring frames, not for drawing. |
 | `fps` | Most recent frames-per-second reading, updated about once a second. |
 
-`close` takes effect promptly — the loop checks between steps, so it will not
-start further work in the current frame.
+`close` takes effect promptly. The loop checks between steps and starts no more
+work in the current frame.
+
+`ticks_ms` is the raw clock. A draw never reads it: animation accumulates its own
+time in `update`.
+
+### Fullscreen
+
+```ruby
+require 'rgame/core'
+
+app = RGame::Core::App.new(width: 640, height: 480, caption: 'demo', fullscreen: true)  # opens fullscreen
+app.fullscreen = !app.fullscreen?                                                      # switches either way
+```
+
+**To open fullscreen, pass `fullscreen: true` to the constructor.** Setting it
+after the window is up also works, but shows one windowed frame first. Players
+read that flash as a broken startup. A game whose settings say fullscreen passes
+the setting to `new`.
+
+`width` and `height` still matter when the window opens fullscreen. The window
+takes that size when it leaves fullscreen.
+
+rgame uses **desktop** fullscreen: the window covers the screen at the screen's
+own resolution. The display never changes mode. The switch is instant, needs no
+mode list, and leaves other windows alone. The game gets a bigger view, not a
+different one.
+
+**Switching resizes the window**, so the loop calls
+[`resize`](#hooks-you-can-override) with the new size. A user dragging a window
+edge triggers the same call. Everything that lays out against the window learns
+of the change through that one path. So a scene reads the `view` it is drawn
+with, not the width it passed to `new`.
+
+A layout written against fixed numbers will not follow a bigger view.
+[`scale_mode:`](game.md#scale_mode--what-width-and-height-mean) on `RGame::Game`
+offers the alternative: keep a logical size and scale it onto the window.
+
+`examples/fullscreen` shows both ways to open, the switch, and every scale mode.
 
 ## Raw input queries
 
-`App` exposes the input snapshot directly. Most code should use
-[`RGame::Core::Input`](input.md), which takes symbolic action names instead of
-numeric ids, but these are the primitives underneath:
+`App` exposes the input snapshot directly. Code written against Core alone
+usually calls [`RGame::Core::Input`](input.md) instead, whose `down?` and `axis`
+default the device to the keyboard. A game on `RGame::Game` reads actions and
+never calls either. These queries are the primitives underneath:
 
 | Method | |
 |---|---|
@@ -162,15 +201,34 @@ numeric ids, but these are the primitives underneath:
 | `gamepad_name(slot)` | Its human-readable name, or `nil`. |
 | `gamepad_count` | How many controllers are connected. |
 
-Note the query is `gamepad_present?`, not `gamepad_connected?` — the latter
-name belongs to the hot-plug *hook* above, and two methods differing only by a
-`?` would be a trap.
+The query is named `gamepad_present?`, not `gamepad_connected?`. The hot-plug
+*hook* above owns that name, and two methods that differ only by a `?` invite
+mistakes.
+
+## The player's languages
+
+```ruby
+require 'rgame/core'
+
+RGame::Core.preferred_locales   # => ["de-AT", "en"] — most preferred first
+```
+
+`RGame::Core.preferred_locales` returns the locales the operating system says the
+user prefers, most preferred first. It is a module function: it needs no app and
+no window. Each entry is a language, followed by a hyphen and a country when the
+OS names one. The list is `[]` when the OS names none, as on Linux under
+`LANG=C`. It never holds `nil` or an empty String.
+
+It returns what SDL reports, unfiltered. On Linux SDL reads `LANG`, then
+`LANGUAGE`, and ignores `LC_ALL`, so a locale can appear twice. macOS and Windows
+ask the OS. Picking the language a game shows is
+[`I18n.choose`](localization.md#locales-and-the-fallback-chain), and `RGame::Game`
+makes that choice at startup.
 
 ## When a hook raises
 
-An exception thrown from any hook comes back out of `run` with its class,
-message and backtrace intact. The loop shuts down cleanly first, so the window
-is not left stranded:
+`run` re-raises any exception from a hook, with its class, message and backtrace
+intact. The loop shuts down cleanly first and closes the window:
 
 ```ruby
 begin
@@ -180,13 +238,12 @@ rescue MyGameError => e
 end
 ```
 
-A **non-local exit** — `throw`, `break` or `return` crossing out of a hook —
-cannot be carried across the loop the same way, and is reported as a
-`RuntimeError` telling you to use `close` instead. Use `close` to stop the
-loop; it is the only supported way out other than closing the window.
+A **non-local exit** cannot cross the loop that way. That covers `throw`,
+`break` or `return` leaving a hook. `run` reports it as a `RuntimeError` that
+tells you to use `close`. Only `close` and closing the window stop the loop.
 
 ## Several windows in one process
 
-Creating more than one `App` works, and they may overlap in lifetime; the
-engine keeps SDL alive until the last one is gone. This mostly matters for test
-suites, which create and discard a window per example.
+A process can create more than one `App`, and their lifetimes may overlap. The
+engine keeps SDL alive until the last one is gone. Test suites rely on this: they
+create and discard a window per example.