rgame 0.1.0 → 0.3.0

data/lib/rgame/engine/components/tile_world.rb

@@ -8,59 +8,100 @@ module RGame
       # everything an actor needs from it — collision against the solid tiles, the world
       # bounds, and drawing the map through the scene's camera.
       #
-      # Collision reuses Engine::CollisionSystem (TileCollision + a world-bounds clamp);
-      # the tile solidity is whatever the map's tileset reports (baked per-tile in Tiled).
+      # **It does not resolve a step.** What it owns is the map's solid tiles as a blocker
+      # source (#blockers, an Engine::TileBlockers); the actor that wants to be stopped by
+      # them borrows it and resolves against it — see Components::Mover, which
+      # builds its own Engine::CollisionSystem out of the sources its `blocked_by` names.
+      # A mover may be blocked by tiles, by other actors, or by both, and only the mover
+      # knows which, so the resolver is the mover's and the grid is this system's. The tile
+      # solidity itself is whatever the map's tileset reports (baked per-tile in Tiled).
+      # The same solidity, viewed as a graph for planning routes, is #nav_grid.
       #
-      # Drawing splits into two z bands so actors can sit between them: the below band
-      # (ground, same-level detail) at GROUND_Z and the above band (canopies, roofs) at
-      # OVERLAY_Z. Actors draw at a z in between (the renderer sorts by z, so the
-      # draw-call order doesn't matter). The camera is centred by the scene before any
-      # drawing.
+      # **Solidity is read from the map once**, into one Util::SolidGrid, the first time
+      # anything asks — and #blockers, #nav_grid and #solid? all read that store, never the
+      # map. So they cannot disagree about a cell, and a resolve costs a byte lookup rather
+      # than a walk through the map's layers and tileset.
       #
-      # It also owns the map's **animation clock**. Nothing below reads a wall clock —
+      # **It does not draw.** Drawing the map is RGame::Engine::TileMapLayer, one
+      # node per Tiled layer, mounted inside the WorldView so the map is drawn
+      # once per viewport like the rest of the world. This stays a system — the
+      # thing actors ask about collision and bounds — and a system that also
+      # drew was always the odd part of it.
+      #
+      # It owns the map's **animation clock**. Nothing below reads a wall clock —
       # see CLAUDE.md, "`draw` renders state; time enters through `update`" — so the
       # elapsed seconds animated tiles run on are accumulated here and handed down at
       # draw time. Stop calling `update` and the water freezes, which is what pausing
       # should look like.
       class TileWorld < Engine::Component
-        GROUND_Z  = 0
-        OVERLAY_Z = 20
+        include WorldBounds
+
+        attr_reader :tilemap_id, :elapsed
 
-        def initialize(map:, tilemap_id:, camera:)
+        # `cameras` are the cameras this map bounds — every player's, normally.
+        # A camera may not show past the world's edges, and this is what knows
+        # how big the world is; the cameras themselves are owned by players.
+        def initialize(map:, tilemap_id:, cameras: [])
           super()
           @map = map
           @tilemap_id = tilemap_id
-          @camera = camera
           @elapsed = 0.0
-          @collision = Engine::CollisionSystem.new(
-            tile_collision: Engine::TileCollision.new(
-              tile_width: map.tile_width, tile_height: map.tile_height,
-              solid: ->(col, row) { map.solid_tile?(col, row) }
-            ),
-            world_width: map.pixel_width, world_height: map.pixel_height
-          )
+          Array(cameras).each { |camera| bound(camera) }
+        end
+
+        # The map's solid tiles as a blocker source, for a body that declared
+        # `blocked_by: [:tiles]`. The same source every time, so every body on the map
+        # shares one.
+        def blockers
+          @blockers ||= Engine::TileBlockers.new(grid: solid_grid, tile_width: @map.tile_width,
+                                                 tile_height: @map.tile_height)
         end
 
         def world_width = @map.pixel_width
         def world_height = @map.pixel_height
 
-        # Move an actor (responds to x/y/collision_box) by (dx, dy), sliding along solids
-        # and clamped inside the world. Delegates to the reused collision system.
-        def move(actor, dx, dy) = @collision.move(actor, dx, dy)
+        # The size of one cell, in pixels — what turns a world position into the cell
+        # #nav_grid plans over.
+        def tile_width = @map.tile_width
+        def tile_height = @map.tile_height
+
+        def layer_count = @map.layer_count
+
+        # The first layer Tiled flags `above`, or the layer count if none is —
+        # which is where TileMapLayer.mount leaves the gap for the actors, so a
+        # map with no flag puts them over everything. Read once at mount rather
+        # than per frame: which layers cover the actors is a fact about the
+        # scene's arrangement, and the arrangement is made once.
+        def first_above_layer
+          layer_count.times.find { |index| @map.above_layer?(index) } || layer_count
+        end
+
+        # Clamp a camera to this map's edges. Called for each camera the scene
+        # hands over, and again for one that arrives later (a player joining).
+        def bound(camera)
+          camera.world_width = @map.pixel_width
+          camera.world_height = @map.pixel_height
+          camera
+        end
 
-        def solid?(col, row) = @map.solid_tile?(col, row)
+        def solid?(col, row) = solid_grid.solid?(col, row)
+
+        # The map's solid tiles as an Engine::NavGrid, for planning a route rather than
+        # resolving a step — over the same store #blockers reads, as a second view. Built on
+        # first ask, and the same grid every time after.
+        def nav_grid
+          @nav_grid ||= Engine::NavGrid.new(grid: solid_grid)
+        end
 
         # Advances the tile animations. Seconds, like every other duration here.
         def update(dt)
           @elapsed += dt
         end
 
-        def draw(renderer)
-          renderer.tilemap(@tilemap_id, @camera.x, @camera.y,
-                           @camera.viewport_width, @camera.viewport_height, elapsed: @elapsed)
-          renderer.tilemap_overlay(@tilemap_id, @camera.x, @camera.y,
-                                   @camera.viewport_width, @camera.viewport_height,
-                                   z: OVERLAY_Z, elapsed: @elapsed)
+        private
+
+        def solid_grid
+          @solid_grid ||= Util::SolidGrid.build(@map.width, @map.height) { |col, row| @map.solid_tile?(col, row) }
         end
       end
     end

data/lib/rgame/engine/components/timer.rb

@@ -26,7 +26,7 @@ module RGame
       # When a node needs more than one (a spawn cadence and a wave cadence), give them
       # distinct `as:` names — a node holds one component per slot.
       class Timer < Engine::Component
-        signal :on_timeout # emits no payload
+        signal :on_timeout
 
         def initialize(interval, repeating: true)
           super()

data/lib/rgame/engine/components/velocity.rb

@@ -5,20 +5,36 @@ module RGame
     module Components
       # Integrates linear and angular velocity into the node's transform each step.
       # Free-moving entities (rocks, bullets) use it alone; a controller component
-      # (or the node's own control hook) writes vx/vy/spin as intent. From Body#integrate.
-      class Velocity < Engine::Component
+      # (or the node's own control hook) writes vx/vy/spin as intent.
+      #
+      # A Mover, so `blocked_by:` stops it the way it stops a CharacterBody — see Mover's
+      # header. A blocked step keeps `vx`/`vy` as they were: they are the intent, and what
+      # a stop should do to them (nothing, zero them, bounce) is the game's call, made in
+      # an `on_blocked` handler.
+      class Velocity < Mover
         attr_accessor :vx, :vy, :spin
 
-        def initialize(vx: 0.0, vy: 0.0, spin: 0.0)
-          super()
+        def initialize(vx: 0.0, vy: 0.0, spin: 0.0, blocked_by: [])
+          super(blocked_by: blocked_by)
           @vx = vx
           @vy = vy
           @spin = spin
         end
 
-        def update(dt)
-          node.x += @vx * dt
-          node.y += @vy * dt
+        # The velocity scaled so its larger axis is ±1 — the direction, without the square
+        # root a unit vector would cost.
+        def heading_x = scale_to_heading(@vx)
+        def heading_y = scale_to_heading(@vy)
+
+        private
+
+        def scale_to_heading(axis)
+          larger = [@vx.abs, @vy.abs].max
+          larger.zero? ? 0.0 : axis / larger.to_f
+        end
+
+        def take_step(dt)
+          apply_move(@vx * dt, @vy * dt)
           node.angle += @spin * dt
         end
       end

data/lib/rgame/engine/components/wander_controller.rb

@@ -7,6 +7,10 @@ module RGame
       # direction (one of eight, or idle) and holds it until a timer elapses — or until a
       # wall blocks it, at which point it re-rolls early instead of pushing into the wall.
       # The RNG is injected so behaviour is deterministic in tests.
+      #
+      # "Blocked" is measured as *the node did not move while intending to*, not asked of
+      # a collision world — so this works over any CharacterBody, and simply never fires
+      # for one whose steps always land.
       class WanderController < Engine::Component
         MOVED_EPS = 1e-6
         DIRECTIONS = [
@@ -19,11 +23,11 @@ module RGame
           @rng = rng
           @change_interval = change_interval
           @idle_chance = idle_chance
-          @timer = 0.0 # rolls a direction on the first update
+          @timer = 0.0
         end
 
         def on_attach
-          @body = node.get_component(CharacterBody)
+          @body = require_sibling(CharacterBody)
           @last_x = node.x
           @last_y = node.y
         end

data/lib/rgame/engine/components/world.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    module Components
+      # How big the world is — the contract, not an implementation.
+      #
+      # Two systems answer it: `World` below, which is nothing *but* the answer,
+      # and `TileWorld`, which derives it from the map it parsed. A component
+      # that needs bounds asks for the contract — `node.system(WorldBounds)` —
+      # and gets whichever of the two the scene mounted. That works because
+      # Node2D#get_component matches with `is_a?`, which matches an included
+      # module as readily as a class.
+      #
+      # Naming the contract is what keeps the two from drifting: ScreenWrap does
+      # not know which kind of world it is wrapping inside, and must not need to.
+      #
+      # ## The bounds are in world coordinates
+      #
+      # The world runs from (0, 0) to (world_width, world_height) in **world**
+      # space — the space `Node2D#world_x` answers in, and the one the tile grid,
+      # the collision world and the camera already use. So everything that
+      # compares a node against these bounds compares `world_x`/`world_y`, never
+      # the node's local `x`/`y`: an entity grouped under an offset container is
+      # still inside the world when it is, whatever its position in the container.
+      # spec/support/shared_examples/a_world_edge_response.rb holds every reader to it.
+      module WorldBounds
+        def world_width = raise(NotImplementedError, "#{self.class} must define #world_width")
+        def world_height = raise(NotImplementedError, "#{self.class} must define #world_height")
+
+        # The bounds a component should use: whatever it was handed, falling back
+        # to the world system on `node` for either axis left nil. The single place
+        # that fallback is written, so the components sharing it cannot drift.
+        #
+        # Call it from `on_attach`, not `initialize` — a node has no scene to ask
+        # until it is in the tree, and a pooled entity is built long before it is.
+        def self.resolve(node, width, height)
+          return [width, height] if width && height
+
+          bounds = node.system(self)
+          if bounds.nil?
+            raise 'no world bounds in scope: mount a World (or TileWorld) system on the scene, ' \
+                  'or pass explicit width:/height:'
+          end
+
+          [width || bounds.world_width, height || bounds.world_height]
+        end
+
+        # Refuse a node carrying more than one response to the edge of the world:
+        # ScreenWrap, DespawnOffscreen, or a Mover declaring `blocked_by: [:bounds]`.
+        #
+        # Stopping at the edge, wrapping past it and being freed beyond it are three
+        # answers to one question, and no two of them mean anything together. Stop and
+        # wrap disagree about where the node ends up; wrap and despawn race on which
+        # margin is reached first; and the stop works on the collision box while the
+        # other two test the node's origin, so a box with an offset holds the origin
+        # just past the edge and the other response fires on a node that was held.
+        # Rather than a rule each game has to remember, it raises.
+        #
+        # Folding wrap and despawn into Mover as one `at_edge:` option would make two
+        # responses inexpressible too, but they act on the node however it moved — a reset,
+        # an ancestor, a direct write — and every option there is a branch on the free
+        # step's path. A refusal at attach costs no frame anything. It is also the place
+        # to change if a game wants wrapping on one axis and stopping on the other: the
+        # rule then becomes one response per axis.
+        #
+        # Every response calls this from its own on_attach, which is what makes it
+        # order-free: a node assembled outside the tree already holds all its
+        # components when the first attaches, and on a live node each attaches on
+        # arrival, so the second response always finds the first.
+        #
+        # A pooled node re-attaches on every spawn, so this walks the components
+        # without allocating, and builds a message only when it raises.
+        def self.one_response!(node)
+          first = nil
+          node.components.each do |component|
+            next unless edge_response?(component)
+            next first = component if first.nil?
+
+            raise "#{node.class} has two responses to the edge of the world: " \
+                  "#{describe_response(first)} and #{describe_response(component)}. " \
+                  'A node can stop at the edge, wrap past it or be freed beyond it, but ' \
+                  'only one of those — keep the one this node is for.'
+          end
+        end
+
+        def self.edge_response?(component)
+          component.is_a?(ScreenWrap) || component.is_a?(DespawnOffscreen) ||
+            (component.is_a?(Mover) && component.blocked_by?(Mover::BOUNDS))
+        end
+        private_class_method :edge_response?
+
+        def self.describe_response(component)
+          name = component.class.name&.split('::')&.last || component.class.inspect
+          component.is_a?(Mover) ? "#{name} (blocked_by :bounds)" : name
+        end
+        private_class_method :describe_response
+      end
+
+      # The scene-scoped world: how big it is, and nothing else yet.
+      #
+      # A game whose world is a plain rectangle mounts one on its scene, and the
+      # components that need bounds — ScreenWrap, DespawnOffscreen — find it
+      # rather than having the numbers threaded through every constructor between
+      # the scene and the entity. That threading is what this replaces, and it was
+      # worse than it looks: a pooled entity is built outside the tree, so its
+      # factory had to close over the size, and every scene above the factory had
+      # to carry the size in order to build it.
+      #
+      # It is deliberately **not** the window size. The two coincide in a
+      # single-screen game, which is exactly what makes the mistake easy to make
+      # and hard to see: bind wrapping to the viewport and the world silently
+      # changes shape when the window is resized, or when the screen is split and
+      # each half is its own viewport. Ask `Viewports` (or the `View` a draw is
+      # handed) how big the *window* is; ask this how big the *world* is.
+      #
+      # The bounds are immutable, which is what lets the components resolve them
+      # once at attach rather than re-reading them every frame. A world that
+      # genuinely changes size is a new scene.
+      class World < Engine::Component
+        include WorldBounds
+
+        attr_reader :world_width, :world_height
+
+        def initialize(width:, height:)
+          super()
+          @world_width = width
+          @world_height = height
+        end
+      end
+    end
+  end
+end

data/lib/rgame/engine/contact_set.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    # The colliders one collider is touching, this step and last. CollisionWorld owns
+    # one of these per registered collider and drives it, and together they are what
+    # turns a per-step overlap test into the two edges a game actually wants: the step
+    # a contact starts and the step it ends. Pure logic; no graphics.
+    #
+    # Nothing here is about overlapping, though, and it has a second user:
+    # every Components::Mover keeps one of *what stopped its step*, and gets on_blocked
+    # and on_unblocked out of it on exactly the same terms. What this class is, underneath
+    # its names, is "the set of things that were true this step and last".
+    #
+    # Two arrays, swapped rather than reallocated. `begin_frame` makes this step's list
+    # into last step's and empties the other one for refilling, so after the first few
+    # frames nothing here allocates — `Array#clear` keeps the capacity it grew to, the
+    # same trick SpatialHash#clear relies on.
+    #
+    # Membership is a linear scan by identity, and deliberately so. A Set or a Hash
+    # allocates on insert, and both are slower than scanning a handful of entries; a
+    # collider touching more than a handful of things at once is a design problem
+    # somewhere else, not a reason to index this.
+    class ContactSet
+      def initialize
+        @current = []
+        @previous = []
+      end
+
+      # Start a step: this step's contacts become the ones to compare against, and the
+      # list being filled is emptied. Swapped through a temporary rather than by
+      # `@current, @previous = @previous, @current`, which would allocate an Array every
+      # step — see .rubocop.yml on Style/SwapValues.
+      def begin_frame
+        filled = @current
+        @current = @previous
+        @previous = filled
+        @current.clear
+      end
+
+      # Forget everything, both steps. CollisionWorld calls this when a collider
+      # registers, so a pooled entity that died mid-contact cannot come back still
+      # holding the contacts it had in its previous life — which would otherwise
+      # surface as one spurious `on_separated` on its first step.
+      def reset
+        @current.clear
+        @previous.clear
+      end
+
+      # Record a contact for this step.
+      def add(other) = @current << other
+
+      # Already recorded this step? The broadphase offers a pair once per cell the two
+      # share, so this is what keeps one overlap from being counted twice.
+      def touching?(other) = @current.include?(other)
+
+      # Is this the *start* of a contact — a pair that was not touching last step? It
+      # reads only last step's list, so it gives the same answer either side of #add,
+      # and asking before recording is what reads as a guard.
+      def started?(other) = !@previous.include?(other)
+
+      # Yield every collider that was in contact last step and is not in contact now —
+      # the ending edge. Call it once every pair for the step has been recorded.
+      def each_ended
+        i = 0
+        while i < @previous.size
+          other = @previous[i]
+          i += 1
+          yield other unless @current.include?(other)
+        end
+      end
+    end
+  end
+end

data/lib/rgame/engine/culling.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    # Skipping a drawable that the viewport cannot show.
+    #
+    # Mixed into the components that draw a node's own footprint, which are the
+    # ones that know both where they put it and how big it is.
+    #
+    # ## Why it is worth doing at all
+    #
+    # It was not, while the world was drawn once: a handful of skipped draws
+    # against a frame's worth of work. Split-screen changes the arithmetic —
+    # the world is walked once per viewport, and an actor at one player's end of
+    # the map is off the *other* player's view every frame. What used to be a
+    # small saving becomes a saving multiplied by the number of people playing.
+    #
+    # ## Conservative on purpose
+    #
+    # Culling one frame too eagerly is a sprite popping in at the edge of the
+    # screen, which is worse than the draw it saved. So two rules:
+    #
+    # - **No size means no culling.** `node.width`/`height` are what a drawable's
+    #   footprint is measured from, and a node that never set them (nothing
+    #   requires it) reads as 0×0, which would otherwise cull everything
+    #   instantly. Unknown means draw.
+    # - **A rotated node is measured generously.** `Node2D#draw` rotates about the
+    #   node's own origin, so a rotated footprint can reach further than its
+    #   box in any direction. The margin is `width + height`, which is always at
+    #   least the diagonal `hypot(width, height)` and costs no square root on a
+    #   path that runs once per drawable per viewport.
+    module Culling
+      private
+
+      # hot-path
+      def culled?(view, x, y, width, height)
+        return false if width.zero? || height.zero?
+        return !view.visible?(x, y, width, height) if node.world_angle.zero?
+
+        margin = width + height
+        !view.visible?(x - margin, y - margin, width + (margin * 2), height + (margin * 2))
+      end
+    end
+  end
+end

data/lib/rgame/engine/debug_overlay.rb

@@ -35,27 +35,33 @@ module RGame
       OBJ_LABEL   = 'OBJ'
       DELTA_LABEL = 'Δ/f'
 
-      COLOR = [80, 255, 120].freeze # frozen so the renderer caches the resolved colour
-      Z     = 1_000_000             # above any scene content
-      PAD   = 8                     # margin from the screen edge
-      GAP   = 8                     # space between a label and its number
+      COLOR = [80, 255, 120].freeze
+      PAD   = 8
+      GAP   = 8
 
       def initialize
         @visible = false
         @prev_allocated = 0
-        @digit_widths  = Array.new(10) # measured once, then reused
-        @label_widths  = {}            # measured once per label, then reused
+        @digit_widths  = Array.new(10)
+        @label_widths  = {}
       end
 
       def visible? = @visible
 
       def toggle
         @visible = !@visible
-        # Baseline the counter on reveal so the first Δ/f isn't the whole run's history.
         @prev_allocated = GC.stat(:total_allocated_objects) if @visible
       end
 
-      def draw(renderer, width, height, fps)
+      # Laid out against the view it is drawn into rather than against the
+      # window, so it stays in the corner of whatever region it is given. It
+      # takes `fps` rather than reading it, for the same reason nothing here
+      # reads a clock: the number is measured by the shell that owns the loop
+      # and handed down. See CLAUDE.md, "`draw` renders state".
+      # Its own `:debug` band, which is the last one, so this lands over every
+      # other thing in the frame however the scene is arranged. Not a node, so
+      # it opens its own layer rather than being given one by the traversal.
+      def draw(renderer, view, fps)
         return unless @visible
 
         allocated = GC.stat(:total_allocated_objects)
@@ -63,24 +69,23 @@ module RGame
         @prev_allocated = allocated
 
         line_h  = renderer.text_height
-        right_x = width - PAD
-        top_y   = height - PAD - (line_h * 3)
+        right_x = view.width - PAD
+        top_y   = view.height - PAD - (line_h * 3)
 
-        draw_line(renderer, FPS_LABEL, fps, right_x, top_y)
-        draw_line(renderer, OBJ_LABEL, allocated, right_x, top_y + line_h)
-        draw_line(renderer, DELTA_LABEL, delta, right_x, top_y + (line_h * 2))
+        renderer.layered(:debug) do
+          draw_line(renderer, FPS_LABEL, fps, right_x, top_y)
+          draw_line(renderer, OBJ_LABEL, allocated, right_x, top_y + line_h)
+          draw_line(renderer, DELTA_LABEL, delta, right_x, top_y + (line_h * 2))
+        end
       end
 
       private
 
-      # A right-aligned "label  number" row ending at right_x.
       def draw_line(renderer, label, value, right_x, y)
         number_left = draw_uint(renderer, value, right_x, y)
-        renderer.text(label, number_left - GAP - label_width(renderer, label), y, z: Z, color: COLOR)
+        renderer.text(label, number_left - GAP - label_width(renderer, label), y, color: COLOR)
       end
 
-      # Draw a non-negative integer right-aligned ending at right_x, digit by digit so no
-      # String is built per frame. Returns the x of the leftmost digit.
       def draw_uint(renderer, value, right_x, y)
         x = right_x
         more = true
@@ -88,7 +93,7 @@ module RGame
           digit = value % 10
           value /= 10
           x -= digit_width(renderer, digit)
-          renderer.text(DIGITS[digit], x, y, z: Z, color: COLOR)
+          renderer.text(DIGITS[digit], x, y, color: COLOR)
           more = value.positive?
         end
         x

data/lib/rgame/engine/i18n/plural.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    module I18n
+      # A translation that varies with `count`: one `Template` per CLDR category
+      # the table spells out, and the locale of the table it came from, whose
+      # language decides which category a count falls into.
+      #
+      # Internal to `I18n`. A nested Hash in a table compiles to a Plural when
+      # every key is a category, every value is text, and `other` is among them;
+      # any other Hash is a level of nesting.
+      #
+      # @api private
+      class Plural
+        CATEGORIES = %i[zero one two few many other].freeze
+        CATEGORY_NAMES = CATEGORIES.map(&:name).freeze
+
+        attr_reader :locale
+
+        # The variable names any form uses, each once, and `count`, which every
+        # form is chosen by whether it prints it or not.
+        attr_reader :names
+
+        def self.forms?(entries)
+          entries.key?('other') &&
+            entries.all? { |name, value| CATEGORY_NAMES.include?(name) && value.is_a?(String) }
+        end
+
+        def initialize(locale, entries)
+          @locale = locale
+          @forms = entries.to_h { |name, source| [name.to_sym, Template.compile(source)] }.freeze
+          @names = @forms.values.flat_map(&:names).push(:count).uniq.freeze
+        end
+
+        # The template for `count`, whose category under this table's language
+        # is `category`. An explicit `zero` form wins for 0 in every language,
+        # and a category the table leaves out reads `other`.
+        def template_for(count, category)
+          (count == 0 && @forms[:zero]) || @forms[category] || @forms.fetch(:other) # rubocop:disable Style/NumericPredicate -- count may be any object
+        end
+      end
+    end
+  end
+end