rgame 0.4.0-x86_64-linux-gnu

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

@@ -0,0 +1,196 @@
+# 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
+
+      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] },
+        ui_radial_x: { axis: [[Controls::KEY_LEFT, Controls::KEY_RIGHT],
+                              [Controls::PAD_DPAD_LEFT, Controls::PAD_DPAD_RIGHT]],
+                       stick: Controls::AXIS_LEFT_X },
+        ui_radial_y: { axis: [[Controls::KEY_UP, Controls::KEY_DOWN],
+                              [Controls::PAD_DPAD_UP, Controls::PAD_DPAD_DOWN]],
+                       stick: Controls::AXIS_LEFT_Y }
+      }.freeze
+
+      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 button bound to `action` that `device` can actually press, or nil.
+      #
+      # This undoes what the section above describes. One entry lists a key and
+      # a pad button together so that polling needs no branch, and that is right
+      # for reading input and wrong for *showing* it: a prompt has to say "press
+      # A" or "press Space", never both, and which one depends on what the
+      # player last touched.
+      #
+      #   map.button_for(:fire, Controls::KEYBOARD)    # => KEY_SPACE
+      #   map.button_for(:fire, Controls.gamepad(0))   # => PAD_A
+      #
+      # The first match wins, so the order an entry lists its ids in is the order
+      # a prompt prefers them — `ui_confirm` names Return before Space, and a
+      # prompt for it says Return.
+      #
+      # Nil for an action nobody bound, for one with no buttons at all (a stick
+      # or a digital axis is not a button and a prompt for one is a different
+      # picture), and for a device kind the entry does not cover. A caller
+      # showing a prompt has to handle that nil either way, because a rebinding
+      # screen can leave an action unbound.
+      #
+      # Allocation-free, so a HUD may call it per frame rather than caching a
+      # string it would then have to invalidate.
+      def button_for(action, device)
+        binding = @bindings[action]
+        buttons = binding&.buttons
+        return nil if buttons.nil?
+
+        pad = Controls.gamepad?(device)
+        buttons.find { |id| Controls.pad_button?(id) == pad }
+      end
+
+      # 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
+
+      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
+
+      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

data/lib/rgame/engine/layout.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    # Where each viewport goes on screen: pure rectangle arithmetic, and nothing
+    # else.
+    #
+    #   Layout.rects(2, 640, 480)   # => [[0, 0, 640, 240], [0, 240, 640, 240]]
+    #
+    # No state, no anchors, no lifetime — so it is specced on its own with no
+    # tree and no window, which is the point of separating it from Viewports.
+    # That system holds *which* mode is current and *who* is playing; this only
+    # answers "given a count and a window, where do they go".
+    #
+    # ## Rects tile exactly
+    #
+    # Edges are computed as `(i * total) / count` rather than by multiplying a
+    # rounded size, so three rows of a 481-pixel window are 161, 160 and 160 and
+    # the last one still ends exactly at 481. Dividing first leaves a seam at the
+    # bottom of the screen that nothing draws into — a one-pixel line that looks
+    # like a rendering bug and is really a rounding one.
+    module Layout
+      # A window's worth of rows, columns or cells for `count` viewports.
+      #
+      # Two players get rows rather than columns because halving the height of a
+      # landscape window leaves each view landscape, while halving the width
+      # leaves two tall slots that fit a 2D scene badly. Three and four share a
+      # 2x2 grid, with the fourth cell left empty for three.
+      # Forwards its block with `&block` rather than re-yielding through
+      # `{ |*args| yield(*args) }`, which builds an Array per yield. Passing a
+      # block straight on allocates nothing — measured, not assumed; see the
+      # allocation example in layout_spec.rb.
+      def self.each_rect(count, width, height, &)
+        return if count <= 0
+        return yield(0, 0, 0, width, height) if count == 1
+        return each_row(count, width, height, &) if count == 2
+
+        each_cell(count, 2, 2, width, height, &)
+      end
+
+      # The same, as an Array of `[x, y, width, height]`. For specs and setup;
+      # the per-frame path uses #each_rect, which allocates nothing.
+      def self.rects(count, width, height)
+        result = []
+        each_rect(count, width, height) { |_i, x, y, w, h| result << [x, y, w, h] }
+        result
+      end
+
+      # `count` full-width rows, stacked.
+      def self.each_row(count, width, height)
+        count.times do |i|
+          top = edge(i, count, height)
+          yield(i, 0, top, width, edge(i + 1, count, height) - top)
+        end
+      end
+
+      # `count` full-height columns, side by side.
+      def self.each_column(count, width, height)
+        count.times do |i|
+          left = edge(i, count, width)
+          yield(i, left, 0, edge(i + 1, count, width) - left, height)
+        end
+      end
+
+      # The first `count` cells of a `cols` x `rows` grid, filled left to right,
+      # top to bottom.
+      def self.each_cell(count, cols, rows, width, height)
+        count.times do |i|
+          col = i % cols
+          row = i / cols
+          left = edge(col, cols, width)
+          top = edge(row, rows, height)
+          yield(i, left, top, edge(col + 1, cols, width) - left, edge(row + 1, rows, height) - top)
+        end
+      end
+
+      # The i-th boundary of `count` even divisions of `total`. Multiplying
+      # before dividing is what makes the divisions tile with no seam.
+      def self.edge(index, count, total) = (index * total) / count
+    end
+  end
+end

data/lib/rgame/engine/nav_grid.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    # A walkability grid and the searches over it: region labels and A* routes, run in C by a
+    # Util::RouteSearch over a Util::SolidGrid.
+    #
+    # Where TileBlockers answers *what is in the way of a step*, this answers *what is in the
+    # way of a route*: the same fact about the same cells, asked over a graph instead of along
+    # a box's sweep. Components::TileWorld owns both, over one store.
+    #
+    # It is built one of two ways:
+    #
+    # - **`grid:`** — over a SolidGrid it shares. A cell changed in that grid is changed here
+    #   at once, and region labels follow it on the next query with nothing rebuilt. This is
+    #   how a TileWorld builds one, and the way to build one over solidity that will change.
+    # - **`width:`, `height:`, `solid:`** — from a callable, `solid.call(col, row) -> bool`,
+    #   read once per cell into a private grid of its own. Nothing re-reads the callable, so a
+    #   change behind it is never seen.
+    #
+    # Anything else — both, or neither — is an ArgumentError.
+    #
+    # Routes are cells, never pixels. Turning a cell into the point a node must reach depends
+    # on the node's collider, which a grid has no business knowing; Components::Navigator
+    # does that.
+    #
+    # The grid is 8-connected with octile costs (1 straight, √2 diagonal), and a diagonal step
+    # is allowed only when both orthogonal cells beside it are open, so a route never cuts the
+    # corner of a solid cell. Connected regions are labelled whenever the grid has changed
+    # since they last were, which makes an unreachable goal — the answer a search is slowest
+    # to give, because it has to exhaust the region first — a lookup whenever it lies in
+    # another region.
+    #
+    # Coordinates are Integers, and anything else is a TypeError. An Integer outside the
+    # grid, however large, is answered like any cell outside it.
+    #
+    # A search runs on demand, never per frame, and allocates its result; everything else it
+    # keeps is reused between searches. One grid is therefore not safe to search from two
+    # threads at once.
+    class NavGrid
+      def initialize(grid: nil, width: nil, height: nil, solid: nil)
+        @grid = grid ? shared(grid, width, height, solid) : private_grid(width, height, solid)
+        @search = Util::RouteSearch.new(@grid)
+      end
+
+      def width = @grid.width
+      def height = @grid.height
+
+      def walkable?(col, row)
+        !@grid.solid?(col, row) && col >= 0 && row >= 0 && col < @grid.width && row < @grid.height
+      end
+
+      # The connected region containing the cell, as an Integer label — two walkable cells
+      # share a label exactly when a route joins them — or nil for a solid cell or one
+      # outside the grid.
+      def region(col, row) = @search.region(col, row)
+
+      def reachable?(from_col, from_row, to_col, to_row)
+        from = @search.region(from_col, from_row)
+        to = @search.region(to_col, to_row)
+        !from.nil? && from == to
+      end
+
+      # The cheapest route from start to goal, both included, as `[[col, row], ...]` — or
+      # nil when either end is solid, outside the grid, or in another region. Start equal
+      # to goal is a route of one cell. Ties between equally cheap routes are broken the
+      # same way every time, so the same query always returns the same route.
+      def find(from_col, from_row, to_col, to_row) = @search.find(from_col, from_row, to_col, to_row)
+
+      private
+
+      def shared(grid, width, height, solid)
+        return grid unless width || height || solid
+
+        raise ArgumentError, 'a NavGrid is built over a grid: or from width:, height: and solid:, not both'
+      end
+
+      def private_grid(width, height, solid)
+        unless width && height && solid
+          raise ArgumentError, 'a NavGrid needs a grid:, or all of width:, height: and solid:'
+        end
+
+        Util::SolidGrid.build(width, height) { |col, row| solid.call(col, row) }
+      end
+    end
+  end
+end