rgame 0.2.0 → 0.3.0

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

@@ -4,26 +4,58 @@ module RGame
   module Engine
     module Components
       # Walks the owning node along an Engine::Path at a constant speed, segment by
-      # segment, and emits `on_finished` once it reaches the final waypoint — the seam a
-      # tower defense game uses to leak a life when an enemy reaches the base.
+      # segment, and emits `on_finished` once it reaches the final waypoint — the seam for
+      # whatever should happen when a walker arrives.
       #
       # The walk is allocation-free: it tracks the current segment and the distance into
       # it, advancing through as many segments as one step crosses (so a fast mover over
       # short segments still lands correctly), then interpolates the node's position from
       # the segment endpoints. Movement is driven purely by `speed * dt`; this is not a
       # Velocity integrator and ignores the node's angle.
-      class PathFollow < Engine::Component
-        signal :on_finished # emits no payload; the owning node identifies which follower finished
+      #
+      # ## Blocked, the walk waits
+      #
+      # A Mover, so `blocked_by:` stops it the way it stops a CharacterBody — see Mover's
+      # header. Declaring nothing keeps the walk exactly as described above: the node is
+      # *placed* on the path each step.
+      #
+      # Declaring something turns the placement into a move: the walk still works out
+      # where the node should be, and then gets there through `apply_move`. **A step that
+      # is stopped short does not advance the walk** — progress goes back to where the
+      # step began. The obvious alternative, letting progress run on and the node catch up,
+      # is wrong twice over: a follower held behind something for a second would race
+      # ahead to where it "should" be once let go, and `on_finished` could fire for a
+      # walker still standing in front of the obstacle.
+      #
+      # One consequence is easy to miss: **a held follower does not slide along what stopped
+      # it** the way a Velocity does. A step's free axis still moves, but the rewind aims the
+      # next step at the same point on the path, from a little closer, so a follower pressed
+      # diagonally against a wall creeps to rest instead of sliding to the corner. A walker
+      # meant to get round something replans its path rather than relying on the slide.
+      #
+      # `on_attach` still places the node on the first waypoint absolutely, blocked or
+      # not: where a walker starts is a placement, not a step.
+      #
+      # ## A new route, and none
+      #
+      # `path: nil` builds an idle follower, which moves nothing and never finishes, and
+      # `follow(path)` hands any follower a route to walk from its start — the same restart
+      # entering the tree gives, so a walker that finished one route walks the next and
+      # finishes again, and one still walking drops its old route at once.
+      #
+      # Its heading is the unit direction of the segment it is on, worked out when the walk
+      # crosses into a segment rather than on every read.
+      class PathFollow < Mover
+        signal :on_finished
 
         attr_accessor :speed
+        attr_reader :path, :heading_x, :heading_y
 
-        def initialize(path:, speed:)
-          super()
+        def initialize(speed:, path: nil, blocked_by: [])
+          super(blocked_by: blocked_by)
           @path = path
           @speed = speed
-          @segment = 0       # walking from waypoint @segment to @segment + 1
-          @distance = 0.0    # distance travelled into the current segment
-          @finished = false
+          restart
         end
 
         def finished? = @finished
@@ -32,52 +64,112 @@ module RGame
         # progress cleared — so a pooled follower reacquired and re-added begins a fresh walk
         # rather than resuming (or staying finished) where its previous life ended.
         def on_attach
-          @segment = 0
-          @distance = 0.0
-          @finished = false
-          place_at(0)
+          super
+          restart
         end
 
-        def update(dt)
-          return if @finished
+        # Walk `path` from its first waypoint, where the node is placed, whatever this
+        # follower was doing — idle, finished, or halfway along another route. `nil` stops
+        # it where it stands.
+        def follow(path)
+          @path = path
+          restart
+        end
+
+        private
+
+        def take_step(dt)
+          return if @finished || @path.nil?
+
+          from_segment = @segment
+          from_distance = @distance
+
+          if advance_to_end?(@speed * dt)
+            last = @path.count - 1
+            return finish if moved_to?(@path.x_at(last), @path.y_at(last))
+
+            rewind(from_segment, from_distance)
+          else
+            seg_len = @path.segment_length(@segment)
+            t = seg_len.zero? ? 0.0 : @distance / seg_len
+            sx = @path.x_at(@segment)
+            sy = @path.y_at(@segment)
+            reached = moved_to?(sx + ((@path.x_at(@segment + 1) - sx) * t),
+                                sy + ((@path.y_at(@segment + 1) - sy) * t))
+            rewind(from_segment, from_distance) unless reached
+          end
+          aim
+        end
 
-          remaining = @speed * dt
+        def advance_to_end?(remaining)
           while remaining.positive?
             left = @path.segment_length(@segment) - @distance
             if remaining < left
               @distance += remaining
-              break
+              return false
             end
-            # Consume the rest of this segment and step onto the next waypoint.
             remaining -= left
             @segment += 1
             @distance = 0.0
-            return finish if @segment >= @path.count - 1
+            return true if @segment >= @path.count - 1
           end
-          place_along_segment
+          false
         end
 
-        private
+        def moved_to?(x, y)
+          unless blocking?
+            node.x = x
+            node.y = y
+            return true
+          end
+
+          apply_move(x - node.x, y - node.y)
+          !last_move_blocked?
+        end
+
+        def rewind(segment, distance)
+          @segment = segment
+          @distance = distance
+        end
 
         def finish
-          place_at(@path.count - 1)
           @finished = true
+          head_nowhere
           on_finished_signal.emit
         end
 
+        def restart
+          @segment = 0
+          @distance = 0.0
+          @finished = false
+          head_nowhere
+          return unless @path
+
+          aim
+          place_at(0) if node
+        end
+
+        def aim
+          return if @segment == @aimed_segment
+
+          @aimed_segment = @segment
+          length = @path.segment_length(@segment)
+          return head_nowhere if length.zero?
+
+          @heading_x = (@path.x_at(@segment + 1) - @path.x_at(@segment)) / length
+          @heading_y = (@path.y_at(@segment + 1) - @path.y_at(@segment)) / length
+        end
+
+        def head_nowhere
+          @aimed_segment = nil
+          @heading_x = 0.0
+          @heading_y = 0.0
+        end
+
         def place_at(waypoint)
           node.x = @path.x_at(waypoint)
           node.y = @path.y_at(waypoint)
         end
-
-        def place_along_segment
-          seg_len = @path.segment_length(@segment)
-          t = seg_len.zero? ? 0.0 : @distance / seg_len
-          sx = @path.x_at(@segment)
-          sy = @path.y_at(@segment)
-          node.x = sx + ((@path.x_at(@segment + 1) - sx) * t)
-          node.y = sy + ((@path.y_at(@segment + 1) - sy) * t)
-        end
       end
     end
   end

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

@@ -5,7 +5,10 @@ module RGame
     module Components
       # Drives a CharacterBody sibling from two input axes — direct 8-way walking, no
       # inertia (unlike ThrustController). Each frame it copies the axis snapshot into
-      # the body's movement intent; the body does the collision-checked move.
+      # the body's movement intent; what the body then does with it is the body's
+      # business — an unblocked CharacterBody moves the node, a blocked one resolves
+      # the step against the map. The lookup names the base class and get_component
+      # matches by ancestry, so this needs to know nothing about which is there.
       class PlayerController < Engine::Component
         def initialize(x_axis: :move_x, y_axis: :move_y)
           super()
@@ -13,7 +16,7 @@ module RGame
           @y_axis = y_axis
         end
 
-        def on_attach = @body = node.get_component(CharacterBody)
+        def on_attach = @body = require_sibling(CharacterBody)
 
         def control(actions)
           @body.set_intent(actions.axis(@x_axis), actions.axis(@y_axis))

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

@@ -37,7 +37,7 @@ module RGame
           @pool.reclaim_if do |child|
             next false unless child.freed?
 
-            node.remove_node(child) # idempotent if the deferred-free sweep already detached it
+            node.remove_node(child)
             true
           end
         end

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

@@ -3,23 +3,45 @@
 module RGame
   module Engine
     module Components
-      # Wraps the node's position toroidally within a rectangle (plus margin), so an
-      # entity leaving one edge reappears on the opposite one. From Body#wrap!. The
-      # bounds are passed in; in a scrolling game they'd come from a scene-scoped
-      # World system instead.
+      # Wraps the node's position toroidally within the world bounds (plus margin), so
+      # an entity leaving one edge reappears on the opposite one.
+      #
+      # The bounds come from the scene's world system — anything answering the
+      # WorldBounds contract, so Components::World or Components::TileWorld — and are
+      # resolved when the node enters the tree. Passing `width:`/`height:` overrides
+      # that for a node whose wrap region is not the whole world.
+      #
+      # The node is tested and placed in **world space**, which is the frame WorldBounds
+      # is stated in: a node under an offset container wraps at the world's edge, not at
+      # an edge shifted by wherever the container sits. The write goes through
+      # Node2D#world_x=, so the node's local position is what actually changes.
+      #
+      # A wrap is a placement, not a step: it does not ask a sibling Mover's `blocked_by`
+      # whether the far edge is free, so a node wrapped onto a blocker is left pressed
+      # against it.
       class ScreenWrap < Engine::Component
-        def initialize(width:, height:, margin: 0.0)
+        def initialize(width: nil, height: nil, margin: 0.0)
           super()
-          @width = width
-          @height = height
+          @given_width = width
+          @given_height = height
           @margin = margin
         end
 
+        # Re-resolved on every entry rather than cached from the first, so a pooled
+        # entity recycled into a differently sized scene wraps against that scene.
+        def on_attach
+          WorldBounds.one_response!(node)
+          @width, @height = WorldBounds.resolve(node, @given_width, @given_height)
+        end
+
         def update(_dt)
-          node.x = @width + @margin if node.x < -@margin
-          node.x = -@margin if node.x > @width + @margin
-          node.y = @height + @margin if node.y < -@margin
-          node.y = -@margin if node.y > @height + @margin
+          x = node.world_x
+          node.world_x = @width + @margin if x < -@margin
+          node.world_x = -@margin if x > @width + @margin
+
+          y = node.world_y
+          node.world_y = @height + @margin if y < -@margin
+          node.world_y = -@margin if y > @height + @margin
         end
       end
     end

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

@@ -3,10 +3,10 @@
 module RGame
   module Engine
     module Components
-      # Draws a single registered image centered on the node's absolute origin. It
-      # passes NO angle to the renderer: Node2D#draw already wraps a node's own draws
-      # in renderer.rotated(abs_angle, abs_x, abs_y), so the node's rotation orients
-      # the sprite — passing an angle here too would rotate it twice.
+      # Draws a single registered image centred on the node's own origin. It passes
+      # NO angle and NO position to the renderer: Node2D#draw has already pushed the
+      # node's transform, so drawing at (0, 0) *is* drawing at the node, correctly
+      # rotated. Passing either would apply it a second time.
       #
       # `scale` is writable so a pooled entity (e.g. a multi-tier rock) can retune it on
       # reset. `z` is the render layer (NOT the node's transform z / abs_z) — kept under
@@ -27,13 +27,19 @@ module RGame
         # Centred on the node's origin and scaled, so the footprint to cull
         # against is the node's box scaled and offset back by half of itself. A
         # node that never set a size is never culled — see Culling.
+        #
+        # Culling is the one thing here still stated in **world** coordinates:
+        # it compares against the camera, which is nowhere near this node's
+        # local space. Drawing is local, culling is world, and the two are
+        # deliberately different arguments.
         def draw(renderer, view)
           width = node.width * @scale
           height = node.height * @scale
-          return if culled?(view, node.abs_x - (width / 2.0), node.abs_y - (height / 2.0),
+          lift = node.elevation
+          return if culled?(view, node.world_x - (width / 2.0), node.world_y - lift - (height / 2.0),
                             width, height)
 
-          renderer.image(@id, node.abs_x, node.abs_y, scale: @scale, z: @layer)
+          renderer.image(@id, 0, -lift, scale: @scale, z: @layer)
         end
       end
     end

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

@@ -3,17 +3,17 @@
 module RGame
   module Engine
     module Components
-      # Picks an enemy for the owning node (a tower) to aim at: each update it queries the
-      # scene's CollisionWorld around the node's world origin and exposes the chosen target
-      # via #target (the enemy node, or nil). The owner reads it to fire — Targeting only
+      # Picks a node for the owning node to aim at: each update it queries the scene's
+      # CollisionWorld around the node's world origin and exposes the chosen target via
+      # #target (the candidate's node, or nil). The owner reads it to act — Targeting only
       # selects, it never moves or shoots.
       #
-      # The CollisionWorld it queries is the same broadphase enemies register with through
-      # their CircleCollider, so targeting needs no enemy list of its own. The `layer`
-      # restricts candidates (a tower wants :enemy, not other towers or projectiles).
+      # The CollisionWorld it queries is the same broadphase every collider registers with,
+      # so targeting needs no candidate list of its own. The `layer` restricts candidates
+      # (pass :enemy to pick only colliders on that layer, not allies or projectiles).
       #
       # Policies (how to choose among the candidates in range):
-      #   - :nearest — the closest enemy (the default; one broadphase nearest-lookup).
+      #   - :nearest — the closest candidate (the default; one broadphase nearest-lookup).
       # More policies (e.g. furthest-along-path) arrive with the state they need.
       class Targeting < Engine::Component
         POLICIES = %i[nearest].freeze
@@ -28,7 +28,7 @@ module RGame
           @target = nil
         end
 
-        # The chosen enemy node, or nil when nothing is in range. Refreshed every update.
+        # The chosen node, or nil when nothing is in range. Refreshed every update.
         attr_reader :target
 
         # Pull the broadphase once it's reachable (scene scope, resolved up the tree).
@@ -41,11 +41,9 @@ module RGame
 
         private
 
-        # Allocation-free: a symbol dispatch over a known-small policy set, each delegating
-        # to an allocation-free CollisionWorld query.
         def pick
           case @policy
-          when :nearest then @world.nearest(node.abs_x, node.abs_y, @range, layer: @layer)
+          when :nearest then @world.nearest(node.world_x, node.world_y, @range, layer: @layer)
           end
         end
       end

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

@@ -26,7 +26,7 @@ module RGame
         end
 
         # The Velocity sibling is only guaranteed present once attached to a node.
-        def on_attach = @velocity = node.get_component(Velocity)
+        def on_attach = @velocity = require_sibling(Velocity)
 
         def control(actions)
           @velocity.spin = actions.axis(@turn_action) * @turn_speed

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

@@ -8,8 +8,19 @@ 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.
+      #
+      # **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 does not draw.** Drawing the map is RGame::Engine::TileMapLayer, one
       # node per Tiled layer, mounted inside the WorldView so the map is drawn
@@ -23,6 +34,8 @@ module RGame
       # draw time. Stop calling `update` and the water freezes, which is what pausing
       # should look like.
       class TileWorld < Engine::Component
+        include WorldBounds
+
         attr_reader :tilemap_id, :elapsed
 
         # `cameras` are the cameras this map bounds — every player's, normally.
@@ -34,18 +47,24 @@ module RGame
           @tilemap_id = tilemap_id
           @elapsed = 0.0
           Array(cameras).each { |camera| bound(camera) }
-          @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
-          )
+        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
 
+        # 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 —
@@ -65,16 +84,25 @@ module RGame
           camera
         end
 
-        # 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)
+        def solid?(col, row) = solid_grid.solid?(col, row)
 
-        def solid?(col, row) = @map.solid_tile?(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
+
+        private
+
+        def solid_grid
+          @solid_grid ||= Util::SolidGrid.build(@map.width, @map.height) { |col, row| @map.solid_tile?(col, row) }
+        end
       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