rgame 0.2.0 → 0.3.0

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

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    module Components
+      # A rectangular collision shape on a node — the sibling of CircleCollider for
+      # entities that are honestly box-shaped (a crate, a platform, a wall segment).
+      # It registers itself with the scene's CollisionWorld when it enters the tree
+      # and unregisters on leaving, so a spawned/despawned entity can't leak a
+      # registration. A scene with no world mounted leaves it a bare shape (see
+      # on_attach).
+      #
+      # The rectangle is an Engine::CollisionBox: an offset + size relative to the
+      # node's origin, so a 32x32 sprite can carry a small box at its feet —
+      # FeetCollider is the subclass that works that offset out for you. The `layer`
+      # is an opaque tag the game reads in its on_hit handler to decide what a contact
+      # means. See docs/api/systems.md.
+      #
+      # The box stays axis-aligned in world space: it does not rotate with the node.
+      # That is what an AABB buys — a spinning entity wants a CircleCollider, which
+      # is rotation-invariant, rather than a per-frame box recompute.
+      class BoxCollider < Engine::Component
+        # The two edges of a contact, fired by CollisionWorld: on_hit on the step this
+        # collider starts overlapping another, on_separated on the step it stops. Each
+        # fires once per pair, so a handler may count, play a sound or spend a life.
+        # The listener gets the other collider and reads its #layer / #node to react.
+        signal :on_hit, Engine::Signal.define(:other)
+        signal :on_separated, Engine::Signal.define(:other)
+
+        # box is writable so a pooled entity can retune its shape on reset — assign any
+        # CollisionBox, CollisionBox.bottom_anchored(...) included. CollisionWorld reads
+        # it fresh each frame, so no re-registration.
+        attr_accessor :box
+        attr_reader :layer
+
+        # CollisionWorld's per-collider bookkeeping: who this was touching this step and
+        # last. The world owns what goes in it; nothing else should write to it.
+        attr_reader :contacts
+
+        def initialize(width:, height:, offset_x: 0, offset_y: 0, layer: :default)
+          super()
+          @box = Engine::CollisionBox.new(width:, height:, offset_x:, offset_y:)
+          @layer = layer
+          @contacts = Engine::ContactSet.new
+        end
+
+        # A collider is a *shape*; a CollisionWorld is what turns shapes into contacts. So
+        # a scene with no world mounted leaves this a bare shape instead of raising, which
+        # is what a tile-only game wants: its character's feet box stops its steps (that is
+        # a Mover's `blocked_by`) and there are no pairs to report to anyone.
+        #
+        # The cost is that an on_hit handler in such a scene never fires and nothing says
+        # so. That is the trade taken deliberately: what declares "I expect to be stopped"
+        # is `blocked_by`, and that *does* raise for a system it cannot find.
+        def on_attach = node.system(CollisionWorld)&.register(self)
+        def on_detach = node.system(CollisionWorld)&.unregister(self)
+
+        # The broadphase AABB in world space, one component per call rather than
+        # CollisionBox#aabb's Array: CollisionWorld reads these for every collider
+        # every frame, and that path may not allocate.
+        #
+        # These go through `box` rather than @box so a subclass that builds its shape
+        # lazily — FeetCollider, which cannot know the node's size until the tree is
+        # live — is seen by the broadphase too. An attr_reader call allocates nothing.
+        def aabb_x = node.world_x + box.offset_x
+        def aabb_y = node.world_y + box.offset_y
+        def aabb_w = box.width
+        def aabb_h = box.height
+
+        # World-space centre of the box — what CollisionWorld's range queries measure
+        # from, so a box collider is targetable on the same terms as a circle. Note it
+        # is the box's centre, not the node's origin, which is where a circle's is.
+        def cx = aabb_x + (box.width / 2.0)
+        def cy = aabb_y + (box.height / 2.0)
+
+        # Narrowphase, first half of the double dispatch: hand this shape's numbers to
+        # the *other* collider and let it pick the test, so neither side has to ask what
+        # kind the other is. CircleCollider#overlap? is the mirror image.
+        def overlap?(other) = other.overlap_box?(aabb_x, aabb_y, aabb_w, aabb_h)
+
+        # Second half: the two tests another collider dispatches into.
+        #
+        # @api private
+        def overlap_box?(x, y, w, h)
+          Engine::CollisionBox.overlap?(aabb_x, aabb_y, aabb_w, aabb_h, x, y, w, h)
+        end
+
+        # @api private
+        def overlap_circle?(x, y, r)
+          Engine::CollisionBox.overlap_circle?(aabb_x, aabb_y, aabb_w, aabb_h, x, y, r)
+        end
+
+        # Called by CollisionWorld on each edge (the signals' emit is otherwise private).
+        def emit_hit(other) = on_hit_signal.emit(other)
+        def emit_separated(other) = on_separated_signal.emit(other)
+      end
+    end
+  end
+end

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

@@ -29,14 +29,15 @@ module RGame
           @offset_y = offset_y
         end
 
-        # Reads the absolute origin resolved at the top of this node's update,
-        # so the camera trails the node's own movement by one step (a couple of
+        # A node runs its components before its own `on_update`, so this reads
+        # the node's world position from before whatever moves it this tick, and
+        # the camera trails the node's own movement by one step (a couple of
         # pixels at walking speed). That is deliberate and uniform: everything
         # drawn through this camera trails equally, so nothing drifts apart on
-        # screen, and the alternative — re-resolving here — would put this
-        # component's ordering among its siblings on show.
+        # screen. Reading it later — from the node's own hook, say — would put
+        # this component's ordering among its siblings on show instead.
         def update(_dt)
-          @camera.center_on(node.abs_x + @offset_x, node.abs_y + @offset_y)
+          @camera.center_on(node.world_x + @offset_x, node.world_y + @offset_y)
         end
       end
     end

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

@@ -3,48 +3,33 @@
 module RGame
   module Engine
     module Components
-      # Walking movement for a tile-bound actor (player or NPC). A controller writes a
-      # per-step movement intent — each axis in -1..1 — and this component turns it into
-      # a real move each update, resolved against the scene's TileWorld so the actor
-      # slides along walls and stays inside the map. Distinct from Velocity (which
-      # integrates blindly): here every step is collision-checked.
+      # Direct, per-step movement for a walking actor (player or NPC). A controller writes a
+      # movement intent — each axis in -1..1 — and this component turns it into a real move
+      # each update, at a fixed speed and with no inertia (unlike Velocity, which integrates
+      # a velocity the controller sets, and ThrustController, which accelerates one).
       #
-      # The intent doubles as the facing for AnimatedSprite (move_x / move_y readers), so
+      # The intent doubles as the mover's heading, which is what AnimatedSprite faces by, so
       # a character is just CharacterBody + a controller + AnimatedSprite.
       #
-      # The feet box is built from the node's dimensions (which AnimatedSprite sets from the
-      # sprite frame), not a passed-in sprite size — `feet_width`/`feet_height` are the box,
-      # centred horizontally and anchored to the node's bottom. It's built lazily on first
-      # use (the first update, after every on_attach has run), so the order components are
-      # added in doesn't matter. A body with no sprite must set the node's width/height.
-      class CharacterBody < Engine::Component
+      # What may stop a step — `blocked_by:`, `on_blocked` / `on_unblocked`, and the
+      # `apply_move` seam — is Mover's, and shared with every other component that moves a
+      # node; see its header. What is this class's own is the intent and the speed.
+      #
+      #   CharacterBody.new(speed: 80)                             # walks wherever the intent points
+      #   CharacterBody.new(speed: 80, blocked_by: %i[tiles npc])   # stopped by the map and by NPCs
+      class CharacterBody < Mover
         attr_reader :move_x, :move_y
 
-        def initialize(feet_width:, feet_height:, speed:)
-          super()
-          @feet_width = feet_width
-          @feet_height = feet_height
+        def initialize(speed:, blocked_by: [])
+          super(blocked_by: blocked_by)
           @speed = speed
           @move_x = 0.0
           @move_y = 0.0
-          @collision_box = nil
-        end
-
-        # The feet box, derived from the node's sprite size and memoised.
-        #
-        # **Only valid once the node is in the tree**, and it says so rather than
-        # letting you find out later. The size comes from AnimatedSprite#on_attach,
-        # so a read from a constructor sees a 0x0 node and bakes a box anchored to
-        # nothing — permanently, because this memoises, and for the collision
-        # system too, because it reads the same box. The symptom is an actor that
-        # walks through walls it should not, a long way from the call that caused
-        # it. Guarding costs one comparison, once.
-        def collision_box
-          @collision_box ||= build_collision_box
         end
 
-        # The TileWorld is a scene-scoped system, reachable once we're in the tree.
-        def on_attach = @world = node.system(TileWorld)
+        # The heading is the intent as set, blocked or not.
+        def heading_x = @move_x
+        def heading_y = @move_y
 
         # Set this step's movement intent; each axis is in -1..1.
         def set_intent(intent_x, intent_y)
@@ -52,38 +37,12 @@ module RGame
           @move_y = intent_y
         end
 
-        def update(dt)
-          return if @move_x.zero? && @move_y.zero?
-
-          @world.move(self, @move_x * @speed * dt, @move_y * @speed * dt)
-        end
-
-        # CollisionSystem#move drives an "actor" through x/y/collision_box and writes the
-        # resolved position back — back those by the owning node's transform.
-        def x = node.x
-        def y = node.y
-
-        def x=(value)
-          node.x = value
-        end
-
-        def y=(value)
-          node.y = value
-        end
-
         private
 
-        def build_collision_box
-          if node.width.zero? || node.height.zero?
-            raise "collision_box needs the node's sprite size, but it is " \
-                  "#{node.width}x#{node.height}. AnimatedSprite sets that when it attaches, so " \
-                  'read this after the node is in the tree, not while building it.'
-          end
+        def take_step(dt)
+          return if @move_x.zero? && @move_y.zero?
 
-          Engine::CollisionBox.bottom_anchored(
-            sprite_width: node.width, sprite_height: node.height,
-            width: @feet_width, height: @feet_height
-          )
+          apply_move(@move_x * @speed * dt, @move_y * @speed * dt)
         end
       end
     end

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

@@ -6,38 +6,74 @@ module RGame
       # A circular collision shape on a node. It registers itself with the scene's
       # CollisionWorld system when it enters the tree and unregisters on leaving —
       # the engine fires both hooks, so a spawned/despawned entity can't leak a
-      # registration. Its world centre is the node's resolved absolute origin; the
+      # registration. Its world centre is the node's world origin; the
       # `layer` is an opaque tag the game reads in its on_hit handler to decide what a
-      # contact means (bullet-vs-rock, etc.). See docs/api/systems.md.
+      # contact means. See docs/api/systems.md.
+      #
+      # BoxCollider is the rectangular sibling, and the two collide with each other:
+      # both answer the same broadphase (#aabb_*) and narrowphase (#overlap?) protocol.
       class CircleCollider < Engine::Component
-        # Fired by CollisionWorld for each overlapping collider; the listener gets the
-        # other collider and reads its #layer / #node to react.
+        # The two edges of a contact, fired by CollisionWorld: on_hit on the step this
+        # collider starts overlapping another, on_separated on the step it stops. Each
+        # fires once per pair, so a handler may count, play a sound or spend a life.
+        # The listener gets the other collider and reads its #layer / #node to react.
         signal :on_hit, Engine::Signal.define(:other)
+        signal :on_separated, Engine::Signal.define(:other)
 
         # radius is writable so a pooled entity (e.g. a multi-tier rock) can retune its
         # shape on reset; CollisionWorld reads it fresh each frame, so no re-registration.
         attr_accessor :radius
         attr_reader :layer
 
+        # CollisionWorld's per-collider bookkeeping: who this was touching this step and
+        # last. The world owns what goes in it; nothing else should write to it.
+        attr_reader :contacts
+
         def initialize(radius:, layer: :default)
           super()
           @radius = radius
           @layer = layer
+          @contacts = Engine::ContactSet.new
         end
 
-        def on_attach = node.system(CollisionWorld).register(self)
+        # A collider is a *shape*; a CollisionWorld is what turns shapes into contacts.
+        # A scene with no world mounted therefore leaves this a bare shape rather than
+        # raising — BoxCollider#on_attach says why, and it is the same trade here.
+        def on_attach = node.system(CollisionWorld)&.register(self)
         def on_detach = node.system(CollisionWorld)&.unregister(self)
 
-        # World-space centre — the node's resolved absolute origin.
-        def cx = node.abs_x
-        def cy = node.abs_y
+        # World-space centre — the node's own origin, in world coordinates.
+        def cx = node.world_x
+        def cy = node.world_y
+
+        # The circle's bounding box, one component per call rather than an Array:
+        # CollisionWorld reads these for every collider every frame, and that path may
+        # not allocate.
+        def aabb_x = cx - @radius
+        def aabb_y = cy - @radius
+        def aabb_w = @radius * 2
+        def aabb_h = @radius * 2
+
+        # Narrowphase, first half of the double dispatch: hand this shape's numbers to
+        # the *other* collider and let it pick the test, so neither side has to ask what
+        # kind the other is. BoxCollider#overlap? is the mirror image.
+        def overlap?(other) = other.overlap_circle?(cx, cy, @radius)
+
+        # Second half: the two tests another collider dispatches into.
+        #
+        # @api private
+        def overlap_circle?(x, y, r)
+          Engine::CircleCollider.overlap?(cx, cy, @radius, x, y, r)
+        end
 
-        def overlap?(other)
-          Engine::CircleCollider.overlap?(cx, cy, @radius, other.cx, other.cy, other.radius)
+        # @api private
+        def overlap_box?(x, y, w, h)
+          Engine::CollisionBox.overlap_circle?(x, y, w, h, cx, cy, @radius)
         end
 
-        # Called by CollisionWorld on contact (the signal's emit is otherwise private).
+        # Called by CollisionWorld on each edge (the signals' emit is otherwise private).
         def emit_hit(other) = on_hit_signal.emit(other)
+        def emit_separated(other) = on_separated_signal.emit(other)
       end
     end
   end

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

@@ -5,10 +5,31 @@ module RGame
     module Components
       # Scene-scoped broadphase collision system: a Component that lives on the scene
       # node (so it is born and torn down with the scene, and rides the normal update
-      # traversal). CircleColliders register/unregister with it via their tree
-      # lifecycle; each update it buckets them in a SpatialHash and fires on_hit on
-      # every overlapping pair. It is layer-agnostic — it reports contacts and lets
-      # the colliders' owners decide meaning. See docs/api/systems.md.
+      # traversal). Colliders register/unregister with it via their tree lifecycle;
+      # each update it buckets them in a SpatialHash and reports every overlapping
+      # pair. It is layer-agnostic — it reports contacts and lets the colliders'
+      # owners decide meaning. See docs/api/systems.md.
+      #
+      # **A contact is reported as two edges, not as a state.** `on_hit` fires on the
+      # step a pair starts overlapping and `on_separated` on the step it stops, each
+      # once, on both colliders. Nothing fires in between, so a handler is free to
+      # count, to play a sound, or to do anything else that must happen once — which
+      # is the whole reason the world keeps a ContactSet per collider rather than
+      # simply forwarding what the broadphase found.
+      #
+      # It is also *shape*-agnostic, which is what lets CircleCollider and BoxCollider
+      # share it (and collide with each other). A collider is anything answering:
+      #
+      #   aabb_x, aabb_y, aabb_w, aabb_h  its world-space bounding box, for bucketing
+      #   cx, cy                          its centre, for the range queries below
+      #   overlap?(other)                 the narrowphase, which the two colliders
+      #                                   settle between themselves by double dispatch
+      #   layer, node                     the tag and the owner
+      #   contacts                        an Engine::ContactSet, which this drives
+      #   emit_hit(other)                 the contact's two edges
+      #   emit_separated(other)
+      #
+      # None of those may allocate: they run per collider per frame.
       class CollisionWorld < Engine::Component
         def initialize(cell_size:)
           super()
@@ -16,13 +37,22 @@ module RGame
           @colliders = []
         end
 
-        def register(collider) = @colliders << collider
+        # Reset rather than merely add: the collider may be a pooled one coming back
+        # from the dead, still carrying the contacts it held when it was freed.
+        def register(collider)
+          collider.contacts.reset
+          @colliders << collider
+        end
+
+        # The partners of a collider that leaves are told on their next step, by the
+        # ordinary separation pass — it is gone from the index, so the pair no longer
+        # overlaps. Nothing has to be emitted here.
         def unregister(collider) = @colliders.delete(collider)
 
         # Yield every registered collider whose centre lies within `r` of (x, y), using
         # the spatial index built by the most recent #update. The narrowphase is a
-        # centre-distance test — the query is a point + range (a tower's range ring), so
-        # the collider's own radius isn't added in. Colliders whose node is queued for
+        # centre-distance test — the query is a point + range (a turret's range ring), so
+        # the collider's own size isn't added in. Colliders whose node is queued for
         # removal are skipped. As with SpatialHash#query a collider spanning several cells
         # may be yielded more than once, so callers that *select* (e.g. #nearest) are
         # written dup-insensitively. Layer-agnostic — filter by `collider.layer` in the
@@ -38,8 +68,47 @@ module RGame
           end
         end
 
+        # Yield every registered collider bucketed in a cell the region covers, skipping
+        # those whose node is queued for removal. The rectangular counterpart to
+        # #query_circle, and what a blocker source asks when it resolves a step: "what is
+        # near this box".
+        #
+        # It inherits #query_circle's dedup contract — a collider spanning several cells
+        # may be yielded more than once — so a caller that *selects* is written
+        # dup-insensitively, the way #nearest and Engine::ActorBlockers both are. Unlike
+        # #query_circle there is no narrowphase here at all: the bucket walk is the whole
+        # answer, and refining it is the caller's business. Layer-agnostic; filter by
+        # `collider.layer` in the block. Allocation-free.
+        def query_box(x, y, w, h)
+          @hash.query(x, y, w, h) do |collider|
+            next if collider.node.freed?
+
+            yield collider
+          end
+        end
+
+        # Re-bucket a collider that has moved since #update built the index, so a query
+        # later in the same step still finds it where it now is. `from_*` is the box it
+        # was bucketed at — the caller knows it, which is what lets the index keep no
+        # per-item state of its own.
+        #
+        # This is what makes a mid-step query exact rather than nearly right. Buckets are
+        # filled once per step and a collider that moves afterwards is still bucketed
+        # where it was, so a query over cells it has left does not reach it. Measured over
+        # 60,000 queries at two hundred actors: 116 misses left stale, 0 re-indexed, and
+        # padding the query instead is not exact at any pad — it compensates for the
+        # *other* actor's staleness by inflating the *mover's* step. Engine::CollisionSystem
+        # calls this through a blocker source's #moved, so nothing a game writes has to
+        # remember it; anything else that moves a collider mid-step may call it directly.
+        #
+        # Allocation-free, so a resolver may call it every step.
+        def reindex(collider, from_x, from_y, from_w, from_h)
+          @hash.remove(collider, from_x, from_y, from_w, from_h)
+          insert(collider)
+        end
+
         # The registered collider nearest to (x, y) within range `r`, or nil when none
-        # qualifies. Restrict to a single `layer:` (the common case: a tower targeting only
+        # qualifies. Restrict to a single `layer:` (the common case: a turret targeting only
         # :enemy). Dup-safe — it keeps the running minimum, so #query_circle's possible
         # multi-cell repeats don't matter. Allocation-free.
         def nearest(x, y, r, layer: nil)
@@ -59,15 +128,64 @@ module RGame
           best
         end
 
+        # Is the cell containing the *world* point (x, y) free — "may a pickup spawn on
+        # this square?" A point, not a region: pass any coordinate inside the square you
+        # mean. The cells are the broadphase's own, so set `cell_size` to the game's
+        # square and the two grids line up.
+        #
+        # Two coordinate gotchas, both easy to get wrong from a node that has neither in
+        # mind:
+        #
+        # - The index holds **world** coordinates, because that is what a collider
+        #   reports. A node whose own grid starts somewhere else adds its world origin
+        #   before asking (`node.world_x + col * cell_size`) — and puts that origin on a
+        #   multiple of `cell_size`, since the cells are the hash's own lattice anchored
+        #   at the world origin. A board off that lattice has each square straddling two
+        #   cells, and both read occupied.
+        # - It answers about the index the most recent #update built, exactly as
+        #   #query_circle and #nearest do. Before the first update every cell is empty.
+        #
+        # The bucket is the answer, geometry and all: the broadphase's cell walk is
+        # half-open exactly like CollisionBox.overlap?, so a collider is bucketed in a
+        # cell if and only if it overlaps that cell's area. All this adds is the one
+        # thing the index cannot know — that a collider queued for removal no longer
+        # occupies anything, the same rule the queries above follow, so a corpse cannot
+        # reserve a square.
+        #
+        # Allocation-free, including the miss: SpatialHash#cell_empty? is asked first
+        # because it is the only way to look at a cell without materialising a bucket for
+        # it, and a caller scanning a board for a free square asks mostly about empty
+        # ones.
+        def cell_empty?(x, y)
+          return true if @hash.cell_empty?(x, y)
+
+          free = true
+          @hash.query(x, y, 0, 0) { |collider| free &&= collider.node.freed? }
+          free
+        end
+
+        # Rebuild the index, then report the step's two kinds of edge. Starting edges
+        # come first and every one of them for the step is emitted before the first
+        # ending one, because a separation is only knowable once every pair has been
+        # looked at.
         def update(_dt)
           @hash.clear
-          @colliders.each { |c| insert(c) }
+          @colliders.each do |collider|
+            collider.contacts.begin_frame
+            insert(collider)
+          end
+
+          report_contacts
+          report_separations
+        end
+
+        private
 
-          # Index-bounded over the count at frame start: an on_hit handler may spawn
-          # entities (a rock splitting), which `register`s new colliders mid-loop; those
-          # appended ones are skipped this frame (processed next) rather than mutating
-          # the array being iterated. The hash was built before the loop, so they're
-          # absent from queries too — consistent.
+        def insert(collider)
+          @hash.insert(collider, collider.aabb_x, collider.aabb_y, collider.aabb_w, collider.aabb_h)
+        end
+
+        def report_contacts
           count = @colliders.size
           i = 0
           while i < count
@@ -75,27 +193,37 @@ module RGame
             i += 1
             next if a.node.freed?
 
-            r = a.radius
-            d = r * 2
-            @hash.query(a.cx - r, a.cy - r, d, d) do |b|
-              # object_id ordering visits each unordered pair once (and skips self);
-              # the freed? guards skip nodes already queued for removal, so a dead
-              # entity stops colliding and duplicate (multi-cell) yields are ignored.
-              next if a.node.freed? || b.node.freed? || a.object_id >= b.object_id
-              next unless a.overlap?(b)
-
-              a.emit_hit(b)
-              b.emit_hit(a)
-            end
+            pair_up(a)
           end
         end
 
-        private
+        def pair_up(a)
+          contacts = a.contacts
+          @hash.query(a.aabb_x, a.aabb_y, a.aabb_w, a.aabb_h) do |b|
+            next if a.node.freed? || b.node.freed? || a.object_id >= b.object_id
+            next if contacts.touching?(b)
+            next unless a.overlap?(b)
 
-        def insert(collider)
-          r = collider.radius
-          d = r * 2
-          @hash.insert(collider, collider.cx - r, collider.cy - r, d, d)
+            started = contacts.started?(b)
+            contacts.add(b)
+            b.contacts.add(a)
+            next unless started
+
+            a.emit_hit(b)
+            b.emit_hit(a)
+          end
+        end
+
+        def report_separations
+          count = @colliders.size
+          i = 0
+          while i < count
+            collider = @colliders[i]
+            i += 1
+            next if collider.node.freed?
+
+            collider.contacts.each_ended { |other| collider.emit_separated(other) }
+          end
         end
       end
     end

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

@@ -3,20 +3,36 @@
 module RGame
   module Engine
     module Components
-      # Queues the node for removal once it has fully left the bounds (plus margin).
-      # From Body#offscreen?. Used by short-lived projectiles; removal is deferred via
-      # queue_free so it is safe to trigger from inside the update traversal.
+      # Queues the node for removal once its origin is further than `margin` past an
+      # edge of the world bounds. Used by short-lived projectiles; removal is deferred
+      # via queue_free so it is safe to trigger from inside the update traversal.
+      #
+      # The margin is what stands in for the node's size: a node drawn centred on its
+      # origin has fully left once the margin is at least its half-extent.
+      #
+      # Bounds resolve the same way ScreenWrap's do: from the scene's world system,
+      # at attach time, with `width:`/`height:` as an override. And like ScreenWrap it
+      # tests the node's **world** position, so a projectile spawned as the child of an
+      # offset emitter leaves at the world's edge rather than at one shifted by the
+      # emitter.
       class DespawnOffscreen < 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
 
+        # See ScreenWrap#on_attach: resolved per entry, so a recycled node is correct
+        # after a scene change.
+        def on_attach
+          WorldBounds.one_response!(node)
+          @width, @height = WorldBounds.resolve(node, @given_width, @given_height)
+        end
+
         def update(_dt)
-          x = node.x
-          y = node.y
+          x = node.world_x
+          y = node.world_y
           offscreen = x < -@margin || x > @width + @margin || y < -@margin || y > @height + @margin
           node.queue_free if offscreen
         end

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

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    module Components
+      # A BoxCollider whose rectangle is the node's *feet*: horizontally centred in the
+      # node's dimensions and anchored to their bottom. That is the shape a top-down
+      # character collides with — a 16x22 hero standing on a floor occupies the 12x6
+      # patch under them, not the whole sprite, which is what stops their head from
+      # bumping into a wall a tile away.
+      #
+      # It is an ordinary BoxCollider in every other respect, so it registers with the
+      # scene's CollisionWorld, collides with circles and boxes alike, and
+      # `get_component(BoxCollider)` finds it. See docs/api/components.md.
+      #
+      # The box is derived from `node.width`/`node.height`, which AnimatedSprite sets
+      # from the sprite frame, rather than from a sprite size passed in — so the caller
+      # gives the feet box and nothing else, and the two can never disagree.
+      class FeetCollider < BoxCollider
+        def initialize(width:, height:, layer: :default)
+          super
+          @feet_width = width
+          @feet_height = height
+          @box = nil
+        end
+
+        # The feet box, derived from the node's sprite size and memoised.
+        #
+        # **Only valid once the node is in the tree**, and it says so rather than letting
+        # you find out later. The size comes from AnimatedSprite#on_attach, so a read from
+        # a constructor sees a 0x0 node and bakes a box anchored to nothing — permanently,
+        # because this memoises. The symptom is an actor that walks through walls it
+        # should not, a long way from the call that caused it. Guarding costs one
+        # comparison, once.
+        #
+        # Building it here rather than in on_attach is what makes the order components
+        # were added in irrelevant: the first read is a frame later, by which time every
+        # sibling has attached. Assigning `box =` still wins, since that leaves nothing
+        # to memoise.
+        def box
+          @box ||= build_box
+        end
+
+        private
+
+        def build_box
+          if node.width.zero? || node.height.zero?
+            raise "FeetCollider needs the node's sprite size, but it is " \
+                  "#{node.width}x#{node.height}. AnimatedSprite sets that when it attaches, so " \
+                  'read this after the node is in the tree, not while building it.'
+          end
+
+          Engine::CollisionBox.bottom_anchored(
+            sprite_width: node.width, sprite_height: node.height,
+            width: @feet_width, height: @feet_height
+          )
+        end
+      end
+    end
+  end
+end