rgame 0.1.0 → 0.3.0

data/docs/api/images.md

@@ -1,8 +1,8 @@
 # Images
 
 `RGame::Core::Image` is a picture on the GPU. Loading one decodes a PNG and
-uploads it; everything after that — subimages, tiles, whole sprite sheets — is a
-*view* of that single upload.
+uploads it once. Subimages, tiles and whole sprite sheets are all *views* of that
+single upload.
 
 ```ruby
 require 'rgame/core'
@@ -12,8 +12,12 @@ frame = img.subimage(0, 0, 16, 16)
 walk  = RGame::Core::Image.load_tiles(app, 'hero.png', 16, 16)
 ```
 
-There is nothing to draw them with yet — the renderer is the next piece of the
-engine to land. What works today is loading, slicing and measuring.
+[Drawing](drawing.md) covers putting images on screen.
+
+**A game loads images through the [asset manager](assets.md)**, with
+`app.assets.image(path)`. The manager resolves the path against `media_root` and
+caches the image. `Image.new` and `Image.load_tiles` bypass that cache, and resolve a
+relative path against the working directory.
 
 ## Loading
 
@@ -23,13 +27,12 @@ image.width    # => 64
 image.height   # => 32
 ```
 
-The `app` argument is required and comes first. A texture lives inside one
-OpenGL context, so an image genuinely is an image *of* a window rather than a
-free-floating object — and saying so is what makes two windows work, and what
-lets the image keep its app alive for as long as it needs it.
+**The `app` argument is required and comes first.** A texture lives inside one
+OpenGL context, so an image belongs to a window. Naming the app lets two windows
+work side by side. It also lets the image keep its app alive as long as it needs.
 
-PNG is the only format. A file that cannot be read or decoded raises
-`RGame::Core::Image::LoadError` with the path in the message:
+rgame reads PNG only. A file it cannot read or decode raises
+`RGame::Core::Image::LoadError`, with the path in the message:
 
 ```ruby
 begin
@@ -39,12 +42,11 @@ rescue RGame::Core::Image::LoadError => e
 end
 ```
 
-Greyscale and palette PNGs load fine; they are converted to RGBA on the way in,
-so there is only ever one pixel format in play.
+Greyscale and palette PNGs load too. The loader converts them to RGBA, so the
+engine handles one pixel format.
 
-**Images are always sampled nearest-neighbour.** There is no setting for it.
-The engine exists to draw pixel art, and blurring it on scale-up is never the
-intent.
+**Images always use nearest-neighbour sampling**, with no setting to change it.
+The engine draws pixel art, and pixel art should never blur when scaled up.
 
 ## Slicing: subimages and tiles
 
@@ -58,25 +60,24 @@ sheet.tiles(16, 16)             # => [Image, Image, ...] all eight
 sheet.each_tile(16, 16) { |t| }  # the same, without building the Array
 ```
 
-`Image.load_tiles(app, path, w, h)` is `new` plus `tiles` in one step, and is
-the usual way to open a sprite sheet:
+`Image.load_tiles(app, path, w, h)` combines `new` and `tiles`. It is the usual
+way to open a sprite sheet:
 
 ```ruby
 frames = RGame::Core::Image.load_tiles(app, 'explosion.png', 32, 32)
 ```
 
-Three things are worth knowing about all of these:
+Three rules apply to all of these methods.
 
-**Nothing is decoded or uploaded twice.** A hundred tiles are a hundred small
-Ruby objects over one texture. Slicing a sheet is cheap enough to do at load
-time without thinking about it.
+**Nothing is decoded or uploaded twice.** A hundred tiles are a hundred small Ruby
+objects over one texture. Slice sheets at load time without worrying about cost.
 
-**Tiles come back in reading order** — left to right, then top to bottom — which
-is how sprite-sheet frames are numbered everywhere else.
+**Tiles come back in reading order**: left to right, then top to bottom. Sprite
+sheets number their frames the same way.
 
-**A partial tile at the right or bottom edge is not a tile.** A 70-pixel-wide
-sheet sliced into 16s yields four columns and leaves six pixels of padding
-alone, because half a sprite is never what was meant.
+**A partial tile at the right or bottom edge is not a tile.** Slicing a 70-pixel
+sheet into 16s yields four columns. The six leftover pixels count as padding,
+because half a sprite is never wanted.
 
 ### Coordinates are relative to what you cut from
 
@@ -87,24 +88,23 @@ row  = sheet.subimage(0, 16, 64, 16)   # the bottom row of the sheet
 tile = row.subimage(32, 0, 16, 16)     # 32 pixels into *the row*, not the sheet
 ```
 
-A rectangle that does not fit raises `ArgumentError`, and an out-of-range tile
-index raises `IndexError`, rather than either returning `nil`:
+**Bad coordinates raise; they never return `nil`.** A rectangle that does not fit
+raises `ArgumentError`. An out-of-range tile index raises `IndexError`:
 
 ```ruby
 sheet.subimage(0, 0, 999, 999)   # ArgumentError: does not fit in a 64x32 image
 sheet.tile(16, 16, 99)           # IndexError: 8 tiles of 16x16
 ```
 
-A `nil` here would travel a long way — into an asset table, out of it three
-scenes later — before failing as a `NoMethodError` with nothing left pointing at
-the coordinates that were wrong.
+A `nil` would travel a long way: into an asset table, and out again three scenes
+later. It would finally fail as a `NoMethodError` that no longer points at the
+wrong coordinates.
 
 ## Lifetime
 
-You never free an image. The texture is released when the last view of it is
-garbage-collected, and the order does not matter: dropping the sheet while its
-tiles are still in use keeps the upload alive, and dropping the window first is
-also fine.
+**You never free an image.** The engine releases the texture when the last view
+of it is garbage-collected, in any order. Tiles still in use keep the upload
+alive after the sheet is dropped. Dropping the window first also works.
 
 ```ruby
 sheet  = RGame::Core::Image.new(app, 'tiles.png')
@@ -112,7 +112,7 @@ ground = sheet.tile(16, 16, 0)
 sheet  = nil     # the upload stays — `ground` is still a view of it
 ```
 
-That is worth stating because a leaked GPU texture is invisible while it
-happens: nothing is slower, nothing looks wrong, and video memory fills up over
-an hour of play. `Image.debug_live_textures` reports how many uploads exist, and
-is there for tests to assert against; it is not part of the drawing API.
+A leaked GPU texture shows no symptoms at first. Nothing slows down and nothing
+looks wrong, while video memory fills over an hour of play.
+`Image.debug_live_textures` returns how many uploads exist. Tests assert against
+it; it is not part of the drawing API.

data/docs/api/input.md

@@ -1,119 +1,376 @@
 # Input
 
-Three pieces work together:
+Input has four pieces, in two layers:
 
-- **`RGame::Util::Controls`** — the vocabulary: which number means "the left
-  arrow key", "the A button", "player 2's controller". Plain values, usable
-  without loading any graphics library.
-- **`RGame::Core::Input`** — translates your game's *actions* (`:fire`,
-  `:confirm`) into those ids and asks the app whether they are held.
-- **`RGame::Core::Gamepad`** — which controllers are plugged in, for menus.
+- **`RGame::Util::Controls`** is the vocabulary. It says which number means "the
+  left arrow key", "the A button" or "player 2's controller". These are plain
+  values, usable without any graphics library.
+- **`RGame::Core::Input`** is the raw query: is *this id* active on *this
+  device*?
+- **`RGame::Engine::InputMap`** says what those ids *mean*. Each player has one
+  table that maps the game's actions onto physical ids.
+- **`RGame::Engine::ActionMapper`** polls one player's device through their map
+  once per tick. It produces an `Actions` snapshot.
 
-There is no mouse support, by design.
+**`RGame::Core::Gamepad`** adds a readout of the plugged-in controllers, for
+menus.
 
-## `RGame::Core::Input`
+rgame has no mouse support, by design.
+
+## Which layer do I want?
+
+**Use the engine layer.** A game declares its actions, reads
+`actions.held?(:fire)`, and names a scancode only inside its input map. The
+mapper polls `RGame::Core::Input`. Call `Input` directly only when you write
+against `RGame::Core` alone, with no scene graph.
 
 ```ruby
-input = RGame::Core::Input.new(app)
+require 'rgame/game'
+
+Controls = RGame::Util::Controls
 
-input.down?(:fire)                 # keyboard — the single-player default
-input.down?(:fire, device: pad)    # a specific controller
-input.axis(:move_x, device: pad)   # => Float
+class MyRoot < RGame::Engine::Node2D; end
+
+RGame::Game.new(
+  root: MyRoot.new,
+  input_map: RGame::Engine::InputMap.new(
+    fire: { buttons: [Controls::KEY_SPACE, Controls::PAD_A] }
+  )
+).start
 ```
 
-`down?` and `axis` read a snapshot the engine takes **once per frame**, when it
-pumps events. That is what makes them safe to call from `update`: a frame can
-run several simulation ticks, and every tick sees the same answer. Reading
-hardware directly would make a held key behave differently depending on how
-slow the previous frame was.
+## `RGame::Engine::InputMap`
+
+An `InputMap` holds one entry per action and names physical ids directly. **A
+rebinding screen edits this one table.**
+
+```ruby
+require 'rgame'
+
+Controls = RGame::Util::Controls
 
-### Actions, not keys
+map = RGame::Engine::InputMap.new(
+  turn:   { axis: [Controls::KEY_LEFT, Controls::KEY_RIGHT], stick: Controls::AXIS_LEFT_X },
+  thrust: { axis: [Controls::KEY_DOWN, Controls::KEY_UP], stick: Controls::AXIS_TRIGGER_RIGHT },
+  fire:   { buttons: [Controls::KEY_SPACE, Controls::PAD_A] }
+)
+```
 
-You ask for `:fire`, not for the space bar. The mapping lives in a binding
-table, so the same game code works for a keyboard player and a controller
-player:
+An entry uses up to three kinds of source, and may combine them:
 
-| Action | Keyboard | Gamepad |
+| Key | Read with | Meaning |
 |---|---|---|
-| `:left` `:right` `:up` `:down` | arrow keys | dpad |
-| `:confirm` | Return | A |
-| `:fire` | Space | A |
+| `buttons:` | `held?` / `pressed?` / `released?` | down if **any** listed id is down |
+| `axis:` | `axis` | `[negative_id, positive_id]`, or a list of such pairs — a digital axis from buttons |
+| `stick:` | `axis` | an analog axis id, for a real stick or a trigger |
 
-Asking for an action nothing is bound to raises `KeyError`.
+`map[action]` returns an entry as an `InputMap::Binding`: a frozen Struct with
+`buttons`, `pairs` and `stick`. `pairs` is always a list of pairs, even when the
+entry gave one, and a source the entry does not use is `nil`.
 
-### Devices
+A list of pairs binds several controls to one axis. The default `move_x` uses
+this for the arrows, WASD and the d-pad:
+
+```ruby
+move_x: { axis: [[Controls::KEY_LEFT, Controls::KEY_RIGHT],
+                 [Controls::PAD_DPAD_LEFT, Controls::PAD_DPAD_RIGHT]],
+          stick: Controls::AXIS_LEFT_X }
+```
+
+When an action binds several axis sources, **the largest deflection wins**. No
+per-device branching is needed. A keyboard reads `0.0` for every stick, and a
+gamepad reads `false` for every key. The source for the other device contributes
+nothing.
 
-Device 0 is the keyboard, and it is the default — so single-player code never
-mentions devices at all. Controllers follow, one per player slot:
+### One table serves every device
+
+An entry can list a key and a pad button together, because **a device answers
+only for its own kind of input**. A gamepad asked about a keyboard scancode
+answers `false`; it never passes on the keyboard's state. So `fire` can be
+"Space or A", and each player's device uses the half that applies to it.
+
+### Prompts need the device's half
+
+Reading an action needs no branch, but **showing** one does. A prompt saying
+"press Space or A" tells players about hardware they are not holding.
 
 ```ruby
-Controls = RGame::Util::Controls
+map.button_for(:fire, Controls::KEYBOARD)     # => KEY_SPACE
+map.button_for(:fire, Controls.gamepad(0))    # => PAD_A
+```
 
-Controls::KEYBOARD       # => 0
-Controls.gamepad(0)      # the first controller
-Controls.gamepad(1)      # the second
-Controls::MAX_GAMEPADS   # how many slots exist
+`button_for(action, device)` returns the first id bound to `action` that
+`device` can press. It compares `Controls.pad_button?(id)` against
+`Controls.gamepad?(device)`; the two id spaces never overlap. The first match
+wins, so an entry's order is a prompt's preference. `ui_confirm` lists Return
+before Space, so its prompt says Return.
+
+`button_for` returns `nil` in three cases:
+
+- nobody bound the action;
+- the action has no buttons. A stick or digital axis is not a button, and needs
+  a different picture;
+- the entry has nothing for that kind of device.
+
+It allocates nothing, so a HUD may call it every frame instead of caching a
+string.
+
+`examples/input_glyphs` shows the whole idea. It draws three prompts from a glyph
+sheet keyed by button id. A seat moves between the keyboard and a controller
+while you watch.
+
+### A stick's sign is the device's
+
+`AXIS_LEFT_Y` is positive **downwards**, like screen coordinates. An action that
+wants the opposite, such as "thrust" or "climb", negates at the call site or
+binds a trigger. The map stays declarative, with no inversion flag for every
+reader to check.
+
+### The universal UI set
+
+**Every map merges over a universal UI set**, so these actions exist whether a
+game declares them or not:
+
+- `ui_up`, `ui_down`, `ui_left`, `ui_right`, `ui_confirm`, `ui_cancel` are
+  buttons.
+- `ui_radial_x` and `ui_radial_y` are axes on the left stick, the arrow keys and
+  the d-pad. A menu built with [`Pointing`](ui.md#pointing) reads them.
+
+Keyboard navigation and menus need these actions for **every** player. The `ui_`
+prefix leaves `:up` free for the game. To change a binding, declare it:
+
+```ruby
+RGame::Engine::InputMap.new(ui_confirm: { buttons: [Controls::PAD_X] })
+```
+
+By default the radial axes share the left stick with `move_x` and `move_y`. They
+remain separate actions. A game that walks on the left stick can move its wheel
+to the right stick without touching movement.
+
+`ui_cancel` is Escape. That is why `RGame::Game` quits on `F2`: players expect
+Escape to back out of a menu.
+
+### Defaults and rebinding
+
+`InputMap.default` is the UI set plus eight-way movement and `fire`. `move_x` and
+`move_y` sit on the arrows, WASD, the d-pad and the left stick. A game that wants
+exactly this passes no `input_map:`.
+
+`#merge` returns a copy with some actions replaced. A config screen uses it to
+rebind one action without restating the rest:
+
+```ruby
+map = RGame::Engine::InputMap.default.merge(fire: { buttons: [Controls::KEY_RETURN] })
 ```
 
-A device only answers for its own kind of input. Asking a gamepad about a
-keyboard key is `false`, never the keyboard's answer — otherwise player two's
-pad would echo player one. The keyboard has no axes, so `axis` on it is `0.0`.
+**A malformed entry raises at construction.** That covers an unknown source key,
+an entry with no source, an empty button list, and an axis that is not a pair.
+Otherwise the action would read as "never pressed" for the rest of the program.
+Someone would discover it as a frame where nothing moves.
 
-### Rebinding
+## `RGame::Engine::ActionMapper`
 
-A binding table is just a Hash of action to id, and the ids are ordinary values
-from `Util`, so a game can build its own and hand it over:
+Each player has one `ActionMapper`. It polls that player's device through their
+map and returns the `Actions` snapshot game logic reads.
 
 ```ruby
-controls = RGame::Util::Controls
-bindings = controls::DEFAULT_KEYBOARD.merge(fire: controls::KEY_RETURN)
+mapper = RGame::Engine::ActionMapper.new(map, device: Controls.gamepad(0))
+actions = mapper.poll(input)
 
-input = RGame::Core::Input.new(app, bindings: bindings)
+actions.held?(:fire)      # is it down now
+actions.pressed?(:fire)   # did it go down this tick
+actions.released?(:fire)  # did it come up this tick
+actions.axis(:turn)       # -1.0..1.0
 ```
 
-`Input.new` accepts three optional tables:
+**Asking about an undeclared action raises `KeyError`**, naming the action and
+listing the declared ones. A mistyped name fails on the first tick instead of
+reading as "never pressed".
 
-| Keyword | Default | Used for |
+**The device lets two players share one map.** Every query carries the device,
+so two mappers over the *same* map read two different controllers. Each mapper
+keeps its own previous-tick state, so their edge queries stay independent.
+Reassign `mapper.device` to follow a hot-plug.
+
+`dead_zone:` (default `0.15`) ignores a resting stick, which reports small
+non-zero values. It **rescales** the range instead of cutting it off, so a stick
+leaving the dead zone ramps up from zero.
+
+`RGame::Game` builds the mappers and polls them once per tick. A game normally
+sees only the `Actions` passed to `control`.
+
+## Players, seats and joining
+
+`RGame::Engine::Players` is a root-scoped system that knows who is playing. Each
+`RGame::Engine::Player` owns a device, an `InputMap`, a camera and a UI root.
+Players share the game's action *names* but not the buttons behind them.
+
+```ruby
+RGame::Game.new(root: MyRoot.new, players: 2)
+```
+
+`players:` sets how many **seats** the game has, which is the most people who
+can play. Player 0 starts on `Game`'s `device:`, the keyboard by default; the
+other seats start empty. An empty
+seat draws no viewport. A two-seat game with one player looks like an ordinary
+full-screen game.
+
+`player.active?` is `false` while that seat is empty. `players.each_active` yields
+only the seated players, and `players.active_count` counts them.
+
+### A device is seated when someone uses it
+
+**Plugging a controller in seats nobody.** A plug says something about hardware.
+Seating a player creates a camera, a viewport and a screen split. That needs a
+statement of intent: a **`ui_confirm` press** on the device.
+
+Joining waits for one action, not for any input, so a stick resting off centre
+never seats a player. It reacts to the press edge, not to a held button, so one
+press does one thing. `Players` reads the press through the map of the player who
+would receive the device. Rebinding `ui_confirm` therefore rebinds "press to
+join".
+
+```ruby
+players = node.system(RGame::Engine::Players)
+
+players.on_unassigned_input = :join       # :join | :takeover | :ignore
+players.accepting_joins = false           # temporarily refuse
+players.on_joined { |player| spawn(player) }
+```
+
+| Policy | A press on a device nobody holds | Default when |
 |---|---|---|
-| `bindings:` | `Controls::DEFAULT_KEYBOARD` | keyboard buttons |
-| `pad_bindings:` | `Controls::DEFAULT_PAD` | controller buttons |
-| `axis_bindings:` | `Controls::DEFAULT_AXES` | analog axes |
+| `:join` | fills the next free seat | there is more than one seat |
+| `:takeover` | becomes the **primary** player's device | there is one seat |
+| `:ignore` | nothing; the game calls `players.seat(device)` itself | — |
+
+**`:takeover` serves single-player games.** A solo player who picks up a
+controller is not a second person arriving. Their keyboard becomes unassigned,
+and a `ui_confirm` press on it switches back. The last device used wins, in both
+directions. Only `ui_confirm` switches; W does nothing. To switch on any key, set
+`:ignore` and assign `players.primary.device` yourself. If the controller is
+unplugged, the player falls back to the keyboard, so the game keeps responding.
+
+**Under `:join` and `:ignore`, unplugging a controller empties its seat.** The
+player's device becomes `nil`, so they draw no viewport until a device is seated
+again. `players.seat(device)` fills the first empty seat and returns that player,
+or `nil` when every seat is taken or joins are refused.
+
+`accepting_joins = false` refuses both joins and takeovers. Use it during a
+cutscene or a mid-round lockout.
+
+`on_joined` fires with the player who received the device. A scene uses it to
+spawn that player's character without polling. `examples/split_screen` shows the
+whole flow in one file. The game opens full-screen for one player and splits
+when a controller presses A.
 
-The defaults are frozen, so `merge` a copy rather than mutating them.
+## `RGame::Core::Input`
 
-## `RGame::Util::Controls`
+`Input` answers the raw query and nothing more.
+
+```ruby
+input = RGame::Core::Input.new(app)
+
+input.down?(Controls::KEY_SPACE)                             # keyboard
+input.down?(Controls::PAD_A, device: Controls.gamepad(0))    # player 1's pad
+input.axis(Controls::AXIS_LEFT_X, device: Controls.gamepad(0))
+```
+
+**`down?` and `axis` read a snapshot the engine takes once per frame**, when it
+pumps events. So they are safe to call from `update`. A frame can run several
+simulation ticks, and every tick sees the same answer. Reading the hardware
+directly would make a held key depend on how slow the previous frame was.
+
+Ids are numbers that cross into C, so anything else raises `TypeError`. `Input`
+applies no dead zone; it returns the hardware's answer.
+
+### Devices
+
+**Device 0 is the keyboard, and the default**, so single-player code never names
+a device. Controllers follow, one per player slot:
 
-The id vocabulary. Available from `require 'rgame'` **and** from
-`require 'rgame/core'`, because these are plain integers with nothing behind
-them — a game's configuration screen can name a key without pulling in a window.
+```ruby
+Controls::KEYBOARD       # => 0
+Controls.gamepad(0)      # the first controller
+Controls.gamepad(1)      # the second
+Controls::MAX_GAMEPADS   # how many slots exist
+```
 
-**Keys** — `KEY_LEFT`, `KEY_RIGHT`, `KEY_UP`, `KEY_DOWN`, `KEY_RETURN`,
-`KEY_SPACE`, `KEY_ESCAPE`, `KEY_F1`.
+A device answers only for its own kind of input. A gamepad asked about a
+keyboard key answers `false`. Otherwise player two's pad would echo player one's
+keys. The keyboard has no axes, so `axis` on it returns `0.0`.
 
-**Gamepad buttons** — `PAD_A`, `PAD_B`, `PAD_X`, `PAD_Y`, `PAD_BACK`,
+## `RGame::Util::Controls`
+
+`Controls` is the id vocabulary. Both `require 'rgame'` **and**
+`require 'rgame/core'` load it. The ids are plain integers, so a configuration
+screen can name a key without opening a window.
+
+**Keys**: the 81 keys a Western keyboard reliably has.
+
+| | |
+|---|---|
+| Letters | `KEY_A` … `KEY_Z` |
+| Digits | `KEY_1` … `KEY_9`, `KEY_0` |
+| Whitespace and editing | `KEY_RETURN`, `KEY_ESCAPE`, `KEY_BACKSPACE`, `KEY_TAB`, `KEY_SPACE` |
+| Punctuation | `KEY_MINUS`, `KEY_EQUALS`, `KEY_LEFTBRACKET`, `KEY_RIGHTBRACKET`, `KEY_BACKSLASH`, `KEY_SEMICOLON`, `KEY_APOSTROPHE`, `KEY_GRAVE`, `KEY_COMMA`, `KEY_PERIOD`, `KEY_SLASH` |
+| Function row | `KEY_CAPSLOCK`, `KEY_F1` … `KEY_F12` |
+| Navigation | `KEY_INSERT`, `KEY_HOME`, `KEY_PAGEUP`, `KEY_DELETE`, `KEY_END`, `KEY_PAGEDOWN` |
+| Arrows | `KEY_LEFT`, `KEY_RIGHT`, `KEY_UP`, `KEY_DOWN` |
+| Modifiers | `KEY_LCTRL`, `KEY_LSHIFT`, `KEY_LALT`, `KEY_RCTRL`, `KEY_RSHIFT`, `KEY_RALT` |
+
+**A scancode is a position, not a letter.** `KEY_A` is the key marked A on a
+QWERTY board and Q on AZERTY. That suits `WASD` movement. A rebinding screen has
+to explain it to players. The engine only compares numbers.
+
+**Some keys are left out on purpose**: the numpad (most laptops lack one), the
+GUI key (Windows on a PC, Command on a Mac), the print-screen cluster, and any key
+whose position depends on the layout. Adding a key takes three edits: a
+`#define` in `ext/rgame_core/include/rgame/core.h`, a `_Static_assert` against
+the SDL scancode, and a constant here. `spec/rgame/util/controls_spec.rb` checks
+that all three agree.
+
+**Gamepad buttons**: `PAD_A`, `PAD_B`, `PAD_X`, `PAD_Y`, `PAD_BACK`,
 `PAD_GUIDE`, `PAD_START`, `PAD_LEFT_STICK`, `PAD_RIGHT_STICK`,
 `PAD_LEFT_SHOULDER`, `PAD_RIGHT_SHOULDER`, `PAD_DPAD_UP`, `PAD_DPAD_DOWN`,
 `PAD_DPAD_LEFT`, `PAD_DPAD_RIGHT`.
 
-**Axes** — `AXIS_LEFT_X`, `AXIS_LEFT_Y`, `AXIS_RIGHT_X`, `AXIS_RIGHT_Y`,
-`AXIS_TRIGGER_LEFT`, `AXIS_TRIGGER_RIGHT`. Sticks read −1.0 to 1.0 with **y
-positive downwards**; triggers read 0.0 to 1.0. No dead zone is applied — where
-to put one is a game decision, and a resting stick genuinely does report small
-non-zero values.
+Some buttons exist only on some hardware. They read as never pressed on a pad
+without them: `PAD_MISC1` (share/capture/microphone), `PAD_PADDLE1` …
+`PAD_PADDLE4` (Xbox Elite), `PAD_TOUCHPAD` (PS4/PS5).
+
+**Axes**: `AXIS_LEFT_X`, `AXIS_LEFT_Y`, `AXIS_RIGHT_X`, `AXIS_RIGHT_Y`,
+`AXIS_TRIGGER_LEFT`, `AXIS_TRIGGER_RIGHT`. Sticks read −1.0 to 1.0, with **y
+positive downwards**. Triggers read 0.0 to 1.0. `Controls` applies no dead zone.
+A resting stick reports small non-zero values, and the game decides where to cut
+them off.
 
-**Devices** — `KEYBOARD`, `GAMEPAD_FIRST`, `MAX_GAMEPADS`, and
+**Devices**: `KEYBOARD`, `GAMEPAD_FIRST`, `MAX_GAMEPADS`, and
 `Controls.gamepad(slot)`.
 
-**Default tables** — `DEFAULT_KEYBOARD`, `DEFAULT_PAD`, `DEFAULT_AXES`.
+**This module holds the vocabulary only**, with no binding tables.
+`RGame::Engine::InputMap` says what an id *means*, one map per player.
 
-Buttons and keys share one numbering, partitioned into ranges, so a single
-"is it held" query serves every device. You never need the numbers themselves —
-use the constants.
+Buttons and keys share one numbering, split into ranges. One "is it held" query
+therefore serves every device. Use the constants; you never need the numbers.
+
+A prompt has to know **which side of the split** an id is on, so `Controls` names
+the check:
+
+```ruby
+Controls.gamepad?(device)   # a controller slot, or the keyboard?
+Controls.pad_button?(id)    # a pad button, or a key?
+```
+
+`BUTTON_GAMEPAD_FIRST` marks the boundary. It is the C engine's own
+`RGAME_BUTTON_GAMEPAD_FIRST`, checked against the header like every other id.
+[`InputMap#button_for`](#prompts-need-the-devices-half) is built from these two
+checks.
 
 ## `RGame::Core::Gamepad`
 
-A readout for menus — "Player 2: connect a controller". Reading a *button* goes
-through `Input`; this answers what is plugged in.
+`Gamepad` tells a menu what is plugged in, for screens like "Player 2: connect a
+controller". Button reads go through `Input`.
 
 ```ruby
 pads = RGame::Core::Gamepad.new(app)
@@ -121,34 +378,36 @@ pads = RGame::Core::Gamepad.new(app)
 pads.count                                # how many are connected
 pads.max_slots                            # how many slots exist
 pads.connected?(0)                        # is slot 0 filled?
-pads.name(0)                              # => "Xbox Controller", or nil
+pads.name(0)                              # => "Xbox Controller" — or nil
 pads.device(0)                            # the id Input wants for that slot
 pads.each_connected { |slot, name| ... }  # lowest slot first
 ```
 
-`device(slot)` is the bridge to `Input`: a menu that has just found a pad can
-drive it without knowing how devices are numbered.
+`device(slot)` connects `Gamepad` to `Input`. A menu that finds a pad can drive
+it without knowing how devices are numbered.
 
-Out-of-range slots answer rather than raising, so a UI loop needs no bounds
-checks.
+An out-of-range slot returns an answer instead of raising, so a UI loop needs no
+bounds checks.
 
 ### Slots are stable across a replug
 
-A controller that falls out and comes back returns to the **same** slot, so
-player 2 stays player 2. The engine remembers which device last occupied each
-slot; a genuinely new controller takes the lowest free one.
+**A controller that drops out and returns gets the same slot back**, so player 2
+stays player 2. The engine remembers which device last used each slot. A new
+controller takes the lowest free slot.
 
 Two identical controllers report the same hardware id, so "the slot that
-remembers this controller" is ambiguous for them. The rule resolves it the way
-a player expects: two matching pads take slots 0 and 1, and whichever is
-unplugged gets its own slot back when it returns.
+remembers this controller" is ambiguous. The engine resolves it the way players
+expect. Two matching pads take slots 0 and 1. Whichever is unplugged gets its own
+slot back when it returns.
 
 ## Reacting to hot-plug
 
-Polling with `Gamepad` answers "what is connected now". The `App` hooks tell you
-when that changes:
+`Gamepad` answers "what is connected now". The `App` hooks report when that
+changes:
 
 ```ruby
+require 'rgame/core'
+
 class MyGame < RGame::Core::App
   def initialize
     super(width: 800, height: 600, caption: 'demo')
@@ -170,10 +429,10 @@ class MyGame < RGame::Core::App
   end
 
   def update(_dt)
-    @moving_left = @input.down?(:left, device: @device)
+    @moving_left = @input.down?(RGame::Util::Controls::KEY_LEFT, device: @device)
   end
 end
 ```
 
-A controller unplugged mid-press has its buttons and axes cleared, so a button
-held at that moment does not stay stuck down.
+When a controller is unplugged mid-press, the engine clears its buttons and axes.
+A button held at that moment does not stay stuck down.