rgame 0.1.0 → 0.2.0

data/lib/rgame/engine/components/sprite.rb

@@ -13,6 +13,8 @@ module RGame
       # @layer to say so. For an animated sprite (sheet + frame index driving
       # renderer.sprite), add a sibling AnimatedSprite component later.
       class Sprite < Engine::Component
+        include Engine::Culling
+
         attr_accessor :scale
 
         def initialize(id:, scale: 1.0, z: 0)
@@ -22,7 +24,15 @@ module RGame
           @layer = z
         end
 
-        def draw(renderer)
+        # Centred on the node's origin and scaled, so the footprint to cull
+        # against is the node's box scaled and offset back by half of itself. A
+        # node that never set a size is never culled — see Culling.
+        def draw(renderer, view)
+          width = node.width * @scale
+          height = node.height * @scale
+          return if culled?(view, node.abs_x - (width / 2.0), node.abs_y - (height / 2.0),
+                            width, height)
+
           renderer.image(@id, node.abs_x, node.abs_y, scale: @scale, z: @layer)
         end
       end

data/lib/rgame/engine/components/tile_world.rb

@@ -11,27 +11,29 @@ module RGame
       # Collision reuses Engine::CollisionSystem (TileCollision + a world-bounds clamp);
       # the tile solidity is whatever the map's tileset reports (baked per-tile in Tiled).
       #
-      # Drawing splits into two z bands so actors can sit between them: the below band
-      # (ground, same-level detail) at GROUND_Z and the above band (canopies, roofs) at
-      # OVERLAY_Z. Actors draw at a z in between (the renderer sorts by z, so the
-      # draw-call order doesn't matter). The camera is centred by the scene before any
-      # drawing.
+      # **It does not draw.** Drawing the map is RGame::Engine::TileMapLayer, one
+      # node per Tiled layer, mounted inside the WorldView so the map is drawn
+      # once per viewport like the rest of the world. This stays a system — the
+      # thing actors ask about collision and bounds — and a system that also
+      # drew was always the odd part of it.
       #
-      # It also owns the map's **animation clock**. Nothing below reads a wall clock —
+      # It owns the map's **animation clock**. Nothing below reads a wall clock —
       # see CLAUDE.md, "`draw` renders state; time enters through `update`" — so the
       # elapsed seconds animated tiles run on are accumulated here and handed down at
       # draw time. Stop calling `update` and the water freezes, which is what pausing
       # should look like.
       class TileWorld < Engine::Component
-        GROUND_Z  = 0
-        OVERLAY_Z = 20
+        attr_reader :tilemap_id, :elapsed
 
-        def initialize(map:, tilemap_id:, camera:)
+        # `cameras` are the cameras this map bounds — every player's, normally.
+        # A camera may not show past the world's edges, and this is what knows
+        # how big the world is; the cameras themselves are owned by players.
+        def initialize(map:, tilemap_id:, cameras: [])
           super()
           @map = map
           @tilemap_id = tilemap_id
-          @camera = camera
           @elapsed = 0.0
+          Array(cameras).each { |camera| bound(camera) }
           @collision = Engine::CollisionSystem.new(
             tile_collision: Engine::TileCollision.new(
               tile_width: map.tile_width, tile_height: map.tile_height,
@@ -44,6 +46,25 @@ module RGame
         def world_width = @map.pixel_width
         def world_height = @map.pixel_height
 
+        def layer_count = @map.layer_count
+
+        # The first layer Tiled flags `above`, or the layer count if none is —
+        # which is where TileMapLayer.mount leaves the gap for the actors, so a
+        # map with no flag puts them over everything. Read once at mount rather
+        # than per frame: which layers cover the actors is a fact about the
+        # scene's arrangement, and the arrangement is made once.
+        def first_above_layer
+          layer_count.times.find { |index| @map.above_layer?(index) } || layer_count
+        end
+
+        # Clamp a camera to this map's edges. Called for each camera the scene
+        # hands over, and again for one that arrives later (a player joining).
+        def bound(camera)
+          camera.world_width = @map.pixel_width
+          camera.world_height = @map.pixel_height
+          camera
+        end
+
         # Move an actor (responds to x/y/collision_box) by (dx, dy), sliding along solids
         # and clamped inside the world. Delegates to the reused collision system.
         def move(actor, dx, dy) = @collision.move(actor, dx, dy)
@@ -54,14 +75,6 @@ module RGame
         def update(dt)
           @elapsed += dt
         end
-
-        def draw(renderer)
-          renderer.tilemap(@tilemap_id, @camera.x, @camera.y,
-                           @camera.viewport_width, @camera.viewport_height, elapsed: @elapsed)
-          renderer.tilemap_overlay(@tilemap_id, @camera.x, @camera.y,
-                                   @camera.viewport_width, @camera.viewport_height,
-                                   z: OVERLAY_Z, elapsed: @elapsed)
-        end
       end
     end
   end

data/lib/rgame/engine/culling.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    # Skipping a drawable that the viewport cannot show.
+    #
+    # Mixed into the components that draw a node's own footprint, which are the
+    # ones that know both where they put it and how big it is.
+    #
+    # ## Why it is worth doing at all
+    #
+    # It was not, while the world was drawn once: a handful of skipped draws
+    # against a frame's worth of work. Split-screen changes the arithmetic —
+    # the world is walked once per viewport, and an actor at one player's end of
+    # the map is off the *other* player's view every frame. What used to be a
+    # small saving becomes a saving multiplied by the number of people playing.
+    #
+    # ## Conservative on purpose
+    #
+    # Culling one frame too eagerly is a sprite popping in at the edge of the
+    # screen, which is worse than the draw it saved. So two rules:
+    #
+    # - **No size means no culling.** `node.width`/`height` are what a drawable's
+    #   footprint is measured from, and a node that never set them (nothing
+    #   requires it — `examples/14_asteroids` does not) reads as 0×0, which would
+    #   otherwise cull everything instantly. Unknown means draw.
+    # - **A rotated node is measured generously.** `Node2D#draw` rotates about the
+    #   node's absolute origin, so a rotated footprint can reach further than its
+    #   box in any direction. The margin is `width + height`, which is always at
+    #   least the diagonal `hypot(width, height)` and costs no square root on a
+    #   path that runs once per drawable per viewport.
+    module Culling
+      private
+
+      # Can this box be skipped for `view`? Coordinates are in the space the
+      # caller draws in — world coordinates under a camera.
+      # hot-path
+      def culled?(view, x, y, width, height)
+        return false if width.zero? || height.zero?
+        return !view.visible?(x, y, width, height) if node.abs_angle.zero?
+
+        margin = width + height
+        !view.visible?(x - margin, y - margin, width + (margin * 2), height + (margin * 2))
+      end
+    end
+  end
+end

data/lib/rgame/engine/debug_overlay.rb

@@ -36,7 +36,6 @@ module RGame
       DELTA_LABEL = 'Δ/f'
 
       COLOR = [80, 255, 120].freeze # frozen so the renderer caches the resolved colour
-      Z     = 1_000_000             # above any scene content
       PAD   = 8                     # margin from the screen edge
       GAP   = 8                     # space between a label and its number
 
@@ -55,7 +54,15 @@ module RGame
         @prev_allocated = GC.stat(:total_allocated_objects) if @visible
       end
 
-      def draw(renderer, width, height, fps)
+      # Laid out against the view it is drawn into rather than against the
+      # window, so it stays in the corner of whatever region it is given. It
+      # takes `fps` rather than reading it, for the same reason nothing here
+      # reads a clock: the number is measured by the shell that owns the loop
+      # and handed down. See CLAUDE.md, "`draw` renders state".
+      # Its own `:debug` band, which is the last one, so this lands over every
+      # other thing in the frame however the scene is arranged. Not a node, so
+      # it opens its own layer rather than being given one by the traversal.
+      def draw(renderer, view, fps)
         return unless @visible
 
         allocated = GC.stat(:total_allocated_objects)
@@ -63,12 +70,16 @@ module RGame
         @prev_allocated = allocated
 
         line_h  = renderer.text_height
-        right_x = width - PAD
-        top_y   = height - PAD - (line_h * 3)
+        # The view's size, not its position: inside a region that has been
+        # translated to its corner, adding `view.x` would offset a second time.
+        right_x = view.width - PAD
+        top_y   = view.height - PAD - (line_h * 3)
 
-        draw_line(renderer, FPS_LABEL, fps, right_x, top_y)
-        draw_line(renderer, OBJ_LABEL, allocated, right_x, top_y + line_h)
-        draw_line(renderer, DELTA_LABEL, delta, right_x, top_y + (line_h * 2))
+        renderer.layered(:debug) do
+          draw_line(renderer, FPS_LABEL, fps, right_x, top_y)
+          draw_line(renderer, OBJ_LABEL, allocated, right_x, top_y + line_h)
+          draw_line(renderer, DELTA_LABEL, delta, right_x, top_y + (line_h * 2))
+        end
       end
 
       private
@@ -76,7 +87,7 @@ module RGame
       # A right-aligned "label  number" row ending at right_x.
       def draw_line(renderer, label, value, right_x, y)
         number_left = draw_uint(renderer, value, right_x, y)
-        renderer.text(label, number_left - GAP - label_width(renderer, label), y, z: Z, color: COLOR)
+        renderer.text(label, number_left - GAP - label_width(renderer, label), y, color: COLOR)
       end
 
       # Draw a non-negative integer right-aligned ending at right_x, digit by digit so no
@@ -88,7 +99,7 @@ module RGame
           digit = value % 10
           value /= 10
           x -= digit_width(renderer, digit)
-          renderer.text(DIGITS[digit], x, y, z: Z, color: COLOR)
+          renderer.text(DIGITS[digit], x, y, color: COLOR)
           more = value.positive?
         end
         x

data/lib/rgame/engine/input/action_mapper.rb

@@ -2,45 +2,125 @@
 
 module RGame
   module Engine
-    # Polls an InputBackend through a binding map and produces an Actions snapshot.
-    # The map is `{ action_name => { axis: %i[neg pos] } | { button: %i[ids] } }`;
-    # physical ids are decoupled from any backend's constants (the backend resolves
-    # them), so remapping is just swapping this data.
+    # Polls one player's device through an InputMap and produces their Actions
+    # snapshot.
     #
-    # Pure logic: the backend is duck-typed — the whole interface is
-    # `down?(physical_id)` — so a test passes a fake and a game passes
-    # `RGame::Core::Input`.
+    #   mapper = ActionMapper.new(input_map, device: Controls.gamepad(0))
+    #   actions = mapper.poll(input)
+    #
+    # **One of these per player.** The device is what makes that 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.
+    #
+    # Pure logic. The backend is duck-typed and the whole interface is
+    # `down?(physical_id, device:)` and `axis(axis_id, device:)` — a spec passes
+    # a fake and a game passes RGame::Core::Input.
     class ActionMapper
-      attr_accessor :map
+      # A resting analog stick genuinely reports small non-zero values, so
+      # something has to ignore them. Here rather than in the game, because it
+      # is a property of the device, and here rather than in Core, because how
+      # much to ignore is a judgement rather than a fact about the hardware.
+      DEAD_ZONE = 0.15
+
+      attr_reader :map, :actions
+      attr_accessor :device, :dead_zone
 
-      def initialize(map)
+      def initialize(map, device: RGame::Util::Controls::KEYBOARD, dead_zone: DEAD_ZONE)
         @map = map
-        # One reusable snapshot: there's exactly one input state per tick, so we
-        # mutate these in place each poll instead of allocating (after the first
-        # poll warms the hash keys, steady-state polling allocates nothing).
-        # `@prev_held` carries last frame's button state so Actions can answer edge
-        # queries (pressed?/released?).
+        @device = device
+        @dead_zone = dead_zone
+
+        # One reusable snapshot: there is exactly one input state per tick per
+        # player, so these are mutated in place each poll instead of allocated.
+        # Seeded from the map's action list, so the hashes are warm before the
+        # first poll and steady-state polling allocates nothing at all.
         @held = {}
         @prev_held = {}
         @axes = {}
+        map.bindings.each_key do |name|
+          @held[name] = false
+          @prev_held[name] = false
+          @axes[name] = 0.0
+        end
         @actions = Actions.new(held: @held, axes: @axes, prev_held: @prev_held)
       end
 
       def poll(backend)
         # Snapshot this frame's held state as "previous" before recomputing it
-        # (in-place copy: no allocation once the keys exist).
+        # (in-place copy: no allocation, the keys already exist).
         @held.each { |name, down| @prev_held[name] = down }
 
-        @map.each do |name, binding|
-          if (axis = binding[:axis])
-            neg, pos = axis
-            @axes[name] = (backend.down?(pos) ? 1.0 : 0.0) - (backend.down?(neg) ? 1.0 : 0.0)
-          end
-          @held[name] = binding[:button].any? { |b| backend.down?(b) } if binding[:button]
+        return rest if @device.nil?
+
+        @map.bindings.each do |name, binding|
+          @held[name] = any_down?(backend, binding.buttons) if binding.buttons
+          @axes[name] = axis_value(backend, binding) if binding.pairs || binding.stick
         end
 
         @actions
       end
+
+      private
+
+      # A player with no device — an empty seat waiting for a controller — reads
+      # as nothing held and every axis centred. Returning the snapshot rather
+      # than refusing to poll is what lets a game show "press a button to join"
+      # with no special case, and it releases anything that was held when the
+      # controller was unplugged mid-press.
+      def rest
+        @held.each_key { |name| @held[name] = false }
+        @axes.each_key { |name| @axes[name] = 0.0 }
+        @actions
+      end
+
+      # hot-path
+      def any_down?(backend, ids)
+        ids.any? { |id| backend.down?(id, device: @device) }
+      end
+
+      # A digital axis and an analog one can both be bound to the same action —
+      # arrows *and* the left stick — so the larger deflection wins. That needs
+      # no per-device branching: a keyboard reads 0.0 for every axis and a stick
+      # reads 0.0 for every key, so whichever device the player is on, the other
+      # source contributes nothing.
+      # hot-path
+      def axis_value(backend, binding)
+        digital = digital_axis(backend, binding)
+        return digital unless binding.stick
+
+        analog = dead_zoned(backend.axis(binding.stick, device: @device))
+        digital.abs >= analog.abs ? digital : analog
+      end
+
+      # The largest deflection across every pair bound to this axis. Several
+      # pairs is how the arrows, WASD and a d-pad all drive one action; a device
+      # with only one of them reads 0.0 for the rest, so the others cost nothing.
+      # hot-path
+      def digital_axis(backend, binding)
+        pairs = binding.pairs
+        return 0.0 if pairs.nil?
+
+        best = 0.0
+        pairs.each do |pair|
+          value = (backend.down?(pair[1], device: @device) ? 1.0 : 0.0) -
+                  (backend.down?(pair[0], device: @device) ? 1.0 : 0.0)
+          best = value if value.abs > best.abs
+        end
+        best
+      end
+
+      # Rescaled rather than merely cut off, so the value ramps from zero as the
+      # stick leaves the dead zone. Cutting off alone makes it jump to the dead
+      # zone's width the moment it starts reading, which is a visible twitch.
+      # hot-path
+      def dead_zoned(value)
+        magnitude = value.abs
+        return 0.0 if magnitude <= @dead_zone
+
+        scaled = (magnitude - @dead_zone) / (1.0 - @dead_zone)
+        value.negative? ? -scaled : scaled
+      end
     end
   end
 end

data/lib/rgame/engine/input/actions.rb

@@ -3,39 +3,96 @@
 module RGame
   module Engine
     # An immutable per-frame snapshot of abstract action state. Game logic reads
-    # this, never physical keys. Built by ActionMapper (or constructed directly in
-    # tests with a fake).
+    # this, never physical keys. Built by ActionMapper (or constructed directly
+    # in a spec).
     #
-    # Edge queries (`pressed?`/`released?`) compare against the previous frame's held
-    # state, so a one-shot action (menu confirm, jump) fires exactly once per press
-    # rather than every frame it's held.
+    # Edge queries (`pressed?`/`released?`) compare against the previous frame's
+    # held state, so a one-shot action (menu confirm, jump) fires exactly once
+    # per press rather than every frame it is held.
+    #
+    # ## Reading an action nobody declared raises
+    #
+    # A game declares its actions once, in an InputMap. Asking for one that is
+    # not in it is a typo, not a question with an answer, so it raises KeyError
+    # rather than reading `false` forever:
+    #
+    #   actions.pressed?(:fyre)   # KeyError: no such action :fyre
+    #
+    # This matters because the failure it replaces is silent and remote. A
+    # misspelled action reads as "never pressed", and what the player sees is a
+    # button that does nothing — a bug that looks like it lives in the code that
+    # *would* have run. RGame::Core::Input used to raise KeyError for an unbound
+    # action and no longer can: it takes physical ids now, and binding moved up
+    # to InputMap. This is where that guarantee went.
+    #
+    # **The hashes are the declaration.** ActionMapper seeds all three from its
+    # map at construction, so every action the map knows answers and nothing
+    # else does. A spec constructing one directly declares whatever it passes:
+    #
+    #   Actions.new(axes: { move_x: 1.0, move_y: 0.0 })   # both answer
+    #   Actions.new(axes: { move_x: 1.0 }).axis(:move_y)  # KeyError
+    #
+    # That is stricter than it needs to be for a spec, and deliberately: a spec
+    # that has not said what the action set is cannot claim a component reads
+    # the right part of it.
     class Actions
-      # `held`, `axes` and `prev_held` are mutable hashes the mapper updates in place
-      # each poll, so the snapshot stays a single reused, allocation-free object.
+      # `held`, `axes` and `prev_held` are mutable hashes the mapper updates in
+      # place each poll, so the snapshot stays a single reused, allocation-free
+      # object.
       def initialize(held: {}, axes: {}, prev_held: {})
         @held = held
         @axes = axes
         @prev_held = prev_held
       end
 
+      # Every action this snapshot can answer for.
+      def declared = @held.keys | @axes.keys
+
+      # A snapshot is also a degenerate input *source*: it answers for whichever
+      # player is asking, because there is only one answer. That is what lets
+      # `node.control(actions)` keep working unchanged — a tree with nobody
+      # claiming ownership, or a spec that has only one player in mind, passes
+      # the snapshot itself where a Players registry would otherwise go.
+      # hot-path
+      def actions_for(_player) = self
+
+      # hot-path
       def held?(name)
-        @held.fetch(name, false)
+        @held.fetch(name) { undeclared(name) }
       end
 
       # True only on the frame the action transitions up→down.
+      # hot-path
       def pressed?(name)
-        @held.fetch(name, false) && !@prev_held.fetch(name, false)
+        @held.fetch(name) { undeclared(name) } && !@prev_held.fetch(name, false)
       end
 
       # True only on the frame the action transitions down→up.
+      # hot-path
       def released?(name)
-        !@held.fetch(name, false) && @prev_held.fetch(name, false)
+        !@held.fetch(name) { undeclared(name) } && @prev_held.fetch(name, false)
       end
 
-      # Analog value in [-1.0, 1.0]; 0.0 if unbound/neutral.
+      # Analog value in [-1.0, 1.0]; 0.0 for a declared action at rest.
+      # hot-path
       def axis(name)
-        @axes.fetch(name, 0.0)
+        @axes.fetch(name) { undeclared(name) }
+      end
+
+      private
+
+      # A block rather than `fetch(name)`'s bare KeyError, for a message that
+      # says what to do about it. The block only runs on a miss, so the reading
+      # path stays one hash lookup with nothing allocated.
+      def undeclared(name)
+        raise KeyError, "no such action #{name.inspect} — declare it in the InputMap " \
+                        "(this snapshot has #{declared.inspect})"
       end
+
+      # `prev_held` is read with a default on purpose. It is one frame behind, so
+      # on the very first poll after an action is added it legitimately has no
+      # entry, and "was not held before" is the right answer rather than an
+      # error. The current-frame lookup above is what catches a typo.
     end
   end
 end

data/lib/rgame/engine/input/input_map.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    # What physical inputs mean, for one player.
+    #
+    #   map = InputMap.new(
+    #     thrust: { axis: [Controls::KEY_DOWN, Controls::KEY_UP], stick: Controls::AXIS_TRIGGER_RIGHT },
+    #     fire:   { buttons: [Controls::KEY_SPACE, Controls::PAD_A] }
+    #   )
+    #
+    # One entry per action, naming **physical ids from RGame::Util::Controls**
+    # directly. That is the whole point of this class: it is the single table a
+    # rebinding screen edits, and it holds nothing but integers, so the engine
+    # layer may own one outright.
+    #
+    # Three kinds of source, and an action may combine them:
+    #
+    # | Key | Reads as | Meaning |
+    # |---|---|---|
+    # | `buttons:` | `held?` | 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 trigger |
+    #
+    # ## One table serves every device
+    #
+    # Listing a key and a pad button in the same entry is safe, and needs no
+    # per-device branching, 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 (see docs/api/input.md). So `fire` can be "Space or A"
+    # and each player's device picks out the half that applies to it.
+    #
+    # ## An axis can have several pairs, like a button can have several ids
+    #
+    # `axis: [KEY_LEFT, KEY_RIGHT]` is the common case and stays a bare pair.
+    # A list of pairs binds more than one control to the same axis:
+    #
+    #   move_x: { axis: [[Controls::KEY_LEFT, Controls::KEY_RIGHT],
+    #                    [Controls::PAD_DPAD_LEFT, Controls::PAD_DPAD_RIGHT]],
+    #             stick: Controls::AXIS_LEFT_X }
+    #
+    # Without it a d-pad cannot drive movement at all, because the same action
+    # already needed the arrow keys. The largest deflection wins, so the pairs
+    # cost nothing on a device that has only one of them.
+    #
+    # This replaces a two-stage scheme in which a game's action map named
+    # RGame::Core::Input's action names, which named physical ids — two tables in
+    # series, neither of them the one a config screen wanted, and the lower one
+    # unreachable from the engine layer, which may not name Core at all.
+    #
+    # ## A stick's sign is the device's, not the game'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 that every reader would then have to check for.
+    class InputMap
+      Controls = RGame::Util::Controls
+
+      # One action's resolved sources. Built once, at construction, so polling
+      # walks plain attribute reads and allocates nothing.
+      #
+      # `buttons` is "held if any of these is down"; `pairs` is a list of
+      # `[negative, positive]` button pairs, each a digital axis; `stick` is an
+      # analog axis id.
+      Binding = Struct.new(:buttons, :pairs, :stick)
+
+      SOURCES = %i[buttons axis stick].freeze
+
+      # The universal set, merged into every map unless the game overrides it.
+      #
+      # The UI package navigates and activates through these, so a control can
+      # rely on them existing for *every* player without a game having declared
+      # them. They are prefixed rather than plain (`ui_up`, not `up`) so a game
+      # is free to use `:up` for something of its own.
+      #
+      # `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.
+      UI = {
+        ui_up: { buttons: [Controls::KEY_UP, Controls::PAD_DPAD_UP] },
+        ui_down: { buttons: [Controls::KEY_DOWN, Controls::PAD_DPAD_DOWN] },
+        ui_left: { buttons: [Controls::KEY_LEFT, Controls::PAD_DPAD_LEFT] },
+        ui_right: { buttons: [Controls::KEY_RIGHT, Controls::PAD_DPAD_RIGHT] },
+        ui_confirm: { buttons: [Controls::KEY_RETURN, Controls::KEY_SPACE, Controls::PAD_A] },
+        ui_cancel: { buttons: [Controls::KEY_ESCAPE, Controls::PAD_B] }
+      }.freeze
+
+      # A playable starting point: eight-way movement on the arrows or the left
+      # stick, and a fire button. A game that wants exactly this declares
+      # nothing at all.
+      DEFAULT_ACTIONS = {
+        move_x: { axis: [[Controls::KEY_LEFT, Controls::KEY_RIGHT],
+                         [Controls::KEY_A, Controls::KEY_D],
+                         [Controls::PAD_DPAD_LEFT, Controls::PAD_DPAD_RIGHT]],
+                  stick: Controls::AXIS_LEFT_X },
+        move_y: { axis: [[Controls::KEY_UP, Controls::KEY_DOWN],
+                         [Controls::KEY_W, Controls::KEY_S],
+                         [Controls::PAD_DPAD_UP, Controls::PAD_DPAD_DOWN]],
+                  stick: Controls::AXIS_LEFT_Y },
+        fire: { buttons: [Controls::KEY_SPACE, Controls::PAD_A] }
+      }.freeze
+
+      # Every action this map can answer for, as `name => Binding`.
+      attr_reader :bindings
+
+      # `entries` are merged over the universal UI set, so declaring a game's
+      # actions never costs it the ones the UI needs.
+      def initialize(entries = {})
+        @bindings = UI.merge(entries).to_h { |name, entry| [name, build(name, entry)] }.freeze
+      end
+
+      # The default map: the UI set plus DEFAULT_ACTIONS.
+      def self.default = new(DEFAULT_ACTIONS)
+
+      # A copy with `entries` overriding, which is how a game rebinds one action
+      # without restating the rest.
+      def merge(entries) = self.class.new(to_h.merge(entries))
+
+      def [](action) = @bindings[action]
+
+      def actions = @bindings.keys
+
+      # The entries in the shape they were declared in, so a map can be edited
+      # and rebuilt (a config screen) or merged.
+      def to_h
+        @bindings.to_h do |name, binding|
+          entry = {}
+          entry[:buttons] = binding.buttons if binding.buttons
+          entry[:axis] = binding.pairs.size == 1 ? binding.pairs.first : binding.pairs if binding.pairs
+          entry[:stick] = binding.stick if binding.stick
+          [name, entry]
+        end
+      end
+
+      private
+
+      # Malformed entries raise here rather than reading as "nothing is ever
+      # pressed" for the rest of the program. An action name misspelled at a
+      # *read* site is still silent — see Actions — but one misspelled in the
+      # map is the mistake that is actually easy to make, and this catches it at
+      # construction rather than at the first frame nobody can move.
+      def build(name, entry)
+        unknown = entry.keys - SOURCES
+        raise ArgumentError, "#{name}: unknown source #{unknown.first.inspect}" unless unknown.empty?
+
+        buttons = freeze_ids(name, entry[:buttons])
+        pairs = axis_pairs(name, entry[:axis])
+        raise ArgumentError, "#{name}: no buttons, axis or stick" if buttons.nil? && pairs.nil? && entry[:stick].nil?
+
+        Binding.new(buttons, pairs, entry[:stick]).freeze
+      end
+
+      def freeze_ids(name, ids)
+        return nil if ids.nil?
+        raise ArgumentError, "#{name}: buttons must be a list of ids" unless ids.is_a?(Array) && !ids.empty?
+
+        ids.dup.freeze
+      end
+
+      # Accepts one `[negative, positive]` pair or a list of them. A bare pair
+      # is the common case and stays readable; a list is what lets the arrows,
+      # WASD and a d-pad all drive one axis.
+      def axis_pairs(name, axis)
+        return nil if axis.nil?
+
+        pairs = axis.is_a?(Array) && axis.first.is_a?(Array) ? axis : [axis]
+        pairs.each { |pair| check_pair(name, pair) }
+        pairs.map { |pair| pair.dup.freeze }.freeze
+      end
+
+      def check_pair(name, pair)
+        return if pair.is_a?(Array) && pair.size == 2
+
+        raise ArgumentError, "#{name}: axis must be [negative_id, positive_id], or a list of those"
+      end
+    end
+  end
+end