rgame 0.1.0 → 0.3.0

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

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    module Components
+      # A PathFollow that makes its own paths: `go_to(world_x, world_y)` plans a route
+      # over the scene's tile map to the cell containing that point, and walks it.
+      #
+      # Planning is three steps. The scene's TileWorld#nav_grid finds the cheapest route
+      # of cells; the route is **string-pulled** into as few straight segments as the
+      # node's own collider can travel; and those corners become the Engine::Path this
+      # component walks, exactly as a PathFollow walks one it was handed.
+      #
+      # ## The route is checked against what will stop the walk
+      #
+      # A segment is kept only if the map's own blocker source — TileWorld#blockers, the
+      # object a mover declaring `:tiles` resolves its steps against — lets the collider
+      # box travel it. A test on cells alone would keep a diagonal past a solid tile's
+      # corner that a point clears and a 12x6 feet box clips, and a PathFollow does not
+      # slide: the walker would stand at that corner.
+      #
+      # The question is TileBlockers#travel?, which holds for a walker stepping under a
+      # quarter tile at a time — 240 px/s at 60 ticks a second on 16 px tiles.
+      #
+      # Smoothing is greedy: from each corner it extends the segment cell by cell until the
+      # next cell would not be clear, and turns there. The next cell after a corner is taken
+      # without asking, which is sound only for a collider **no larger than a tile** on
+      # either axis — so `go_to` refuses a larger one rather than plan a route it may stall on.
+      #
+      # So what is walked is measured from the **anchor** — the centre of the sibling
+      # BoxCollider's box, or the node's origin on a node with none — and a route ends
+      # with the anchor on the centre of the target cell.
+      #
+      # ## What it does not do
+      #
+      # It does not replan. A route is planned against the map, and the map is all it
+      # knows: a walker declaring other colliders in `blocked_by` waits behind one on its
+      # route, the way any PathFollow waits, and a game that wants it to go round calls
+      # `go_to` again.
+      #
+      # The route is planned in world space and walked in the node's parent's space, which
+      # agree under an unrotated ancestor chain — the same limit a blocked Mover has.
+      class Navigator < PathFollow
+        # The cells of the last route `go_to` planned, start to target, before smoothing —
+        # `[[col, row], ...]`, or nil before the first one. For drawing; `path` is what is
+        # walked.
+        attr_reader :cells
+
+        def initialize(speed:, blocked_by: [])
+          super
+          @cells = nil
+        end
+
+        def on_attach
+          super
+          @world = node.system(TileWorld) ||
+                   raise("#{mover_name} plans routes over the scene's TileWorld, and the scene " \
+                         'has none. Mount one, or use a PathFollow and hand it a path.')
+          @anchor = node.get_component(BoxCollider)
+        end
+
+        # Plan from where the node stands to the cell containing (world_x, world_y), and
+        # start walking it from the node's current position — so a walker already on a
+        # route turns onto the new one without a jump. Returns true.
+        #
+        # Returns false, and leaves whatever the node was doing alone, when there is no
+        # route: the target is solid, outside the map, or cut off from the node.
+        #
+        # Raises ArgumentError when the node's collider is wider or taller than a tile:
+        # pathfinding for such a collider is not supported.
+        #
+        # rubocop:disable Naming/PredicateMethod -- a command that reports whether it could be
+        # carried out, not a question; `go_to?` would read as "may I go there?".
+        def go_to(world_x, world_y)
+          unless @world
+            raise "#{mover_name}#go_to plans over the scene's TileWorld, so the node has to be " \
+                  'in the tree first.'
+          end
+
+          measure_anchor
+          refuse_a_box_larger_than_a_tile
+          cells = @world.nav_grid.find(*cell_at(@anchor_x, @anchor_y), *cell_at(world_x, world_y))
+          return false unless cells
+
+          @cells = cells
+          follow(Engine::Path.new(waypoints(corners(cells))))
+          true
+        end
+        # rubocop:enable Naming/PredicateMethod
+
+        private
+
+        def measure_anchor
+          box = @anchor&.box
+          @box_w = box ? box.width : 0
+          @box_h = box ? box.height : 0
+          @anchor_x = node.world_x + (box ? box.offset_x + (@box_w / 2.0) : 0.0)
+          @anchor_y = node.world_y + (box ? box.offset_y + (@box_h / 2.0) : 0.0)
+        end
+
+        def refuse_a_box_larger_than_a_tile
+          return if @box_w <= @world.tile_width && @box_h <= @world.tile_height
+
+          raise ArgumentError, "#{mover_name}#go_to plans for a collider no larger than a tile, and this " \
+                               "node's is #{@box_w}x#{@box_h} over #{@world.tile_width}x" \
+                               "#{@world.tile_height} tiles. Pathfinding for a larger collider is not supported."
+        end
+
+        def cell_at(x, y) = [(x / @world.tile_width).floor, (y / @world.tile_height).floor]
+
+        def centre_x(cell) = (cell[0] + 0.5) * @world.tile_width
+        def centre_y(cell) = (cell[1] + 0.5) * @world.tile_height
+
+        def corners(cells)
+          corners = [[@anchor_x, @anchor_y]]
+          turn = -1
+          while turn < cells.length - 1
+            turn = furthest_clear(*corners.last, cells, turn + 1)
+            corners << [centre_x(cells[turn]), centre_y(cells[turn])]
+          end
+          corners
+        end
+
+        def furthest_clear(x, y, cells, index)
+          index += 1 while index < cells.length - 1 &&
+                           box_travels?(x, y, centre_x(cells[index + 1]), centre_y(cells[index + 1]))
+          index
+        end
+
+        def box_travels?(from_x, from_y, to_x, to_y)
+          @world.blockers.travel?(from_x - (@box_w / 2.0), from_y - (@box_h / 2.0), @box_w, @box_h,
+                                  to_x - from_x, to_y - from_y)
+        end
+
+        def waypoints(corners)
+          shift_x = node.x - @anchor_x
+          shift_y = node.y - @anchor_y
+          points = corners.map { |(x, y)| [x + shift_x, y + shift_y] }
+          points[0] = [node.x, node.y]
+          points
+        end
+      end
+    end
+  end
+end

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,16 +3,18 @@
 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
       # @layer to say so. For an animated sprite (sheet + frame index driving
       # renderer.sprite), add a sibling AnimatedSprite component later.
       class Sprite < Engine::Component
+        include Engine::Culling
+
         attr_accessor :scale
 
         def initialize(id:, scale: 1.0, z: 0)
@@ -22,8 +24,22 @@ module RGame
           @layer = z
         end
 
-        def draw(renderer)
-          renderer.image(@id, node.abs_x, node.abs_y, scale: @scale, z: @layer)
+        # 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
+          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, 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