rgame 0.2.0 → 0.3.0

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

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require_relative 'layer_boundary'
+
+module RuboCop
+  module Cop
+    module Game
+      # `RGame::Core` must never name `RGame::Engine`. The mirror of
+      # `NoCoreInEngineLayer`, and the more easily broken of the two.
+      #
+      # Engine is built *on top of* Core, so Core should not know it exists.
+      # Core owns windows, textures and sound devices; Engine owns scene
+      # concepts. A Core class that reaches upward makes the lower layer
+      # unusable without the higher one, and inverts a dependency that the whole
+      # three-layer split exists to keep pointing one way.
+      #
+      # Where Core genuinely needs something Engine has — a tile map's grid, say
+      # — it takes the object and calls it by method name, exactly as the engine
+      # layer does with a renderer. The one place allowed to name both sides is
+      # the glue class directly under `RGame`, which is what a glue class is
+      # for.
+      #
+      # Unlike its mirror, nothing catches this at runtime: loading Engine into
+      # a Core spec would work fine and the inversion would go unnoticed until
+      # someone tried to use Core on its own. This cop is the only guard.
+      #
+      # Both spellings are flagged — `RGame::Engine` and the bare `Engine` the
+      # layer still has before it is ported — because the interim is exactly
+      # when the mistake gets made.
+      #
+      # @example
+      #   # bad — Core parsing a file format Engine owns
+      #   def self.load(app, path)
+      #     map = Engine::TileMap.parse(File.read(path))
+      #     new(app, map)
+      #   end
+      #
+      #   # bad — a require, in either spelling
+      #   require 'rgame/engine'
+      #
+      #   # good — hand Core the parsed thing and call it by name
+      #   def initialize(map, tiles)
+      #     @columns = map.width
+      #   end
+      class NoEngineInCoreLayer < RuboCop::Cop::Base
+        include LayerBoundary
+
+        MSG = 'RGame::Core must not name `%{name}`; take the object and call it ' \
+              'by method name, and let the glue layer wire the two together.'
+        MSG_REQUIRE = 'RGame::Core must not require `%{path}` — Engine is built on ' \
+                      'top of Core, not the other way round.'
+
+        PREFIXES = [%w[RGame Engine], %w[Engine]].freeze
+        RESTRICTED_REQUIRE = %r{(\A|/)engine(/|\z)}
+
+        # @!method engine_require(node)
+        def_node_matcher :engine_require, <<~PATTERN
+          (send nil? {:require :require_relative} (str $_))
+        PATTERN
+
+        def on_send(node)
+          engine_require(node) do |path|
+            next unless RESTRICTED_REQUIRE.match?(path.to_s.delete_prefix('./'))
+
+            add_offense(node, message: format(MSG_REQUIRE, path: path))
+          end
+        end
+
+        def on_const(node)
+          return unless opens_namespace?(node, PREFIXES)
+
+          add_offense(node, message: format(MSG, name: matched_prefix(node).join('::')))
+        end
+
+        private
+
+        def matched_prefix(node)
+          path = const_path(node)
+          PREFIXES.find { |prefix| path.first(prefix.length) == prefix }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative 'hot_path'
+
+module RuboCop
+  module Cop
+    module Game
+      # Disallow string interpolation inside per-frame methods — the engine's lifecycle
+      # hooks (`update`/`control`/`draw`/`on_update`/`on_draw`/`on_control`) and any method
+      # tagged `# hot-path`.
+      #
+      # These run every frame (~60/s), and string interpolation builds a brand-new
+      # `String` each time it is evaluated (the `frozen_string_literal` pragma freezes
+      # *literals*, not interpolated results). So a `"Score: #{n}"` here is a per-frame
+      # allocation. Build the string once — on construction, or when the value changes
+      # (see `Engine::Text`) — and draw the cached copy.
+      #
+      # @example
+      #   # bad
+      #   def draw(renderer)
+      #     renderer.text("Score: #{@score}", 10, 10)
+      #   end
+      #
+      #   # good  (rebuilt only when @score changes)
+      #   def draw(renderer)
+      #     renderer.text(@score_label, 10, 10)
+      #   end
+      class NoInterpolationInHotPath < RuboCop::Cop::Base
+        include HotPath
+
+        MSG = 'Avoid string interpolation in a per-frame method: it allocates a String ' \
+              'every frame. Build the string once (on change) and use the cached value.'
+
+        def on_def(node)
+          return unless hot_path_def?(node)
+
+          node.each_descendant(:dstr) do |dstr|
+            add_offense(dstr) if interpolated?(dstr)
+          end
+        end
+
+        private
+
+        def interpolated?(dstr)
+          dstr.children.any?(&:begin_type?)
+        end
+      end
+    end
+  end
+end

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

@@ -1,27 +1,23 @@
 # frozen_string_literal: true
 
-# RGame::Util::Color is implemented in C — see ext/rgame_util/color_ext.c for
-# the Ruby binding and ext/rgame_util/color.c for the packing arithmetic.
-#
-#   Color = RGame::Util::Color
-#   Color.new(255, 128, 0)        # r, g, b, a defaults to 255
-#   Color.rgba(255, 128, 0, 200)  # the same thing, named
-#   Color.from_packed(0xFF8000FF) # 0xRRGGBBAA
-#   Color::WHITE                  # also BLACK and TRANSPARENT
-#
-#   c.r; c.g; c.b; c.a            # => Integer, 0..255
-#   c.packed                      # => Integer, 0xRRGGBBAA
-#
-# Instances are frozen and compare by value, so a Color works as a Hash key and
-# can be shared without anyone tinting it out from under its other holders.
-#
-# Every draw call accepts a colour as nil (white), [r, g, b], [r, g, b, a] or a
-# Color; `Color.coerce` is the single place that conversion happens.
-#
-# A colour is a *value* — no window, no GPU handle — so it lives in Util rather
-# than Core. That is what lets the engine layer hold one as an attribute; see
-# CLAUDE.md, "Value objects go in Util; only handle-owners go in Core".
-#
-# It loads from lib/rgame/util_ext.so, which `make ext-util` copies out of
-# ext/rgame_util/.
 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

@@ -26,17 +26,6 @@ module RGame
     # 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
-      # --- Keyboard. Values are SDL scancodes, which name a physical *position*
-      # rather than a letter: KEY_A is the key marked A on a QWERTY board and Q
-      # on AZERTY. A game rebinding controls shows the player what their layout
-      # calls it; the engine only ever compares numbers. ---
-      #
-      # The set is what a Western keyboard can be relied on to have. No numpad
-      # (most laptops have none), no GUI/Windows/Command key, no print-screen
-      # cluster, and nothing whose position depends on the layout.
-
-      # Letters. Scancodes are physical *positions*, so KEY_A is the key marked A on
-      # a QWERTY board and Q on AZERTY.
       KEY_A = 4
       KEY_B = 5
       KEY_C = 6
@@ -64,7 +53,6 @@ module RGame
       KEY_Y = 28
       KEY_Z = 29
 
-      # Digits along the top row.
       KEY_1 = 30
       KEY_2 = 31
       KEY_3 = 32
@@ -76,14 +64,12 @@ module RGame
       KEY_9 = 38
       KEY_0 = 39
 
-      # Editing and whitespace.
       KEY_RETURN = 40
       KEY_ESCAPE = 41
       KEY_BACKSPACE = 42
       KEY_TAB = 43
       KEY_SPACE = 44
 
-      # Punctuation, by position on a US board.
       KEY_MINUS = 45
       KEY_EQUALS = 46
       KEY_LEFTBRACKET = 47
@@ -96,7 +82,6 @@ module RGame
       KEY_PERIOD = 55
       KEY_SLASH = 56
 
-      # Function row and caps lock.
       KEY_CAPSLOCK = 57
       KEY_F1 = 58
       KEY_F2 = 59
@@ -111,7 +96,6 @@ module RGame
       KEY_F11 = 68
       KEY_F12 = 69
 
-      # The navigation cluster.
       KEY_INSERT = 73
       KEY_HOME = 74
       KEY_PAGEUP = 75
@@ -119,14 +103,11 @@ module RGame
       KEY_END = 77
       KEY_PAGEDOWN = 78
 
-      # Arrows.
       KEY_RIGHT = 79
       KEY_LEFT = 80
       KEY_DOWN = 81
       KEY_UP = 82
 
-      # Modifiers. No GUI key: that is Windows on a PC and Command on a Mac, which
-      # is exactly the platform-specific territory this list stays out of.
       KEY_LCTRL = 224
       KEY_LSHIFT = 225
       KEY_LALT = 226
@@ -134,10 +115,8 @@ module RGame
       KEY_RSHIFT = 229
       KEY_RALT = 230
 
-      # --- Gamepad buttons. The gamepad range plus SDL's own controller button
-      # number. The first fifteen are on every controller; MISC1, the paddles
-      # and TOUCHPAD are hardware the id space describes but most pads do not
-      # have, and read as never pressed on one that does not. ---
+      BUTTON_GAMEPAD_FIRST = 0x1000
+
       PAD_A = 4096
       PAD_B = 4097
       PAD_X = 4098
@@ -160,9 +139,6 @@ module RGame
       PAD_PADDLE4 = 4115
       PAD_TOUCHPAD = 4116
 
-      # --- Analog axes. Their own small space: they are float-valued and read
-      # through a different call, so folding them into the button space would
-      # only invite asking for an axis as if it were a button. ---
       AXIS_LEFT_X = 0
       AXIS_LEFT_Y = 1
       AXIS_RIGHT_X = 2
@@ -170,14 +146,24 @@ module RGame
       AXIS_TRIGGER_LEFT = 4
       AXIS_TRIGGER_RIGHT = 5
 
-      # --- Devices. The keyboard is 0 so single-player code can leave it out;
-      # gamepads follow, one per player slot. ---
       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