rgame 0.4.0-x86_64-linux-gnu

data/lib/rgame/rubocop/cop/game/no_literal_text.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Game
+      # Flag a String literal drawn or measured as a label: the first argument of
+      # `text` or `text_width`, on any receiver.
+      #
+      # Text a player reads belongs in a translation table, where `RGame::Game`
+      # loads it and a language switch reaches it. A literal at the call site is
+      # the one place no table can: it shows the same words in every language, and
+      # it is the form a reader copies out of an example. Build an `Engine::Text`
+      # from a key once, off the per-frame path, and pass it as it is.
+      #
+      # This sees the call site only. A constant or ivar holding a String passes,
+      # so a table of Strings chosen by state is not caught; whether a constant
+      # holds words is not a question syntax can answer.
+      #
+      # @example
+      #   # bad
+      #   renderer.text('Press Space to jump', 12, 12)
+      #   renderer.text("Lives: #{lives}", 12, 34)
+      #
+      #   # good
+      #   @help = Engine::Text.new('help.jump')   # in initialize
+      #   renderer.text(@help, 12, 12)
+      class NoLiteralText < RuboCop::Cop::Base
+        MSG = 'Draw an Engine::Text built from a key, not a String literal: ' \
+              'text a player reads belongs in a translation table.'
+
+        RESTRICT_ON_SEND = %i[text text_width].freeze
+
+        def on_send(node)
+          label = node.first_argument
+          add_offense(label) if label&.type?(:str, :dstr)
+        end
+        alias on_csend on_send
+      end
+    end
+  end
+end

data/lib/rgame/rubocop/cop/game/no_needless_allocation.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require_relative 'hot_path'
+
+module RuboCop
+  module Cop
+    module Game
+      # Flag fresh Array / Range literals that are needless per-frame allocations.
+      #
+      # Two triggers:
+      #  * Anywhere — a literal used as a method-call *receiver*: `[a, b].sum`,
+      #    `(a..b).any? { ... }`. Each call allocates the collection just to reduce or
+      #    iterate it; compare directly or loop with an index instead.
+      #  * Inside a per-frame method (a lifecycle hook or a `# hot-path`-tagged helper) —
+      #    *any* Array/Range literal, e.g. returning `[x, y, w, h]` for the caller to
+      #    decompose. Expose the parts separately (see `Engine::AnimationSet` row/col/flip_x).
+      #
+      # Allowed: an empty `[]` (idiomatic mutable-state seed), a frozen `[...].freeze`
+      # (allocated once), a parallel-assignment RHS (`a, b = c, d`, which the VM does
+      # not allocate), and the four sends the VM rewrites to `opt_newarray_send`.
+      #
+      # That last one is not a concession, it is a correction. `[a, b].min` compiles to
+      # a single `opt_newarray_send` instruction that reads the operands off the stack
+      # and never builds an Array — measured at 0 allocations over 200,000 calls, and
+      # visible in `RubyVM::InstructionSequence.compile("[a, b].min").disasm`. Flagging
+      # it cost real clarity: `Style/MinMaxComparison` asks for exactly this form, so
+      # code was being written around a conflict that does not exist.
+      #
+      # The optimisation is narrow, which is why OPTIMISED_SENDS is a list rather than a
+      # guess. `sum`, `first`, `last` and everything else still emit a plain `newarray`,
+      # and even `min` falls back to one the moment it is given a block or an argument
+      # (`[a, b].min { ... }`, `[a, b].min(1)`). Ranges never had an Array to build.
+      class NoNeedlessAllocation < RuboCop::Cop::Base
+        include HotPath
+
+        MSG_RECEIVER = 'Needless %{kind} allocation: this literal is built every call ' \
+                       'just to call `%{method}` on it — rewrite without the literal.'
+
+        OPTIMISED_SENDS = { min: 0, max: 0, hash: 0, include?: 1 }.freeze
+        MSG_HOT_PATH = 'Needless %{kind} allocation in a per-frame method: this literal ' \
+                       'is built every frame — build it once or expose the parts directly.'
+
+        def on_array(node)
+          check(node, 'array')
+        end
+
+        def on_irange(node)
+          check(node, 'range')
+        end
+
+        def on_erange(node)
+          check(node, 'range')
+        end
+
+        private
+
+        def check(node, kind)
+          return if allowed?(node)
+
+          send = receiving_send(node)
+          if send
+            add_offense(node, message: format(MSG_RECEIVER, kind: kind, method: send.method_name))
+          elsif in_hot_path?(node)
+            add_offense(node, message: format(MSG_HOT_PATH, kind: kind))
+          end
+        end
+
+        def allowed?(node)
+          return true if node.array_type? && node.children.empty?
+          return true if frozen?(node)
+          return true if node.parent&.masgn_type?
+          return true if optimised_send?(node)
+
+          false
+        end
+
+        def optimised_send?(node)
+          return false unless node.array_type?
+          return false if node.children.any?(&:splat_type?)
+
+          send = receiving_send(node)
+          return false if send.nil? || send.block_node
+
+          arity = OPTIMISED_SENDS[send.method_name]
+          !arity.nil? && send.arguments.size == arity
+        end
+
+        def frozen?(node)
+          send = receiving_send(node)
+          send&.method?(:freeze)
+        end
+
+        def receiving_send(node)
+          receiver = node
+          parent = node.parent
+          if parent&.begin_type? && parent.children.one?
+            receiver = parent
+            parent = parent.parent
+          end
+          return unless parent&.send_type? && parent.receiver == receiver
+
+          parent
+        end
+
+        def in_hot_path?(node)
+          enclosing = node.each_ancestor(:def).first
+          enclosing && hot_path_def?(enclosing)
+        end
+      end
+    end
+  end
+end

data/lib/rgame/rubocop/default.yml

@@ -0,0 +1,39 @@
+# The Game/ cops' defaults, for any project that loads the plugin. Each cop's
+# class comment, under cop/game/, says what it catches and why.
+#
+# Specs are test code: their draw stubs and fixture arrays are not a per-frame
+# path the game ships, so the two allocation guards skip them. The draw-space
+# and translation rules still apply there, because a spec that draws in the
+# wrong place describes a game that does too.
+#
+# The two layer cops are off by default. Each needs to be told which files form
+# a layer, and that is a fact about a project's layout rather than about rgame.
+# A project from `rgame new` enables NoCoreInEngineLayer for its nodes/ and spec/.
+
+Game/DrawInLocalSpace:
+  Description: A node's draw methods must not read its own position, which is already applied.
+  Enabled: true
+
+Game/NoInterpolationInHotPath:
+  Description: No string interpolation in a per-frame method.
+  Enabled: true
+  Exclude:
+    - '**/spec/**/*'
+
+Game/NoNeedlessAllocation:
+  Description: No throwaway Array or Range literal on a per-frame path.
+  Enabled: true
+  Exclude:
+    - '**/spec/**/*'
+
+Game/NoLiteralText:
+  Description: Draw text from a translation key, not a String literal.
+  Enabled: true
+
+Game/NoCoreInEngineLayer:
+  Description: Headless code must not name or require RGame::Core.
+  Enabled: false
+
+Game/NoEngineInCoreLayer:
+  Description: RGame::Core must not name or require the engine layer.
+  Enabled: false

data/lib/rgame/rubocop/plugin.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative '../version'
+
+module RuboCop
+  module Game
+    # Hands RuboCop the `Game/` cops' default configuration, in `default.yml`
+    # beside this file.
+    #
+    # A project loads it by path and class, from `.rubocop.yml`:
+    #
+    #   plugins:
+    #     - rgame/rubocop:
+    #         plugin_class_name: RuboCop::Game::Plugin
+    #
+    # The bare gem name would make RuboCop `require 'rgame'` and load the whole
+    # engine, compiled extension included, just to lint. `lint_roller` comes
+    # with every RuboCop that supports plugins, so the gem needs no dependency.
+    #
+    # It lives under `RuboCop` rather than `RGame`, like every other RuboCop
+    # extension, because RuboCop's process is the only one that loads it.
+    class Plugin < LintRoller::Plugin
+      def about
+        LintRoller::About.new(
+          name: 'rgame',
+          version: RGame::VERSION,
+          homepage: 'https://github.com/psuessenb/rgame',
+          description: 'Per-frame allocation, draw-space, layering and translation rules for rgame games.'
+        )
+      end
+
+      def supported?(context)
+        context.engine == :rubocop
+      end
+
+      def rules(_context)
+        LintRoller::Rules.new(
+          type: :path,
+          config_format: :rubocop,
+          value: File.join(__dir__, 'default.yml')
+        )
+      end
+    end
+  end
+end

data/lib/rgame/rubocop.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require 'lint_roller'
+
+require_relative 'rubocop/plugin'
+require_relative 'rubocop/cop/game/draw_in_local_space'
+require_relative 'rubocop/cop/game/no_core_in_engine_layer'
+require_relative 'rubocop/cop/game/no_engine_in_core_layer'
+require_relative 'rubocop/cop/game/no_interpolation_in_hot_path'
+require_relative 'rubocop/cop/game/no_literal_text'
+require_relative 'rubocop/cop/game/no_needless_allocation'

data/lib/rgame/util/color.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'rgame/util_ext'
+
+module RGame
+  module Util
+    class Color
+      RED = new(255, 0, 0)
+      GREEN = new(0, 255, 0)
+      BLUE = new(0, 0, 255)
+      YELLOW = new(255, 255, 0)
+      CYAN = new(0, 255, 255)
+      MAGENTA = new(255, 0, 255)
+      ORANGE = new(255, 165, 0)
+      PURPLE = new(128, 0, 128)
+      BROWN = new(139, 69, 19)
+      PINK = new(255, 192, 203)
+      GRAY = new(128, 128, 128)
+      LIGHT_GRAY = new(192, 192, 192)
+      DARK_GRAY = new(64, 64, 64)
+    end
+  end
+end

data/lib/rgame/util/controls.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+module RGame
+  module Util
+    # The vocabulary of physical inputs: which integer means "the left arrow
+    # key", "the A button", "the left stick's X axis", "player 2's controller".
+    #
+    # These are values — plain integers with no window, GPU or OS handle behind
+    # them — so they live in Util rather than Core. That is what lets the engine
+    # layer and a game's own configuration name a physical input without
+    # touching RGame::Core, which they may not do:
+    #
+    #   controls = RGame::Util::Controls
+    #   map = RGame::Engine::InputMap.default.merge(
+    #     fire: { buttons: [controls::KEY_SPACE, controls::PAD_A] }
+    #   )
+    #
+    # This module is the **vocabulary** only. What an id *means* to a game — the
+    # binding table — is RGame::Engine::InputMap, one per player, because two
+    # players share a game's actions but not the buttons that trigger them.
+    #
+    # The same numbers exist as `#define`s in
+    # ext/rgame_core/include/rgame/core.h, because the C engine and the
+    # standalone binary need them too and cannot see Ruby. Two definitions means
+    # a drift risk, so it is checked: the C side is tied to SDL's own scancodes
+    # by _Static_assert at compile time, and spec/rgame/util/controls_spec.rb
+    # parses that header and compares every value here against it.
+    module Controls
+      KEY_A = 4
+      KEY_B = 5
+      KEY_C = 6
+      KEY_D = 7
+      KEY_E = 8
+      KEY_F = 9
+      KEY_G = 10
+      KEY_H = 11
+      KEY_I = 12
+      KEY_J = 13
+      KEY_K = 14
+      KEY_L = 15
+      KEY_M = 16
+      KEY_N = 17
+      KEY_O = 18
+      KEY_P = 19
+      KEY_Q = 20
+      KEY_R = 21
+      KEY_S = 22
+      KEY_T = 23
+      KEY_U = 24
+      KEY_V = 25
+      KEY_W = 26
+      KEY_X = 27
+      KEY_Y = 28
+      KEY_Z = 29
+
+      KEY_1 = 30
+      KEY_2 = 31
+      KEY_3 = 32
+      KEY_4 = 33
+      KEY_5 = 34
+      KEY_6 = 35
+      KEY_7 = 36
+      KEY_8 = 37
+      KEY_9 = 38
+      KEY_0 = 39
+
+      KEY_RETURN = 40
+      KEY_ESCAPE = 41
+      KEY_BACKSPACE = 42
+      KEY_TAB = 43
+      KEY_SPACE = 44
+
+      KEY_MINUS = 45
+      KEY_EQUALS = 46
+      KEY_LEFTBRACKET = 47
+      KEY_RIGHTBRACKET = 48
+      KEY_BACKSLASH = 49
+      KEY_SEMICOLON = 51
+      KEY_APOSTROPHE = 52
+      KEY_GRAVE = 53
+      KEY_COMMA = 54
+      KEY_PERIOD = 55
+      KEY_SLASH = 56
+
+      KEY_CAPSLOCK = 57
+      KEY_F1 = 58
+      KEY_F2 = 59
+      KEY_F3 = 60
+      KEY_F4 = 61
+      KEY_F5 = 62
+      KEY_F6 = 63
+      KEY_F7 = 64
+      KEY_F8 = 65
+      KEY_F9 = 66
+      KEY_F10 = 67
+      KEY_F11 = 68
+      KEY_F12 = 69
+
+      KEY_INSERT = 73
+      KEY_HOME = 74
+      KEY_PAGEUP = 75
+      KEY_DELETE = 76
+      KEY_END = 77
+      KEY_PAGEDOWN = 78
+
+      KEY_RIGHT = 79
+      KEY_LEFT = 80
+      KEY_DOWN = 81
+      KEY_UP = 82
+
+      KEY_LCTRL = 224
+      KEY_LSHIFT = 225
+      KEY_LALT = 226
+      KEY_RCTRL = 228
+      KEY_RSHIFT = 229
+      KEY_RALT = 230
+
+      BUTTON_GAMEPAD_FIRST = 0x1000
+
+      PAD_A = 4096
+      PAD_B = 4097
+      PAD_X = 4098
+      PAD_Y = 4099
+      PAD_BACK = 4100
+      PAD_GUIDE = 4101
+      PAD_START = 4102
+      PAD_LEFT_STICK = 4103
+      PAD_RIGHT_STICK = 4104
+      PAD_LEFT_SHOULDER = 4105
+      PAD_RIGHT_SHOULDER = 4106
+      PAD_DPAD_UP = 4107
+      PAD_DPAD_DOWN = 4108
+      PAD_DPAD_LEFT = 4109
+      PAD_DPAD_RIGHT = 4110
+      PAD_MISC1 = 4111
+      PAD_PADDLE1 = 4112
+      PAD_PADDLE2 = 4113
+      PAD_PADDLE3 = 4114
+      PAD_PADDLE4 = 4115
+      PAD_TOUCHPAD = 4116
+
+      AXIS_LEFT_X = 0
+      AXIS_LEFT_Y = 1
+      AXIS_RIGHT_X = 2
+      AXIS_RIGHT_Y = 3
+      AXIS_TRIGGER_LEFT = 4
+      AXIS_TRIGGER_RIGHT = 5
+
+      KEYBOARD = 0
+      GAMEPAD_FIRST = 1
+      MAX_GAMEPADS = 4
+
+      # The device id for a player slot: gamepad(0) is the first controller.
+      def self.gamepad(slot) = GAMEPAD_FIRST + slot
+
+      # Is this *device* a controller rather than the keyboard? What a game asks
+      # when the answer changes what it shows the player — the prompt for an
+      # action is a key cap or a face button depending on what they last used.
+      def self.gamepad?(device) = device >= GAMEPAD_FIRST
+
+      # Is this *button* one a controller has rather than one a keyboard has?
+      # The mirror of the question above, on the other id space, and the pair is
+      # what lets a caller keep the two apart: an action bound to both lists its
+      # keys and its pad buttons together, and only a device can say which half
+      # of that list applies right now.
+      def self.pad_button?(id) = id >= BUTTON_GAMEPAD_FIRST
+    end
+  end
+end

data/lib/rgame/util/route_search.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require 'rgame/util_ext'
+
+module RGame
+  module Util
+    # Connected regions and A* routes over a SolidGrid, in C. The search reads its grid and
+    # never writes it, and keeps it alive; any number of searches may read one grid.
+    #
+    # 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. Routes are cells, `[[col, row], ...]`, start and goal
+    # included — or nil when either end is solid, outside the grid, or in another region.
+    #
+    # Regions are labelled on the first ask after the grid's #revision moves, so a goal in
+    # another region is a lookup rather than a search that exhausts the map, and it stays
+    # right when the grid changes. Everything else a search keeps between queries is reused,
+    # so a repeated query allocates nothing but its result. One search is therefore not safe
+    # to use from two threads at once; two searches over one grid are.
+    #
+    #   grid = RGame::Util::SolidGrid.build(8, 3) { |col, row| col == 3 && row < 2 }
+    #   search = RGame::Util::RouteSearch.new(grid)
+    #   search.find(0, 0, 7, 0)   # => [[0, 0], [1, 1], [2, 2], [3, 2], [4, 2], [5, 1], [6, 0], [7, 0]]
+    class RouteSearch
+    end
+  end
+end

data/lib/rgame/util/save_file.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'fileutils'
+
+module RGame
+  module Util
+    # A game's saved state, as one JSON file.
+    #
+    #   save = SaveFile.new('slot1.json', game: 'sheepdog')
+    #   save.write(dog: [120, 80], sheep: [[40, 40], [90, 30]])
+    #   save.read                     # => { dog: [120, 80], sheep: [...] }
+    #   save.read.fetch(:dog, nil)    # => nil when there is no save yet
+    #
+    # It holds no open handle — it opens, reads or writes, and closes — which is
+    # why this is `Util` rather than `Core` (see CLAUDE.md, "Value objects go in
+    # Util"). JSON comes from the standard library, so nothing here adds a
+    # runtime dependency.
+    #
+    # ## Reading never raises
+    #
+    # `read` answers with the default for a file that is missing, empty,
+    # truncated, not JSON, or JSON that is not an object. That is deliberate and
+    # it is the whole reason this class exists rather than three lines of
+    # `JSON.parse(File.read(...))` at a call site.
+    #
+    # A save file is the one input a game has that it did not produce this run.
+    # It survives crashes, disk-full, a killed process mid-write, an editor, and
+    # a copy from someone else's machine. A game that raises on any of those is
+    # a game that cannot be started again, and the player's only fix is to find
+    # and delete a file they were never told about. Losing a save is bad;
+    # refusing to launch is worse.
+    #
+    # **Writing still raises.** A read failure has a sensible answer — "there is
+    # no save" — and a write failure does not: silently discarding the player's
+    # progress is the failure that gets noticed hours later. A caller that wants
+    # to survive a full disk can rescue; it cannot un-swallow an exception this
+    # class never raised.
+    #
+    # ## Writing is atomic
+    #
+    # `write` writes a temporary file beside the target and renames it over the
+    # top. `File.rename` within one directory is atomic on every platform this
+    # engine supports, so a save is either the old one or the new one and never
+    # half of each.
+    #
+    # This matters more than it sounds: the moment a game most wants to save is
+    # on the way out, which is also the moment it is most likely to be killed.
+    # A plain `File.write` truncates first and fills in after, so a crash in
+    # between leaves a zero-byte file where the player's afternoon used to be.
+    class SaveFile
+      # Where saves go, per platform, following each one's own convention rather
+      # than dropping a dotfile in the home directory:
+      #
+      #   Linux    $XDG_DATA_HOME/<game>, or ~/.local/share/<game>
+      #   macOS    ~/Library/Application Support/<game>
+      #   Windows  %APPDATA%\<game>
+      #
+      # `game` names the directory, so two games do not share a save.
+      def self.directory(game)
+        case RbConfig::CONFIG['host_os']
+        when /darwin/ then File.join(Dir.home, 'Library', 'Application Support', game)
+        when /mswin|mingw|cygwin/ then File.join(ENV.fetch('APPDATA', Dir.home), game)
+        else File.join(ENV.fetch('XDG_DATA_HOME', File.join(Dir.home, '.local', 'share')), game)
+        end
+      end
+
+      attr_reader :path
+
+      # `name` is a file name inside the game's save directory; pass `dir:` to
+      # put it somewhere else, which is what a spec does.
+      def initialize(name, game: 'rgame', dir: nil)
+        @path = File.join(dir || SaveFile.directory(game), name)
+      end
+
+      def exist? = File.exist?(@path)
+
+      # The saved state, or `default` if there is nothing usable to read. Keys
+      # come back as Symbols, so a game writes and reads the same shape.
+      def read(default = {})
+        parsed = JSON.parse(File.read(@path), symbolize_names: true)
+        parsed.is_a?(Hash) ? parsed : default
+      rescue Errno::ENOENT, Errno::EACCES, Errno::EISDIR, JSON::ParserError
+        default
+      end
+
+      # Writes `state` as JSON, atomically. Creates the directory if it is not
+      # there — a first save on a fresh machine is the normal case, not an error.
+      def write(state)
+        FileUtils.mkdir_p(File.dirname(@path))
+        temporary = "#{@path}.#{Process.pid}.tmp"
+        File.write(temporary, JSON.pretty_generate(state))
+        File.rename(temporary, @path)
+        self
+      end
+
+      # Removes the save, and says nothing if there was not one. "Delete my
+      # save" and "there was no save" leave the player in the same place.
+      def delete
+        File.unlink(@path)
+        self
+      rescue Errno::ENOENT
+        self
+      end
+    end
+  end
+end

data/lib/rgame/util/solid_grid.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require 'rgame/util_ext'
+
+module RGame
+  module Util
+    # Which cells of a tile grid are solid: one byte a cell, in C. A value with no handle
+    # behind it, which is why it lives in Util and why the engine layer may own one.
+    #
+    # It is the one store a tile world's solidity lives in. The blockers that stop a walker
+    # and the RouteSearch that plans one both read it, so they cannot disagree about a wall,
+    # and a cell changed with #set_solid is changed for both at once.
+    #
+    # #revision counts the changes: it moves on a #set_solid that changes a cell and on no
+    # other, so anything derived from the cells — a search's region labels — can tell
+    # whether it is stale without being told.
+    #
+    # Coordinates are Integers, and anything else is a TypeError. Outside the grid is open,
+    # including an Integer too large to be inside any grid.
+    #
+    #   grid = RGame::Util::SolidGrid.build(8, 3) { |col, _row| col == 3 }
+    #   grid.solid?(3, 1)    # => true
+    #   grid.solid?(-1, 0)   # => false
+    #   grid.set_solid(3, 1, false)
+    #   grid.revision        # => 1
+    class SolidGrid
+      # A grid with each cell's solidity read from the block, once per cell, row by row.
+      def self.build(width, height)
+        grid = new(width, height)
+        height.times do |row|
+          width.times { |col| grid.set_solid(col, row, true) if yield(col, row) }
+        end
+        grid
+      end
+    end
+  end
+end

data/lib/rgame/util/tensor.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require 'rgame/util_ext'

data/lib/rgame/util/tile_sweep.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require 'rgame/util_ext'
+
+module RGame
+  module Util
+    # An axis-aligned box against the solid tiles of a SolidGrid, in C. It reads its grid and
+    # never writes it, and keeps it alive; any number of sweeps may read one grid, so a change
+    # made with SolidGrid#set_solid is seen by all of them at once.
+    #
+    # It answers two questions with one piece of arithmetic, so they cannot disagree:
+    #
+    # - **#resolve_x / #resolve_y** — where the box's left (top) edge lands moving dx (dy). A
+    #   step that would enter a solid tile snaps the box flush against that tile's edge. Each
+    #   axis is resolved on its own. The step is assumed smaller than a tile; a longer one can
+    #   pass through a tile without seeing it.
+    # - **#travel?** — whether the box can move by (dx, dy) without any resolve along the way
+    #   falling short of where it was heading. The box is swept in overlapping windows half a
+    #   tile long, a quarter tile apart, each resolved X-then-Y and Y-then-X, which makes the
+    #   answer sound for a walker that resolves its own steps and steps less than a quarter tile
+    #   at a time.
+    #
+    # Boxes are given by their top-left corner and size, in pixels. Outside the grid is open.
+    # Results are Floats. A coordinate that is not a number is a TypeError; a non-finite one is
+    # a FloatDomainError, except in a resolve with no movement, which returns the box where it
+    # is.
+    #
+    #   grid = RGame::Util::SolidGrid.build(20, 15) { |col, _row| col == 5 }  # a wall at x 80..96
+    #   sweep = RGame::Util::TileSweep.new(grid, 16, 16)
+    #   sweep.resolve_x(58.0, 32.0, 12, 6, 14.0)   # => 68.0, flush against the wall
+    #   sweep.travel?(10.0, 32.0, 12, 6, 50.0, 0)  # => true
+    #   sweep.travel?(10.0, 32.0, 12, 6, 90.0, 0)  # => false
+    class TileSweep
+    end
+  end
+end