rgame 0.2.0 → 0.3.1

data/lib/rgame/engine/viewports.rb

@@ -38,9 +38,6 @@ module RGame
         @height = height
         @solo_camera = nil
         @pending = nil
-        # One View per possible player for the world, one more each for their own
-        # screen space, and one for the whole window. Built once and mutated in
-        # place. See View: these are reused, never rebuilt.
         @pool = []
         @screen_pool = []
         @views = []
@@ -114,6 +111,8 @@ module RGame
       #
       # Allocation-free once the pool has grown: Layout yields its rects rather
       # than building them, and the Views are mutated in place.
+      #
+      # @api private
       def refresh
         @screen.set(0, 0, @width, @height)
         @solo_camera ? refresh_solo : refresh_split
@@ -148,8 +147,6 @@ module RGame
         end
       end
 
-      # `each_active` is a filter, so it cannot be indexed without building an
-      # Array. Walking it costs nothing and this runs once per frame.
       def active_at(index)
         found = nil
         i = 0

data/lib/rgame/engine/world_view.rb

@@ -18,10 +18,11 @@ module RGame
     #
     # ## The subtree does not know how many times it is drawn
     #
-    # Children draw at their own absolute origin and never see a camera. This
-    # node supplies the view, so the same world serves one player or four with
-    # nothing below it changing — which is exactly what a camera owned by a node
-    # *inside* the world could not do, and why cameras belong to players.
+    # Children draw in their own local space and never see a camera. This node
+    # supplies the view — one clip and one translate around the whole subtree —
+    # so the same world serves one player or four with nothing below it changing,
+    # which is exactly what a camera owned by a node *inside* the world could not
+    # do, and why cameras belong to players.
     #
     # ## Only `draw` multiplies, and deliberately
     #

data/lib/rgame/engine.rb

@@ -1,71 +1,76 @@
 # frozen_string_literal: true
 
-# RGame::Engine — the scene graph a game is written against: nodes, components,
-# signals, scenes, collision, tile maps, pathing, pooling.
-#
-# Pure Ruby, and it links nothing. It may hold `RGame::Util` values but may not
-# name `RGame::Core` at all, reaching the platform only through objects handed
-# to it — a `renderer` passed into `draw`, an audio server behind
-# `AudioDirector`. See CLAUDE.md, "The three layers, and who may talk to whom".
-#
-# That is what lets the whole layer be specified with no window, no GPU and no
-# clock: `spec/` drives `update(dt)` directly and can run a simulated hour in
-# milliseconds.
-#
-# Loaded by `require "rgame"` along with Util, since between them they are
-# everything that runs without a window. Requirable on its own too — hence the
-# `util` require below rather than relying on `rgame.rb` to have got there
-# first: `TileMap` holds a `Util::Tensor`, which is exactly the dependency the
-# three-layer rule allows and this file therefore has to declare.
 require_relative 'util'
 
 require_relative 'engine/culling'
-require_relative 'engine/matrix'
 require_relative 'engine/signal'
+require_relative 'engine/sealed_privates'
 require_relative 'engine/node2d'
 require_relative 'engine/component'
 require_relative 'engine/animation_set'
 require_relative 'engine/animator'
 require_relative 'engine/camera'
 require_relative 'engine/layout'
+require_relative 'engine/presentation'
 require_relative 'engine/view'
 require_relative 'engine/world_view'
 require_relative 'engine/player_layer'
-require_relative 'engine/ui/menu_item'
+require_relative 'engine/ui/button'
+require_relative 'engine/ui/nine_slice_style'
+require_relative 'engine/ui/shape_style'
+require_relative 'engine/ui/text_button'
+require_relative 'engine/ui/panel_button'
+require_relative 'engine/ui/option_button'
+require_relative 'engine/ui/icon_button'
+require_relative 'engine/ui/stack'
+require_relative 'engine/ui/column'
+require_relative 'engine/ui/row'
+require_relative 'engine/ui/ring'
+require_relative 'engine/ui/navigation'
+require_relative 'engine/ui/stepping'
+require_relative 'engine/ui/pointing'
 require_relative 'engine/ui/menu'
+require_relative 'engine/ui/panel_menu'
+require_relative 'engine/ui/radial_menu'
 require_relative 'engine/path'
 require_relative 'engine/timer'
 require_relative 'engine/tileset'
 require_relative 'engine/tile_map'
-require_relative 'engine/tile_collision'
+require_relative 'engine/tile_blockers'
+require_relative 'engine/nav_grid'
+require_relative 'engine/actor_blockers'
+require_relative 'engine/bounds_blockers'
 require_relative 'engine/collision_box'
 require_relative 'engine/collision_system'
 require_relative 'engine/circle_collider'
 require_relative 'engine/spatial_hash'
+require_relative 'engine/contact_set'
 require_relative 'engine/pool'
-require_relative 'engine/resettable'
 require_relative 'engine/audio_bus'
 require_relative 'engine/audio_director'
 require_relative 'engine/i18n'
-require_relative 'engine/cached_label'
+require_relative 'engine/text'
 require_relative 'engine/debug_overlay'
-require_relative 'engine/body'
-require_relative 'engine/actor'
 require_relative 'engine/input/actions'
 require_relative 'engine/input/input_map'
 require_relative 'engine/input/action_mapper'
-require_relative 'engine/input/player_controller'
 require_relative 'engine/player'
 require_relative 'engine/players'
 require_relative 'engine/viewports'
 require_relative 'engine/scene/scene_stack'
+require_relative 'engine/components/identity'
+require_relative 'engine/components/mover'
 require_relative 'engine/components/velocity'
 require_relative 'engine/components/pool'
 require_relative 'engine/components/path_follow'
+require_relative 'engine/components/navigator'
 require_relative 'engine/components/timer'
+require_relative 'engine/components/world'
 require_relative 'engine/components/screen_wrap'
 require_relative 'engine/components/despawn_offscreen'
 require_relative 'engine/components/circle_collider'
+require_relative 'engine/components/box_collider'
+require_relative 'engine/components/feet_collider'
 require_relative 'engine/components/collision_world'
 require_relative 'engine/components/targeting'
 require_relative 'engine/components/sprite'
@@ -74,6 +79,7 @@ require_relative 'engine/components/action_trigger'
 require_relative 'engine/components/tile_world'
 require_relative 'engine/components/character_body'
 require_relative 'engine/components/player_controller'
+require_relative 'engine/components/hop'
 require_relative 'engine/components/wander_controller'
 require_relative 'engine/components/animated_sprite'
 require_relative 'engine/components/camera_follow'

data/lib/rgame/game.rb

@@ -55,18 +55,45 @@ module RGame
     # `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_example.rb,
-    # and CLAUDE.md's "The examples 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.
+    # 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)
-      super(width: width, height: height, caption: caption, media_root: media_root)
+                   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)
@@ -77,11 +104,16 @@ module RGame
                                     input_map: input_map)
         end
       )
-      @viewports = RGame::Engine::Viewports.new(@players, width: width, height: height)
-      @debug = RGame::Engine::DebugOverlay.new # always wired up; F1 reveals it
-      @dirty = true # draw the first frame
+      @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
@@ -105,12 +137,13 @@ module RGame
     # anything being threaded through its constructor.
     def start
       @root.context = self
-      # Root-scoped systems, mounted before the tree comes alive so that an
-      # on_add anywhere in it can already resolve node.system(...) for either.
       @root.add_component(@players)
       @root.add_component(@viewports)
-      @root.enter_tree # components attach, then on_add
+      @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
@@ -130,11 +163,9 @@ module RGame
     # one `pressed?`, which is what a caller means.
     def update(dt)
       @players.poll(@input)
-      # The registry, not one player's snapshot: each node resolves the actions
-      # of whoever owns it, and a node that claims nobody gets the primary.
       @root.control(@players)
       @root.update(dt)
-      @root.sweep_freed # flush queue_free'd nodes outside the update traversal
+      @root.sweep_freed
       @dirty = true
     end
 
@@ -152,14 +183,38 @@ module RGame
     # 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 # rects from the layout, then reclamp every camera
-      @root.draw(@renderer, @viewports.screen)
-      @debug.draw(@renderer, @viewports.screen, fps) # last, so it layers on top
+      @viewports.refresh
+      if @presentation.scaled?
+        presented { draw_tree }
+      else
+        draw_tree
+      end
       @dirty = false
     end
 
-    # The window changed size, so every rect and every camera clamp does too.
-    def resize(width, height) = @viewports.resize(width, height)
+    # 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
@@ -179,14 +234,31 @@ module RGame
 
     private
 
-    # Teaches the asset manager the types Core cannot build for itself.
-    #
-    # `:tilemap` is the only one so far, and it is the reason this method
-    # exists: `RGame::Engine::TileMap` reads the `.tmx`, `Image#tiles` slices the
-    # tileset through the cache — so two maps sharing a tileset share one
-    # upload — and `Core::TileMapRenderer` draws the result. Three objects, and
-    # neither of the outer two may name the other.
+    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)

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