rgame 0.1.0 → 0.3.0

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

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Game
+      # A node's draw methods must not read the node's own position — in either
+      # space, because both are already applied by the time they run.
+      #
+      # `Node2D#draw` pushes the node's transform onto the renderer and runs
+      # everything below it inside that, so within `on_draw` the origin *is* the
+      # node, turned the way the node is turned. Drawing is done at (0, 0), or at
+      # an offset from it that means something to the node itself.
+      #
+      # Both spellings of "where am I" are therefore wrong there, and differ only
+      # in how far off they put the result:
+      #
+      # - `world_x` is where the node sits on the map, which every ancestor's
+      #   transform — the camera's included — has already contributed to. Passing
+      #   it applies the whole chain twice.
+      # - `x` is the node's offset inside its parent, which its own transform has
+      #   already applied. Passing it offsets by that much a second time.
+      #
+      # Both are silent: they draw, they just draw in the wrong place, and only
+      # once something is nested under an offset or rotated parent — which is
+      # exactly the case a spec at the origin cannot see.
+      #
+      # A **component** drawing for its node is on this path too, and asks the
+      # node by name: `node.world_x` for a cull test is a different object's
+      # coordinate and is not flagged. Only a bare, receiverless read of the
+      # node's own transform is.
+      #
+      # `width` and `height` are not positions and are ordinary here — a node
+      # drawing its own box says `renderer.rect(0, 0, width, height)`.
+      #
+      # @example
+      #   # bad — the traversal has already placed the renderer on this node
+      #   def on_draw(renderer, _view)
+      #     renderer.rect(world_x, world_y, width, height)
+      #   end
+      #
+      #   # bad — same mistake, a smaller distance
+      #   def on_draw(renderer, _view)
+      #     renderer.rect(x, y, width, height)
+      #   end
+      #
+      #   # good — its own origin
+      #   def on_draw(renderer, _view)
+      #     renderer.rect(0, 0, width, height)
+      #   end
+      #
+      #   # good — a component culling against the camera, in world space, by name
+      #   def draw(renderer, view)
+      #     return if culled?(view, node.world_x, node.world_y, node.width, node.height)
+      #
+      #     renderer.image(@id, 0, 0)
+      #   end
+      class DrawInLocalSpace < RuboCop::Cop::Base
+        MSG = 'Draw in local space: `%{name}` is already applied by the time ' \
+              '`%{method}` runs, so passing it places this %{distance} a second ' \
+              'time. Draw at your own origin (0, 0), or an offset from it.'
+
+        METHODS = %i[draw on_draw _draw_content draw_children].freeze
+
+        RELATIVE = %i[x y angle].freeze
+        WORLD = %i[world_x world_y world_angle].freeze
+        IVARS = { :@rel_x => :x, :@rel_y => :y, :@rel_angle => :angle,
+                  :@world_x => :world_x, :@world_y => :world_y,
+                  :@world_angle => :world_angle }.freeze
+
+        def on_def(node)
+          return unless METHODS.include?(node.method_name)
+
+          node.each_descendant(:ivar, :send) do |read|
+            name = own_transform_read(read)
+            next unless name
+
+            add_offense(read, message: format(MSG, name: name, method: node.method_name,
+                                                   distance: distance_for(name)))
+          end
+        end
+
+        private
+
+        def own_transform_read(node)
+          if node.ivar_type?
+            IVARS[node.children.first]
+          elsif self_read?(node)
+            name = node.method_name
+            name if RELATIVE.include?(name) || WORLD.include?(name)
+          end
+        end
+
+        def self_read?(node)
+          node.send_type? && node.receiver.nil? && node.arguments.empty? && !node.block_literal?
+        end
+
+        def distance_for(name)
+          WORLD.include?(name) ? 'on the map' : 'inside its parent'
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Game
+      # Shared definition of the per-frame "hot path" for the allocation-guard cops.
+      #
+      # The hot path is the set of methods that run every frame: the engine's six
+      # lifecycle hooks, plus any method an author opts into with a `# hot-path` magic
+      # comment on the line directly above its `def`. The opt-in covers per-frame
+      # *helpers* the lifecycle methods call, where an allocation is just as costly but
+      # the method name alone can't reveal it.
+      module HotPath
+        METHODS = %i[update control draw draw_children _draw_content
+                     on_update on_draw on_control].freeze
+
+        # True for a `def` that runs per frame: a lifecycle method by name, or one tagged
+        # `# hot-path` on the line directly above it.
+        def hot_path_def?(node)
+          return false unless node.def_type?
+
+          METHODS.include?(node.method_name) || hot_path_tagged?(node)
+        end
+
+        private
+
+        def hot_path_tagged?(node)
+          line_above = node.source_range.first_line - 1
+          processed_source.comments.any? do |comment|
+            comment.location.line == line_above && comment.text.match?(/\A#\s*hot-path\b/)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Game
+      # Shared by the two cops that police a layer boundary —
+      # `NoCoreInEngineLayer` and `NoEngineInCoreLayer`. They are mirror images:
+      # each forbids one namespace inside the other's files, and the only thing
+      # that differs is which namespace and which message.
+      #
+      # Kept in one place because the interesting part is not the comparison but
+      # the *walk*: `RGame::Core::Renderer` is three nested `const` nodes, and a
+      # naive check reports the same reference three times. Getting that right
+      # once beats getting it right twice and then fixing only one of them.
+      module LayerBoundary
+        private
+
+        def const_path(node)
+          names = []
+          current = node
+          while current&.const_type?
+            names.unshift(current.short_name.to_s)
+            current = current.namespace
+          end
+          names
+        end
+
+        def opens_namespace?(node, prefixes)
+          return false unless under?(node, prefixes)
+
+          !(node.parent&.const_type? && under?(node.parent, prefixes))
+        end
+
+        def under?(node, prefixes)
+          return false unless node.const_type?
+
+          path = const_path(node)
+          prefixes.any? { |prefix| path.first(prefix.length) == prefix }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require_relative 'layer_boundary'
+
+module RuboCop
+  module Cop
+    module Game
+      # The engine layer must never name `RGame::Core`.
+      #
+      # `RGame::Engine` holds the game concepts — scene tree, signals, sprites,
+      # tile maps — and its whole value is that it can be specified with no
+      # window, no GPU and no clock. It reaches the platform only through
+      # objects handed to it: a node's `draw` receives a `renderer` and calls
+      # methods on it by name, never storing it and never asking its class.
+      #
+      # Engine specs enforce this at runtime by simply never loading
+      # `rgame/core`, so a stray reference raises `NameError`. That only catches
+      # code a test run actually executes, though — this cop covers the
+      # branches it doesn't reach.
+      #
+      # A game has the same line: its nodes and specs run headless, and only its
+      # glue class loads the window. So `require 'rgame/game'` is refused too,
+      # since it loads everything `rgame/core` does.
+      #
+      # The short spelling `Core::Image` is flagged only inside `module RGame`,
+      # the one place it resolves to `RGame::Core`. Anywhere else it names the
+      # project's own `Core`.
+      #
+      # `RGame::Util` is fine anywhere: those are shareable value types with no
+      # OS handle behind them, which is exactly why they live in Util.
+      #
+      # @example
+      #   # bad — names the class
+      #   def draw(renderer)
+      #     RGame::Core::Renderer.new
+      #   end
+      #
+      #   # bad — the same thing, resolved through the enclosing RGame
+      #   module RGame
+      #     Core::Image.new(app, path)
+      #   end
+      #
+      #   # bad — a require pulls SDL into the process
+      #   require 'rgame/core'
+      #
+      #   # good — duck-typed against whatever it is handed
+      #   def draw(renderer, _view)
+      #     renderer.sprite(:hero, 0, 0, 0, 0)
+      #   end
+      #
+      #   # good — Util types may be held as attributes
+      #   @grid = RGame::Util::Tensor.new(w, h, d)
+      class NoCoreInEngineLayer < RuboCop::Cop::Base
+        include LayerBoundary
+
+        MSG = 'Headless code must not name `RGame::Core`; receive the object ' \
+              'and call it by method name instead.'
+        MSG_REQUIRE = 'Headless code must not require `%{path}` — that loads ' \
+                      'SDL/OpenGL and breaks headless specs.'
+
+        QUALIFIED = [%w[RGame Core]].freeze
+        WITHIN_RGAME = [%w[RGame Core], %w[Core]].freeze
+        RESTRICTED_REQUIRE = %r{\Argame/(core|game)(/|\z)|\Argame/core_ext\z}
+
+        # `require "rgame/core"` and friends.
+        # @!method core_require(node)
+        def_node_matcher :core_require, <<~PATTERN
+          (send nil? {:require :require_relative} (str $_))
+        PATTERN
+
+        def on_send(node)
+          core_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
+
+        # Any constant path under RGame::Core. The walk, and reporting one
+        # offence per written reference rather than one per path segment, is in
+        # LayerBoundary — shared with this cop's mirror.
+        def on_const(node)
+          add_offense(node) if opens_namespace?(node, prefixes_for(node))
+        end
+
+        private
+
+        def prefixes_for(node)
+          within_rgame?(node) ? WITHIN_RGAME : QUALIFIED
+        end
+
+        def within_rgame?(node)
+          node.each_ancestor(:module, :class).any? do |scope|
+            const_path(scope.identifier).first == 'RGame'
+          end
+        end
+      end
+    end
+  end
+end

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'