rgame 0.4.0-x86_64-linux-gnu

data/lib/rgame/game.rb

@@ -0,0 +1,271 @@
+# frozen_string_literal: true
+
+require_relative 'boot'
+require_relative 'core'
+require_relative 'engine'
+
+module RGame
+  # The entry point of a game, and the one class that knows both halves.
+  #
+  #   class HelloScene < RGame::Engine::Node2D
+  #     def on_draw(renderer) = renderer.text('Hello world!', 250, 200)
+  #   end
+  #
+  #   RGame::Game.new(root: HelloScene.new, caption: 'Hello').start
+  #
+  # A complete game is a root node plus that. `Game` assembles the pieces
+  # around it — the window and its loop, the renderer, the asset manager, the
+  # sound device, the input mapper, the debug overlay — and drives the root
+  # node once per tick.
+  #
+  # ## Why this class is allowed to name both layers
+  #
+  # `RGame::Engine` holds game concepts and may not name `RGame::Core`;
+  # `RGame::Core` owns handles and may not know Engine exists. Two RuboCop cops
+  # say so. Something still has to introduce them, and **this is that
+  # something** — see CLAUDE.md, "The rule points both ways". Keeping the
+  # introduction to one file is what makes the rule checkable everywhere else,
+  # so wiring belongs here and only here.
+  #
+  # The tile-map loader is the clearest case. Parsing a `.tmx` is Engine's job
+  # and drawing one is Core's, and neither may call the other, so `Game`
+  # installs the loader that joins them.
+  #
+  # ## The loop
+  #
+  # `Game` is an `App`, so it inherits the fixed-timestep loop rather than
+  # running one. Its hooks do three things: sample input once per frame, drive
+  # the root once per tick, and draw. Nothing here counts steps or measures
+  # time — `frame_loop.c` does that, and `update` is called once per whole tick.
+  class Game < RGame::Core::App
+    Controls = RGame::Util::Controls
+
+    WIDTH = 640
+    HEIGHT = 480
+
+    attr_reader :root, :renderer
+
+    # `input_map:` is what physical inputs mean — one entry per action, naming
+    # ids from RGame::Util::Controls. It is merged over the universal UI set, so
+    # `ui_confirm` and friends work whether or not a game declares them, and it
+    # defaults to RGame::Engine::InputMap::DEFAULT_ACTIONS, so a game wanting
+    # eight-way movement and a fire button declares nothing.
+    #
+    # `device:` is which device drives it — the keyboard, or
+    # `Controls.gamepad(slot)` for a controller.
+    #
+    # `input:` overrides the input backend. It exists so a harness can drive a
+    # game from a script instead of from hardware — see
+    # tools/drive_test_project.rb, and CLAUDE.md's "The test projects are the
+    # acceptance test for wiring", which is why driving one has to be possible
+    # at all. A game passes nothing and gets the real thing.
+    # `players:` is how many seats the game has, and therefore the most people
+    # who can play it. Player 0 starts on `device:`; the rest start empty and
+    # are filled when someone uses a controller — see RGame::Engine::Players for
+    # why that is a press rather than a plug.
+    # `fullscreen:` opens the window fullscreen rather than switching after it is
+    # already up, so a game that always runs fullscreen never flashes a windowed
+    # frame at startup. `width` and `height` still matter: they are the size the
+    # window takes when it leaves fullscreen, whether or not this game offers a
+    # way to do that.
+    #
+    # `scale_mode:` decides what `width` and `height` *mean*, and the default
+    # answer is "the resolution the game is designed in". Under `:letterbox` the
+    # view a node draws into is always that size, whatever the window is doing,
+    # so a layout written against fixed numbers keeps working at any window size
+    # and in fullscreen — which is what almost every game wants and what nothing
+    # in the engine can supply for it afterwards.
+    #
+    # `:disabled` is the opt-out, and it is the right answer for something that
+    # should genuinely use whatever space it is given: a tool, a HUD-shaped
+    # program, an editor. It hands the window straight through as the view, and
+    # skips the clip, translate and scale that every other mode pushes. See
+    # RGame::Engine::Presentation.
+    #
+    # `locales:` is the directory the translation tables are in, relative to
+    # `media_root` unless absolute. Every `.yml` under it is loaded through the
+    # asset manager here, in sorted order, and the language is chosen from the
+    # player's OS preferences — so a game writes no i18n setup, and a language
+    # the player saved is set after `new` and before `start`. A directory that
+    # does not exist loads nothing, and every key shows as itself.
+    def initialize(root:, width: WIDTH, height: HEIGHT, caption: 'RGame',
+                   media_root: 'media', input_map: nil, device: Controls::KEYBOARD,
+                   players: 1, input: nil, fullscreen: false, scale_mode: :letterbox,
+                   locales: 'locales')
+      super(width: width, height: height, caption: caption, media_root: media_root,
+            fullscreen: fullscreen)
+
+      @root = root
+      @renderer = RGame::Core::Renderer.new(self)
+      @input = input || RGame::Core::Input.new(self)
+      @players = RGame::Engine::Players.new(
+        Array.new(players) do |id|
+          RGame::Engine::Player.new(id: id, device: id.zero? ? device : nil,
+                                    input_map: input_map)
+        end
+      )
+      @presentation = RGame::Engine::Presentation.new(width: width, height: height,
+                                                      mode: scale_mode)
+      @presentation.fit(self.width, self.height)
+      @viewports = RGame::Engine::Viewports.new(@players, width: @presentation.width,
+                                                          height: @presentation.height)
+      @debug = RGame::Engine::DebugOverlay.new
+      @dirty = true
+
+      install_asset_loaders
+      load_locales(locales)
+    end
+
+    # The player registry, also reachable from any node as
+    # `node.system(RGame::Engine::Players)` — which is how a scene gets at a
+    # camera to follow, without anything being threaded into its constructor.
+    #
+    # One player exists from the start, so a single-player game never mentions
+    # players at all: it is `players.primary` that an unowned node reads from,
+    # and `players.primary.camera` that a scene points at its hero.
+    attr_reader :players
+
+    # How the screen is divided. Reachable as `node.system(RGame::Engine::Viewports)`,
+    # which is how a cutscene deep in a scene collapses the split without
+    # anything being handed to it.
+    attr_reader :viewports
+
+    # Brings the tree live and runs until the window closes.
+    #
+    # The root gets this object as its `context`, which is how a node deep in
+    # the tree reaches the asset manager (`node.root.context.assets`) without
+    # anything being threaded through its constructor.
+    def start
+      @root.context = self
+      @root.add_component(@players)
+      @root.add_component(@viewports)
+      @audio_director = Engine::AudioDirector.new(audio).subscribe
+      @root.enter_tree
+      run
+    ensure
+      @audio_director&.unsubscribe
+    end
+
+    # One fixed simulation tick. `dt` is always the engine's fixed step, so the
+    # tree never sees variable frame time.
+    #
+    # **Input is polled here, per tick, not in `frame_begin` per frame.** That
+    # is not where it started, and the reason is edge detection: `pressed?` is
+    # "held now, not held at the previous poll", so whatever polls decides what
+    # a press *is*. `frame_begin` runs once per rendered frame, and a loop that
+    # renders faster than it simulates runs it many times between two ticks —
+    # each one shifting the previous state, so the press is consumed by a poll
+    # no tick ever reads. Menus stop responding, and only on fast machines.
+    #
+    # Polling per tick costs nothing extra and loses nothing: the C layer
+    # snapshots the keyboard once per frame, so several ticks inside one frame
+    # read identical state, and the edge lands on the first of them — one press,
+    # one `pressed?`, which is what a caller means.
+    def update(dt)
+      @players.poll(@input)
+      @root.control(@players)
+      @root.update(dt)
+      @root.sweep_freed
+      @dirty = true
+    end
+
+    # Only the simulation advancing makes the frame stale. While the overlay is
+    # up, redraw anyway, so its numbers stay live even when nothing is moving.
+    def needs_redraw? = @dirty || @debug.visible?
+
+    # The tree is drawn once, with the whole window as its view. Screen-space
+    # content — a HUD, a menu, a title card — lands there and is drawn exactly
+    # once, as it always was.
+    #
+    # **World content multiplies inside the tree, not here.** An
+    # RGame::Engine::WorldView draws its subtree once per viewport, clipping and
+    # translating for each, so where the world begins is the game's choice
+    # rather than a shape the platform imposes. That is also what keeps
+    # `node.root` meaning the game's own root: nothing is inserted above it.
+    def draw
+      @viewports.refresh
+      if @presentation.scaled?
+        presented { draw_tree }
+      else
+        draw_tree
+      end
+      @dirty = false
+    end
+
+    # How `width` and `height` are mapped onto the window: `:disabled`,
+    # `:stretch`, `:letterbox` or `:integer`. See RGame::Engine::Presentation.
+    def scale_mode = @presentation.mode
+
+    # Switchable while the game runs, for a settings screen.
+    #
+    # The viewports are resized as well as the presentation refitted, because
+    # the two modes disagree about what the logical size *is*: leaving `:integer`
+    # for `:disabled` turns a fixed 640x480 back into the window's own size, and
+    # a viewport still holding the old one would lay out into a corner.
+    def scale_mode=(mode)
+      @presentation.mode = mode
+      @viewports.resize(@presentation.width, @presentation.height)
+    end
+
+    # The window changed size, so the presentation is refitted and every rect and
+    # camera clamp follows. Under a scaling mode the logical size does not move,
+    # so the viewports are handed the same numbers again and only the transform
+    # in `draw` changes — which is the whole point of the mode.
+    def resize(width, height)
+      @presentation.fit(width, height)
+      @viewports.resize(@presentation.width, @presentation.height)
+    end
+
+    # Hot-plug is bookkeeping, not seating: a controller arriving becomes a
+    # device the registry watches, and it is someone *using* it that gives it to
+    # a player. Leaving takes it back off whoever had it.
+    def gamepad_connected(slot) = @players.device_connected(slot)
+    def gamepad_disconnected(slot) = @players.device_disconnected(slot)
+
+    # The two development keys, both function keys on purpose: **Escape is
+    # deliberately not bound here**, because it is the natural `cancel`/`back`
+    # button for a game's own menus, and a debug shortcut has no business taking
+    # the one key every player expects to close a dialog. F1 shows the overlay,
+    # F2 quits.
+    def button_down(id)
+      close if id == Controls::KEY_F2
+      @debug.toggle if id == Controls::KEY_F1
+    end
+
+    private
+
+    def draw_tree
+      @root.draw(@renderer, @viewports.screen)
+      @debug.draw(@renderer, @viewports.screen, fps)
+    end
+
+    def presented(&)
+      @renderer.clipped(@presentation.offset_x, @presentation.offset_y,
+                        (@presentation.width * @presentation.scale_x).round,
+                        (@presentation.height * @presentation.scale_y).round) do
+        @renderer.translated(@presentation.offset_x, @presentation.offset_y) do
+          @renderer.scaled(@presentation.scale_x, @presentation.scale_y, &)
+        end
+      end
+    end
+
+    def load_locales(directory)
+      assets.glob(File.join(directory, '**', '*.yml')).each { |path| assets.locale(path) }
+      RGame::Engine::I18n.locale = RGame::Engine::I18n.choose(RGame::Core.preferred_locales)
+    end
+
+    def install_asset_loaders
+      assets.add_loader(:locale) do |path|
+        RGame::Engine::I18n.load(File.read(path), source: path)
+      end
+
+      game = self
+      assets.add_loader(:tilemap) do |path|
+        map, image_path = RGame::Engine::TileMap.load(path)
+        tiles = game.assets.image(image_path)
+                    .tiles(map.tileset.tile_width, map.tileset.tile_height)
+        RGame::Core::TileMapRenderer.new(map, tiles)
+      end
+    end
+  end
+end

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