rgame 0.4.0-x86_64-linux-gnu

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

@@ -0,0 +1,285 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    module Components
+      # What every component that moves its node has in common: a step computed some way
+      # of its own, landing either straight on the node or against whatever may stop it.
+      # CharacterBody, Velocity and PathFollow are the three, and they are three classes
+      # because walking an intent, integrating a velocity and following a path are three
+      # different jobs. What they share is what happens *after* a step is computed, and
+      # that is this class.
+      #
+      # A mover fills in one private hook, `take_step(dt)`, and calls `apply_move(dx, dy)`
+      # from it. `update` is not for overriding: it opens the step, calls the hook and
+      # reports what stopped being in the way, so no mover can forget either edge.
+      #
+      # **Why a base class, and not a sibling component or a Node2D method.** A separate
+      # `Blocking` component that movers write through was tried, and it is order-dependent:
+      # closing the step has to happen after the mover's step, and a sibling can only do
+      # that from its own `update`, which runs wherever it sits in the component list — two
+      # add orders fired on_unblocked on two different ticks. A `Node2D#move_by` owning
+      # `blocked_by` is order-free, but puts collision into the base of every node, HUDs and
+      # menus included. A base class is order-free and touches only what moves.
+      #
+      # ## What stops a step is declared, not subclassed
+      #
+      # `blocked_by:` lists what a step may not pass through, and the default is nothing:
+      # the mover writes the node's position directly and needs no collider and no system
+      # on the scene. That free step is not quite free: `update` → `take_step` →
+      # `apply_move` is one dispatch more than a component writing `node.x` itself, which
+      # measured about 12% on a bare Velocity step (tens of nanoseconds). Inlining the free
+      # write into each subclass wins it back, at the cost of every mover copying
+      # `apply_move`'s free branch and reading this class's ivars — not taken.
+      #
+      #   Velocity.new(vx: 120)                                    # flies wherever it points
+      #   Velocity.new(vx: 120, blocked_by: [:wall])                # stops flush against a :wall collider
+      #   CharacterBody.new(speed: 80, blocked_by: [:tiles])        # slides along the map's solid tiles
+      #   CharacterBody.new(speed: 80, blocked_by: %i[tiles npc])   # ...and does not walk through NPCs
+      #   CharacterBody.new(speed: 80, blocked_by: %i[npc bounds])  # ...and cannot leave the world
+      #
+      # Two names are reserved: **`:tiles`** is the scene's TileWorld, and **`:bounds`** is the
+      # edge of the region the scene's WorldBounds describes. **Every other name is a collider
+      # layer**, resolved against the scene's CollisionWorld: a mover declaring `:npc` is
+      # stopped by any BoxCollider whose `layer` is `:npc`, flush against its edge, exactly the
+      # way a solid tile stops it. A layer that is empty, or whose colliders all leave, is not
+      # an error — the declaration says what *may* stop this mover, not what does.
+      #
+      # `:bounds` is declared rather than automatic, and a mover that does not declare it
+      # leaves the world. Stopping at the edge is one of three responses to it, beside
+      # ScreenWrap and DespawnOffscreen, and a node may carry only one — declaring `:bounds`
+      # beside either raises at attach (WorldBounds.one_response!).
+      #
+      # Blocking is box-versus-box: a CircleCollider on a declared layer reports its contacts
+      # as usual and stops nothing, and a mover that declares anything needs a BoxCollider of
+      # its own.
+      #
+      # The two are not alternatives. `blocked_by` and `on_hit` answer different questions —
+      # what may I pass through, and what am I touching — and a flush-blocked pair does not
+      # overlap, so a mover that must both stop and react needs both.
+      #
+      # A declaration this scene cannot honour raises at on_attach rather than quietly
+      # falling back to free movement — a mover passing through walls looks like a collision
+      # bug, and the cause would be a scene three files away that never mounted the system.
+      #
+      # ## A blocked step slides
+      #
+      # Where a step lands is decided by Engine::CollisionSystem, which resolves X and then Y,
+      # so a diagonal push into a wall keeps the component that is still free. That is the
+      # right feel for a character and the wrong one for a bullet — and a bullet does not
+      # need a different resolver for it, it needs to react: `on_blocked` fires on the step
+      # it hits, and a bullet that queue-frees itself there is gone before it slides anywhere.
+      # One that bounces reads which axis was stopped and turns that half of its velocity:
+      #
+      #   velocity = Velocity.new(vx: 120, vy: 80, blocked_by: %i[wall bounds])
+      #   velocity.on_blocked do |_by, axis|
+      #     velocity.vx = -velocity.vx unless axis == :y
+      #     velocity.vy = -velocity.vy unless axis == :x
+      #   end
+      #
+      # ## The shape has one owner, and it is not this
+      #
+      # A blocked step is resolved against the node's **collider** box, read from the
+      # sibling BoxCollider (FeetCollider is the one a walking character wants). The box is
+      # therefore given once, to the component that *is* a shape, and the same rectangle both
+      # stops the step and reports contacts — there is nothing to hand from one component to
+      # the other and nothing to keep in sync.
+      class Mover < Engine::Component
+        # The two edges of being stopped: on_blocked on the step this mover starts being
+        # stopped by something, on_unblocked on the step it stops. Each fires once per
+        # blocker, so a handler may spend a life or play a sound — the spiky ball that
+        # both stops the player and hurts them is the two signals plus an on_hit.
+        #
+        # The listener gets whatever stopped the step and reads its #layer and #node, so
+        # one handler covers every kind: a collider answers its own layer and its owning
+        # node, the map's solid tiles answer :tiles and nil (Engine::TileBlockers::TILES),
+        # and the world's edge answers :bounds and nil.
+        #
+        # on_blocked also says which axis of the step it stopped — :x, :y, or :both when one
+        # blocker stopped the two at once — which is what a bounce branches on. A listener
+        # that names only the blocker, `{ |by| ... }`, never sees it: a block drops the
+        # arguments it does not name.
+        #
+        # on_unblocked has no axis, because what ends is a blocker stopping this mover, not
+        # an axis. A blocker that stopped x on one step and y on the next was in the way the
+        # whole time, and ends once.
+        signal :on_blocked, Engine::Signal.define(:by, :axis)
+        signal :on_unblocked, Engine::Signal.define(:by)
+
+        TILES  = :tiles
+        BOUNDS = :bounds
+        RESERVED = [TILES, BOUNDS].freeze
+
+        def initialize(blocked_by: [])
+          super()
+          @blocked_by = Array(blocked_by)
+          @collider = nil
+          @collision = nil
+          @last_move_blocked = false
+          @stopped_by = Engine::ContactSet.new
+        end
+
+        # Resolve each declared blocker and build the resolver that runs them, once the node
+        # is in the tree and both the scene's systems and this node's other components are
+        # reachable.
+        #
+        # **The resolver is the mover's own**, rather than something borrowed off the scene.
+        # It has to be: a source over other colliders holds this mover's collider and this
+        # mover's layer list, so two movers declaring different `blocked_by` cannot share
+        # one — and a scene may mount a CollisionWorld with no TileWorld at all, so there is
+        # not always a scene-level resolver to borrow in the first place. What is shared is
+        # what can be: the TileWorld's own source is borrowed, not rebuilt.
+        #
+        # Nothing here runs on a frame. The list is built once, and a step only walks it.
+        #
+        # A subclass that needs its own attach work calls `super` first — PathFollow does,
+        # to place its node before walking.
+        def on_attach
+          @stopped_by.reset
+          return if @blocked_by.empty?
+
+          WorldBounds.one_response!(node) if blocked_by?(BOUNDS)
+
+          @collider = require_sibling(BoxCollider)
+          @collision = Engine::CollisionSystem.new(blockers: resolve_blockers)
+        end
+
+        # Take this step, then report what stopped being in the way.
+        #
+        # **The set advances once per update, not once per apply_move**, and that is what
+        # makes standing still an unblocking: a mover that stops pushing into something
+        # records nothing this step, so what it was pressing against ends and on_unblocked
+        # fires. It also keeps the bookkeeping where a subclass cannot lose it — a mover
+        # that resolves a step in several moves, or overrides apply_move, still opens the
+        # step once and still reports its edges.
+        def update(dt)
+          return take_step(dt) unless @collision
+
+          @stopped_by.begin_frame
+          take_step(dt)
+          @stopped_by.each_ended { on_unblocked_signal.emit(it) }
+        end
+
+        # Which way this mover's step is going, each axis in -1..1, and 0, 0 when it is not
+        # trying to move. A facing rather than a velocity: a mover pressed into a wall still
+        # heads into it, so an AnimatedSprite keeps walking against the wall rather than
+        # standing. Each subclass answers from what its step is computed out of.
+        def heading_x = 0.0
+        def heading_y = 0.0
+
+        # Whether `name` is one of the things this mover declared it may be stopped by.
+        def blocked_by?(name) = @blocked_by.include?(name)
+
+        # Where a step lands. Public, and kept separate from `take_step`, so a mover that
+        # resolves a step some other way — a platformer's CharacterBody, with gravity and a
+        # jump — inherits everything around it rather than restating it.
+        #
+        # The branch is on what was declared rather than on a subclass: an unblocked mover
+        # writes straight to the node, and a blocked one hands *itself* to its resolver as
+        # the actor being moved (see the adapter below).
+        def apply_move(dx, dy)
+          unless @collision
+            node.x += dx
+            node.y += dy
+            return
+          end
+
+          @collision.move(self, dx, dy)
+          blocked_x = @collision.blocked_x
+          blocked_y = @collision.blocked_y
+          @last_move_blocked = !(blocked_x.nil? && blocked_y.nil?)
+          if blocked_x.equal?(blocked_y)
+            record_blocker(blocked_x, :both)
+          else
+            record_blocker(blocked_x, :x)
+            record_blocker(blocked_y, :y)
+          end
+        end
+
+        # The actor adapter CollisionSystem#move drives: it reads x/y/collision_box, works
+        # out where the step lands, and writes the resolved position back. The box is the
+        # sibling collider's — the node's one shape, so retuning `collider.box` retunes
+        # what a step collides with.
+        #
+        # ## The adapter is in world space
+        #
+        # x and y are the node's **world** position, because that is the space everything
+        # else about collision is already in: the tile grid is a world-coordinate grid, and
+        # BoxCollider#aabb_x reports `node.world_x + box.offset_x`. A mover under an offset
+        # ancestor that reported its local position would resolve against a map shifted by
+        # the ancestor, and would be compared against other colliders in a different frame
+        # entirely.
+        #
+        # Writing goes back through Node2D#world_x= / #world_y=, which turn the resolved world
+        # position into the local one the node actually lives in.
+        #
+        # A mover under a rotated ancestor is still outside what an axis-aligned box supports
+        # (docs/api/components.md: a thing that spins wants a circle) — the position it lands
+        # at is exact, but the box it was resolved with does not turn with the frame.
+        def collision_box = @collider.box
+        def x = node.world_x
+        def y = node.world_y
+
+        def x=(value)
+          node.world_x = value
+        end
+
+        def y=(value)
+          node.world_y = value
+        end
+
+        private
+
+        def take_step(_dt) = nil
+
+        def blocking? = !@collision.nil?
+
+        def last_move_blocked? = @last_move_blocked
+
+        def record_blocker(by, axis)
+          return if by.nil? || @stopped_by.touching?(by)
+
+          started = @stopped_by.started?(by)
+          @stopped_by.add(by)
+          on_blocked_signal.emit(by:, axis:) if started
+        end
+
+        def resolve_blockers
+          sources = []
+          sources << tile_blockers if @blocked_by.include?(TILES)
+          sources << bounds_blockers if @blocked_by.include?(BOUNDS)
+          layers = @blocked_by.reject { RESERVED.include?(it) }
+          sources << actor_blockers(layers) unless layers.empty?
+          sources
+        end
+
+        def tile_blockers
+          world = node.system(TileWorld) ||
+                  raise("#{mover_name} is blocked_by :tiles, and the scene has no TileWorld " \
+                        'system to resolve a step against. Mount one, or drop blocked_by for ' \
+                        'a mover with nothing to collide with.')
+          world.blockers
+        end
+
+        def bounds_blockers
+          bounds = node.system(WorldBounds) ||
+                   raise("#{mover_name} is blocked_by :bounds, and the scene has no world " \
+                         'bounds to stop at. Mount a World (or a TileWorld, which is one), or ' \
+                         'drop :bounds for a mover that may leave the world.')
+          Engine::BoundsBlockers.new(bounds: bounds)
+        end
+
+        def actor_blockers(layers)
+          world = node.system(CollisionWorld) ||
+                  raise("#{mover_name} is blocked_by #{layers.map(&:inspect).join(', ')}, which " \
+                        'names collider layers, and the scene has no CollisionWorld system to ' \
+                        'find them in. Mount one, or drop those names for a mover that only ' \
+                        'the map stops.')
+          Engine::ActorBlockers.new(world: world, owner: @collider, layers: layers)
+        end
+
+        def mover_name = self.class.name&.split('::')&.last || self.class.inspect
+      end
+    end
+  end
+end

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

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+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 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.
+      #
+      # ## 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(speed:, path: nil, blocked_by: [])
+          super(blocked_by: blocked_by)
+          @path = path
+          @speed = speed
+          restart
+        end
+
+        def finished? = @finished
+
+        # Restart the walk as the node enters the tree — back to the first waypoint, with
+        # 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
+          super
+          restart
+        end
+
+        # 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
+
+        def advance_to_end?(remaining)
+          while remaining.positive?
+            left = @path.segment_length(@segment) - @distance
+            if remaining < left
+              @distance += remaining
+              return false
+            end
+            remaining -= left
+            @segment += 1
+            @distance = 0.0
+            return true if @segment >= @path.count - 1
+          end
+          false
+        end
+
+        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
+          @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
+      end
+    end
+  end
+end

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

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    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; 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()
+          @x_axis = x_axis
+          @y_axis = y_axis
+        end
+
+        def on_attach = @body = require_sibling(CharacterBody)
+
+        def control(actions)
+          @body.set_intent(actions.axis(@x_axis), actions.axis(@y_axis))
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    module Components
+      # Wraps an Engine::Pool of nodes and folds the tree bookkeeping into the frame tick:
+      # `spawn` takes a node from the pool (recycled or freshly built) and adds it as a
+      # child of the owner, and `update` returns freed nodes to the pool — so a game only
+      # ever writes `pool.spawn` and the ordinary `node.queue_free`, never a hand-written
+      # acquire/add/reclaim bridge. Pooled nodes are normal children, so the scene's usual
+      # traversal updates and draws them; this component only manages their pool membership.
+      #
+      #   pool = add_component(Engine::Components::Pool.new { Enemy.new(path: @path) })
+      #   pool.spawn                       # acquire + add as a child
+      #   pool.spawn { |b| b.reset(x, y) } # reset before it enters the tree (projectiles)
+      #   enemy.queue_free                 # → reclaimed back to the pool automatically
+      #
+      # Add it named (`as:`) like any component when a node needs more than one pool.
+      class Pool < Engine::Component
+        def initialize(&)
+          super()
+          @pool = Engine::Pool.new(&)
+        end
+
+        # Take a node from the pool, let the caller re-initialise it before it goes live
+        # (optional block — runs before on_attach), and add it as a child of the owner.
+        def spawn
+          child = @pool.acquire
+          yield child if block_given?
+          node.add_node(child)
+          child
+        end
+
+        # Ride the tick: return every freed pooled node to the free list, detaching any that
+        # are still in the tree — so a queue_free elsewhere recycles with no game-side wiring.
+        def update(_dt)
+          @pool.reclaim_if do |child|
+            next false unless child.freed?
+
+            node.remove_node(child)
+            true
+          end
+        end
+
+        def size = @pool.size
+
+        # True when no spawned node is currently live (all reclaimed) — a scene reads this to
+        # tell when a wave/round has been fully cleared.
+        def empty? = @pool.empty?
+      end
+    end
+  end
+end