rgame 0.1.0 → 0.2.0

data/docs/api/game.md

@@ -7,8 +7,8 @@ engine.
 $LOAD_PATH.unshift File.expand_path('../lib', __dir__)
 require 'rgame/game'
 
-class HelloScene < Engine::Node2D
-  def on_draw(renderer) = renderer.text('Hello world!', 250, 200)
+class HelloScene < RGame::Engine::Node2D
+  def on_draw(renderer, _view) = renderer.text('Hello world!', 250, 200)
 end
 
 RGame::Game.new(root: HelloScene.new, caption: 'Hello').start
@@ -20,19 +20,24 @@ sound device, the input mapper, the debug overlay — and drives the root node.
 
 ```ruby
 RGame::Game.new(root:, width: 640, height: 480, caption: 'RGame',
-                media_root: 'media', action_map: {})
+                media_root: 'media', input_map: nil, device: Controls::KEYBOARD)
 ```
 
 | Reader | |
 |---|---|
 | `root` | the node tree |
 | `renderer` | what scenes draw through |
-| `action_mapper` | physical input → named actions |
+| `players` | who is playing: their devices, bindings and cameras |
 | `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. `Esc` quits and
-`F1` toggles the debug overlay.
+calls `enter_tree`, and runs the loop until the window closes. `F1` toggles the
+debug overlay and `F2` quits.
+
+**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.
 
 ## Why this class exists at all
 
@@ -57,19 +62,35 @@ sheet = node.root.context.assets.sheet('player.json')
 
 ## Input
 
-`action_map` names the actions a game has, in terms of the physical ids
-[Input](input.md) knows:
+`input_map:` names the actions a game has, in terms of physical ids from
+[`RGame::Util::Controls`](input.md):
 
 ```ruby
+Controls = RGame::Util::Controls
+
 RGame::Game.new(
   root: Root.new,
-  action_map: {
-    move_x: { axis: %i[left right] },   # -1.0 .. 1.0
-    fire:   { button: %i[fire] }        # held / pressed / released
-  }
+  input_map: RGame::Engine::InputMap.new(
+    move_x: { axis: [Controls::KEY_LEFT, Controls::KEY_RIGHT],  # -1.0 .. 1.0
+              stick: Controls::AXIS_LEFT_X },
+    fire:   { buttons: [Controls::KEY_SPACE, Controls::PAD_A] } # held / pressed / released
+  )
 )
 ```
 
+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.
+
+`device:` picks what drives player one — the keyboard by default, or
+`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).
+
 A scene reads the resulting snapshot in `on_control(actions)` — `actions.axis(:move_x)`,
 `actions.pressed?(:fire)` — and never sees a key.
 
@@ -92,7 +113,7 @@ behaviour around the tree rather than replacing the shell.
 ```ruby
 class MyGame < RGame::Game
   def button_down(id)
-    super                      # keeps Esc and F1 working
+    super                      # keeps F1 and F2 working
     @paused = !@paused if id == RGame::Util::Controls::KEY_SPACE
   end
 end

data/docs/api/input.md

@@ -1,85 +1,240 @@
 # Input
 
-Three pieces work together:
+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::Core::Input`** — the raw query: is *this id* active on *this
+  device*.
+- **`RGame::Engine::InputMap`** — what those ids *mean*: one table per player,
+  mapping a game's actions onto physical ids.
+- **`RGame::Engine::ActionMapper`** — polls one player's device through their
+  map once per tick and produces an `Actions` snapshot.
+
+Plus **`RGame::Core::Gamepad`**, a readout of which controllers are plugged in,
+for menus.
 
 There is no mouse support, by design.
 
-## `RGame::Core::Input`
+## Which layer do I want?
 
-```ruby
-input = RGame::Core::Input.new(app)
+Almost always the engine layer. A game declares its actions, reads
+`actions.held?(:fire)`, and never names a scancode outside its input map.
+`RGame::Core::Input` is what the mapper polls; you reach for it directly only
+when writing against `RGame::Core` alone, with no scene graph.
 
-input.down?(:fire)                 # keyboard — the single-player default
-input.down?(:fire, device: pad)    # a specific controller
-input.axis(:move_x, device: pad)   # => Float
+```ruby
+RGame::Game.new(
+  root: MyRoot.new,
+  input_map: RGame::Engine::InputMap.new(
+    fire: { buttons: [Controls::KEY_SPACE, Controls::PAD_A] }
+  )
+)
 ```
 
-`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`
+
+One entry per action, naming physical ids directly. **This is the single table a
+rebinding screen edits.**
+
+```ruby
+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:
+Three kinds of source, and one action 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]` — a digital axis from two buttons |
+| `stick:` | `axis` | an analog axis id, for a real stick or a trigger |
 
-Asking for an action nothing is bound to raises `KeyError`.
+When an action binds both `axis:` and `stick:`, **the larger deflection wins**.
+That needs no per-device branching: a keyboard reads `0.0` for every axis and a
+stick reads `false` for every key, so whichever device a player is on, the other
+source contributes nothing.
 
-### Devices
+### One table serves every device
 
-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:
+Listing a key and a pad button in the same entry is safe, because **a device
+only answers for its own kind of input** — asking a gamepad about a keyboard
+scancode is `false`, never the keyboard's answer. So `fire` can be "Space or A",
+and each player's device picks out the half that applies to it.
+
+### A stick's sign is the device's
+
+`AXIS_LEFT_Y` is positive **downwards**, like screen coordinates. An action that
+wants the opposite ("thrust", "climb") negates at the call site or binds a
+trigger instead — the map stays declarative rather than growing an inversion
+flag every reader would have to check for.
+
+### The universal UI set
+
+Every map is merged over a universal set, so these exist whether or not a game
+declares them:
+
+`ui_up`, `ui_down`, `ui_left`, `ui_right`, `ui_confirm`, `ui_cancel`
+
+Keyboard navigation and menus rely on them being there for **every** player. They
+are prefixed so a game is free to use `:up` for something of its own, and a game
+that wants different bindings just declares one:
 
 ```ruby
-Controls = RGame::Util::Controls
+InputMap.new(ui_confirm: { buttons: [Controls::PAD_X] })
+```
 
-Controls::KEYBOARD       # => 0
-Controls.gamepad(0)      # the first controller
-Controls.gamepad(1)      # the second
-Controls::MAX_GAMEPADS   # how many slots exist
+`ui_cancel` is Escape — which is why `RGame::Game`'s quit key is `F2`. The button
+a player expects to back out of a menu belongs to the menu.
+
+### Defaults and rebinding
+
+`InputMap.default` is the UI set plus eight-way movement (`move_x`, `move_y`) on
+the arrows or the left stick, and `fire`. A game wanting exactly that passes no
+`input_map:` at all.
+
+`#merge` returns a copy with some actions replaced, which is how a config screen
+rebinds one 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 — an unknown source key, an entry with
+no source, an empty button list, an axis that is not a pair. That is deliberate:
+the alternative is an action that reads as "never pressed" for the rest of the
+program, discovered as a frame nobody can move in.
 
-### 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:
+One per player. 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:
+**The device is what makes two players work.** Every query carries it, so two
+mappers over the *same* map read two different controllers, and each keeps its
+own previous-frame state so their edge queries are independent. Reassign
+`mapper.device` to follow a hot-plug.
+
+`dead_zone:` (default `0.15`) ignores a resting stick, which genuinely reports
+small non-zero values. It **rescales** rather than merely cutting off, so a stick
+leaving the dead zone ramps from zero instead of jumping to `0.15`.
+
+`RGame::Game` builds one of these for you and polls it once per tick; a game
+normally sees only the `Actions` handed to `control`.
+
+## Players, seats and joining
+
+`RGame::Engine::Players` is a root-scoped system holding who is playing. Each
+`RGame::Engine::Player` owns a device, an `InputMap`, a camera and a UI root —
+the action *names* are the game's and shared, the buttons behind them are not.
+
+```ruby
+RGame::Game.new(root: MyRoot.new, players: 2)
+```
 
-| Keyword | Default | Used for |
+`players:` is how many **seats** the game has, and therefore the most people who
+can play it. Player 0 starts on the keyboard; the rest start empty. An empty
+seat draws no viewport, so a two-seat game with nobody in the second one is an
+ordinary full-screen single-player game.
+
+### A device is seated when someone uses it
+
+Not when it is plugged in. Plugging a controller in says something about
+hardware; seating a player creates a camera, a viewport and a screen split, and
+that follows a statement of intent — a **`ui_confirm` press** on the device.
+
+One action rather than "any input", because a stick resting slightly off centre
+must never seat a player. An edge rather than held, so one press does one thing.
+It is read through the map of whoever would receive the device, so rebinding
+`ui_confirm` rebinds "press to join" with it.
+
+```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` is single-player's answer: one person already playing who picks up a
+controller is not a second person arriving. Their keyboard becomes unassigned,
+so using it again takes them back — last device used wins. And if their
+controller is unplugged they fall back to the keyboard rather than the game
+going dead in their hands.
+
+`accepting_joins = false` refuses both, which is what a cutscene or a mid-round
+lockout wants.
+
+`on_joined` fires with the player who got the device, which is how a scene
+spawns their character without polling for one. See `examples/15_tiled_world`.
+
+## `RGame::Core::Input`
+
+The raw query, and deliberately 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))
+```
 
-The defaults are frozen, so `merge` a copy rather than mutating them.
+`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.
+
+Ids are numbers, and they cross into C, so passing anything else raises
+`TypeError`. No dead zone is applied here — this is the hardware's answer.
+
+### It used to hold the binding tables
+
+It took `down?(:fire)` and resolved `:fire` through one of three tables passed to
+its constructor. Those tables are gone. Binding moved up to `InputMap` for two
+reasons: a rebinding screen has to be able to edit the table, and the engine
+layer may not name `RGame::Core` at all; and with a player per device, the table
+is a per-player value rather than a property of the one object that talks to the
+hardware.
+
+### Devices
+
+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:
+
+```ruby
+Controls::KEYBOARD       # => 0
+Controls.gamepad(0)      # the first controller
+Controls.gamepad(1)      # the second
+Controls::MAX_GAMEPADS   # how many slots exist
+```
+
+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`.
 
 ## `RGame::Util::Controls`
 
@@ -87,14 +242,39 @@ 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.
 
-**Keys** — `KEY_LEFT`, `KEY_RIGHT`, `KEY_UP`, `KEY_DOWN`, `KEY_RETURN`,
-`KEY_SPACE`, `KEY_ESCAPE`, `KEY_F1`.
+**Keys** — what a Western keyboard can be relied on to have, 81 of them:
+
+| | |
+|---|---|
+| 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 — which is what you want for `WASD` movement, and
+what a rebinding screen has to explain to the player. The engine only ever
+compares numbers.
+
+**Deliberately absent**: the numpad (most laptops have none), the GUI key
+(Windows on a PC, Command on a Mac), the print-screen cluster, and anything
+whose position depends on the layout. Adding one is a `#define` in
+`ext/rgame_core/include/rgame/core.h`, a `_Static_assert` against the SDL
+scancode, and a constant here — and the spec below checks 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`.
 
+Plus the ones only some hardware has, which 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. No dead zone is applied — where
@@ -104,7 +284,8 @@ non-zero values.
 **Devices** — `KEYBOARD`, `GAMEPAD_FIRST`, `MAX_GAMEPADS`, and
 `Controls.gamepad(slot)`.
 
-**Default tables** — `DEFAULT_KEYBOARD`, `DEFAULT_PAD`, `DEFAULT_AXES`.
+This module is the **vocabulary only**. It carries no binding tables — what an id
+*means* is `RGame::Engine::InputMap`, one 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 —
@@ -170,7 +351,7 @@ 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
 ```