rgame 0.4.0-x86_64-linux-gnu

data/lib/rgame/engine/bounds_blockers.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    # The edges of the world as a blocker source: a box may not leave the region the
+    # scene's Components::WorldBounds describes. Pure — it is four numbers and the same
+    # snapping arithmetic every other source uses.
+    #
+    # It answers the blocker-source question Engine::CollisionSystem asks of every source
+    # it holds; see that class's header for the protocol.
+    #
+    # ## Why the world edge is declared rather than automatic
+    #
+    # Stopping at the edge is one of three responses to it. ScreenWrap and DespawnOffscreen
+    # are the other two, and a node may carry only one of them
+    # (Components::WorldBounds.one_response!). A clamp applied to every step would be a
+    # response nobody chose, contradicting a wrap or a despawn on every node that has one.
+    # So a game that wants the world edge to stop an actor says so, and gets an ordinary
+    # blocker with a layer like any other.
+    class BoundsBlockers
+      # What a BoundsBlockers reports as having stopped a step: one object for the life of
+      # the process, answering the same two questions a collider does, so a handler reads
+      # `by.layer` whatever stopped it. The world's edge has no node.
+      class Bounds
+        def layer = :bounds
+        def node = nil
+      end
+
+      BOUNDS = Bounds.new.freeze
+
+      # `bounds` is anything answering world_width / world_height — a Components::World or
+      # a Components::TileWorld. The two numbers are read once, here, because WorldBounds
+      # is documented immutable: a world that genuinely changes size is a new scene.
+      def initialize(bounds:)
+        @world_width = bounds.world_width
+        @world_height = bounds.world_height
+        @blocker = nil
+      end
+
+      # The world's edge stopped the last resolve on this axis, or nil when it did not.
+      attr_reader :blocker
+
+      # The far axis is nothing to a rectangle: a box leaves the world on one axis
+      # independently of where it is on the other, so `_y` and `_h` go unread here and
+      # `_x` and `_w` in the mirror. The five arguments are the protocol's, not this
+      # source's need.
+      def resolve_x(x, _y, w, _h, dx) = resolve(x + dx, w, @world_width, dx)
+      def resolve_y(_x, y, _w, h, dy) = resolve(y + dy, h, @world_height, dy)
+
+      # The world does not move, so there is nothing to re-index.
+      def moved(_actor, _from_x, _from_y, _w, _h) = nil
+
+      private
+
+      def resolve(landed, span, extent, delta)
+        @blocker = nil
+        return landed if delta.zero?
+
+        limit = extent - span
+        limit = 0.0 if limit.negative?
+
+        if landed.negative?
+          @blocker = BOUNDS
+          0.0
+        elsif landed > limit
+          @blocker = BOUNDS
+          limit.to_f
+        else
+          landed
+        end
+      end
+    end
+  end
+end

data/lib/rgame/engine/camera.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    # A 2D camera: a point in the world to look at, plus the world bounds it may
+    # not show past. Pure; the offset it produces is applied as a draw-time
+    # transform, never baked into a node.
+    #
+    #   camera = Camera.new(world_width: map.pixel_width, world_height: map.pixel_height)
+    #   camera.center_on(player.world_x, player.world_y)   # in update, every tick
+    #   camera.resolve(view_width, view_height)        # at draw, for one viewport
+    #   camera.x, camera.y                             # the offset to translate by
+    #
+    # ## Why the viewport size is an argument and not state
+    #
+    # A camera used to be built with its viewport size and clamp against it in
+    # `center_on`. That cannot survive split-screen: the same world is drawn
+    # through several viewports whose rects come from the layout and change when
+    # a player joins or the window resizes. Clamping has to happen against the
+    # rect actually being drawn into, and the difference is visible rather than
+    # theoretical — near a world edge, the same target sits at a different place
+    # on screen in a half-width viewport than in a full-width one.
+    #
+    # So `center_on` records *intent* and `resolve` computes the offset. Nothing
+    # calls `resolve` by hand: the platform resolves each camera against the
+    # viewport it is about to draw, which is what keeps the two from drifting.
+    #
+    # ## The camera belongs to a player, not to a scene
+    #
+    # A scene may have any number of viewers, so it cannot own "the" camera.
+    # RGame::Engine::Player owns one; a scene sets its world bounds when it
+    # loads a map, and a CameraFollow component in the world points it.
+    class Camera
+      attr_reader :x, :y, :target_x, :target_y
+      attr_accessor :world_width, :world_height
+
+      # `world_width` / `world_height` bound what the camera may show. Left nil
+      # the camera is unbounded and follows its target exactly — which is the
+      # right default: a game that has not declared its world yet gets a camera
+      # that visibly works, rather than one silently pinned to the origin.
+      def initialize(world_width: nil, world_height: nil)
+        @world_width = world_width
+        @world_height = world_height
+        @target_x = 0.0
+        @target_y = 0.0
+        @x = 0.0
+        @y = 0.0
+      end
+
+      # Look at this world point. Records the target; the offset is worked out
+      # by #resolve, which is the only place that knows how big the view is.
+      def center_on(world_x, world_y)
+        @target_x = world_x
+        @target_y = world_y
+        self
+      end
+
+      # Work out the draw offset for a viewport of this size, clamped so the
+      # view never shows past the world's edges.
+      def resolve(view_width, view_height)
+        @x = clamp(@target_x - (view_width / 2.0), @world_width, view_width)
+        @y = clamp(@target_y - (view_height / 2.0), @world_height, view_height)
+        self
+      end
+
+      private
+
+      def clamp(value, world_size, view_size)
+        return value.to_f if world_size.nil?
+
+        max = world_size - view_size
+        return 0.0 if max <= 0
+
+        value.clamp(0.0, max.to_f)
+      end
+    end
+  end
+end

data/lib/rgame/engine/circle_collider.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    # A circular collision shape, the sibling of CollisionBox for entities that
+    # rotate (rocks, ship): a circle is rotation-invariant, so a spinning rock needs
+    # no per-frame box recompute. The collider owns only the radius; the entity owns
+    # its centre position. Pure logic; no graphics.
+    class CircleCollider
+      attr_reader :radius
+
+      # Squared-distance overlap test (no sqrt): true when two circles overlap in area.
+      # Circles that exactly graze are apart, the same half-open convention CollisionBox
+      # uses — one meaning of "contact" across both shapes and the pairs that mix them.
+      def self.overlap?(x1, y1, r1, x2, y2, r2)
+        dx = x2 - x1
+        dy = y2 - y1
+        sum = r1 + r2
+        (dx * dx) + (dy * dy) < sum * sum
+      end
+
+      def initialize(radius:)
+        @radius = radius
+      end
+
+      # Bounding AABB [x, y, w, h] for a circle centred at (cx, cy) — what the
+      # spatial hash buckets on.
+      def aabb(cx, cy)
+        d = @radius * 2
+        [cx - @radius, cy - @radius, d, d]
+      end
+    end
+  end
+end

data/lib/rgame/engine/collision_box.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    # A character's collision rectangle, expressed as an offset + size relative to
+    # the actor's top-left origin (the sprite's top-left). Decoupled from sprite
+    # size: a 32x32 sprite can have a small 16x16 box at its feet.
+    #
+    # It is also where rectangle geometry lives, the way CircleCollider owns circle
+    # geometry: the overlap tests below are class methods over plain numbers, so the
+    # per-frame collision path can call them without building a box first.
+    class CollisionBox
+      attr_reader :offset_x, :offset_y, :width, :height
+
+      # Centre the box horizontally and anchor it to the bottom of the sprite (feet).
+      def self.bottom_anchored(sprite_width:, sprite_height:, width:, height:)
+        new(
+          offset_x: (sprite_width - width) / 2,
+          offset_y: sprite_height - height,
+          width: width,
+          height: height
+        )
+      end
+
+      # Rect-vs-rect: true when two world-space AABBs overlap in *area*. A shape spans
+      # the half-open box [x, x + w), so shapes that merely share an edge are apart —
+      # the same convention SDL_HasIntersection uses, and the one thing that makes a
+      # grid work: pieces on neighbouring squares border each other constantly, and an
+      # inclusive test would report every one of those as a contact.
+      def self.overlap?(x1, y1, w1, h1, x2, y2, w2, h2)
+        x1 < x2 + w2 && x2 < x1 + w1 && y1 < y2 + h2 && y2 < y1 + h1
+      end
+
+      # Rect-vs-circle: true when the circle at (cx, cy) overlaps the rect. Clamping
+      # the centre into the rect gives the rect's nearest point to it, so the corner
+      # case and the edge case are the same two lines — no per-region analysis, and
+      # no sqrt (compare squared distances). Grazing is not overlapping, as above.
+      def self.overlap_circle?(x, y, w, h, cx, cy, r)
+        nx = cx.clamp(x, x + w)
+        ny = cy.clamp(y, y + h)
+        dx = cx - nx
+        dy = cy - ny
+        (dx * dx) + (dy * dy) < r * r
+      end
+
+      def initialize(width:, height:, offset_x: 0, offset_y: 0)
+        @offset_x = offset_x
+        @offset_y = offset_y
+        @width = width
+        @height = height
+      end
+
+      # World-space AABB [x, y, w, h] for an actor whose origin is at (x, y).
+      def aabb(x, y)
+        [x + @offset_x, y + @offset_y, @width, @height]
+      end
+    end
+  end
+end

data/lib/rgame/engine/collision_system.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    # The actor-facing collision system: moves any actor by a delta, resolving its
+    # *collision box* (not its sprite) against every blocker source it holds. Reusable by
+    # the player and any NPC.
+    #
+    # **Everything that can stop a step is a source**, including the edge of the world —
+    # see Engine::BoundsBlockers, and its header for why that used to be an unconditional
+    # clamp here and is not any more. Nothing holds an actor anywhere it did not ask to
+    # be held.
+    #
+    # ## What a blocker source is
+    #
+    # A blocker source answers one question, on one axis, over plain numbers:
+    #
+    #   source.resolve_x(x, y, w, h, dx) # -> where the box's left edge lands moving dx
+    #   source.resolve_y(x, y, w, h, dy) # -> where the box's top  edge lands moving dy
+    #
+    # Engine::TileBlockers divides by the tile size and snaps flush against a solid tile;
+    # Engine::ActorBlockers queries a broadphase and snaps flush against another
+    # collider's edge. Neither needs to know the other exists, because this system takes
+    # the **most restrictive** answer on each axis: a box hemmed in by a wall on one side
+    # and something else nearer stops at whichever is nearer.
+    #
+    # Two more questions a source answers, and both are asked here so that no caller has
+    # anything to remember:
+    #
+    #   source.blocker  # -> what produced the edge the last resolve returned, or nil
+    #   source.moved(actor, from_x, from_y, w, h)  # -> the step has been written back
+    #
+    # `blocker` is how #blocked_x / #blocked_y name what stopped a step; `moved` is how a
+    # source over a moving index re-buckets the mover, with the box the step started from.
+    #
+    # A fourth question is optional, and only Engine::TileBlockers answers it today:
+    #
+    #   source.travel?(x, y, w, h, dx, dy)  # -> can the box move (dx, dy) without being stopped?
+    #
+    # "Stopped" means what it means here: a resolve landing *short* of where the step was
+    # heading. A landing past it is ignored below, so it does not stop a travel either. Read
+    # that way the question splits by source — a box travels past several sources exactly when
+    # it travels past each one alone — so no source needs to know the others exist for this
+    # question any more than for the other three. The shared example group "a blocker source
+    # answering travel?" states it.
+    #
+    # Holding the sources here rather than inside any one of them is what puts the
+    # axis-separated order — resolve X, then resolve Y fed the resolved X — in exactly
+    # one place. That order is what produces wall-sliding (a diagonal push into a wall
+    # keeps the component that is still free), so every source shares one feel rather
+    # than each implementing it.
+    class CollisionSystem
+      # What stopped the last #move on each axis, or nil when that axis was free. Whatever
+      # a source reports, so a handler reads `blocked_x.layer` without asking which kind
+      # of thing it was. Set by every #move, so read it straight after one.
+      attr_reader :blocked_x, :blocked_y
+
+      def initialize(blockers: [])
+        @blockers = Array(blockers)
+        @blocked_x = nil
+        @blocked_y = nil
+      end
+
+      # Move `actor` by (dx, dy), writing the resolved position back to it.
+      def move(actor, dx, dy)
+        box = actor.collision_box
+        from_x = actor.x + box.offset_x
+        from_y = actor.y + box.offset_y
+        bw = box.width
+        bh = box.height
+
+        bx = resolve_x(from_x, from_y, bw, bh, dx)
+        by = resolve_y(bx, from_y, bw, bh, dy)
+
+        actor.x = bx - box.offset_x
+        actor.y = by - box.offset_y
+
+        i = 0
+        while i < @blockers.size
+          @blockers[i].moved(actor, from_x, from_y, bw, bh)
+          i += 1
+        end
+      end
+
+      # Where the box's left edge lands moving dx, against every source at once. The most
+      # restrictive answer is the *smallest* landing for a rightward step and the largest
+      # for a leftward one; with no sources at all the box simply moves.
+      #
+      # A plain index loop rather than @blockers.map/min: this runs per actor per axis per
+      # frame, and both the block and the intermediate array would allocate.
+      def resolve_x(x, y, w, h, dx)
+        @blocked_x = nil
+        nx = x + dx
+        return nx if dx.zero?
+
+        winner = nil
+        i = 0
+        while i < @blockers.size
+          source = @blockers[i]
+          landed = source.resolve_x(x, y, w, h, dx)
+          if dx.positive? ? landed < nx : landed > nx
+            nx = landed
+            winner = source
+          end
+          i += 1
+        end
+        @blocked_x = winner&.blocker
+        nx
+      end
+
+      def resolve_y(x, y, w, h, dy)
+        @blocked_y = nil
+        ny = y + dy
+        return ny if dy.zero?
+
+        winner = nil
+        i = 0
+        while i < @blockers.size
+          source = @blockers[i]
+          landed = source.resolve_y(x, y, w, h, dy)
+          if dy.positive? ? landed < ny : landed > ny
+            ny = landed
+            winner = source
+          end
+          i += 1
+        end
+        @blocked_y = winner&.blocker
+        ny
+      end
+    end
+  end
+end

data/lib/rgame/engine/component.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    class Component
+      extend Signal::DSL
+      extend SealedPrivates
+
+      attr_accessor :node
+
+      def context
+        @context ||= node.context
+      end
+
+      # Tree-lifecycle hooks. on_attach fires once the node is in the live tree, so
+      # node.root / node.scene and sibling systems are reachable — pull and register
+      # shared systems here, not in initialize (where the node has no anchors yet).
+      # on_detach mirrors it: release those registrations.
+      def on_attach; end
+      def on_detach; end
+
+      # The sibling component this one drives, or a raise naming both — for the
+      # `@body = require_sibling(CharacterBody)` line an `on_attach` opens with.
+      #
+      # Worth a helper rather than a bare `get_component` because the nil it returns
+      # is silent, and stays silent until the first frame calls a method on it: the
+      # error you see is a NoMethodError on nil, in `control`, naming neither the
+      # component that is missing nor the one that wanted it.
+      #
+      # And the cause is nearly always the same, which is why the message says it.
+      # A node assembled *outside* the tree collects every component before any
+      # on_attach runs (Node2D#enter_tree), so add order does not matter there. A
+      # node that adds components from its own `on_add` is already in the tree, so
+      # each one attaches as it arrives and can only see the ones before it. Same
+      # two lines, opposite outcome, depending on where they were written.
+      #
+      # A class several components answer to — `Components::Mover` has three — can match
+      # twice on one node, and then there is no telling which one was meant. That raises
+      # too, naming each match, rather than quietly taking the first.
+      def require_sibling(klass)
+        matches = node.components.grep(klass)
+        if matches.length > 1
+          raise ArgumentError, "#{self.class} reads one #{klass} on the same node, and this node has " \
+                               "#{matches.length}: #{matches.map(&:class).join(', ')}. " \
+                               'Keep one of them on this node.'
+        end
+
+        matches.first ||
+          raise("#{self.class} needs a #{klass} on the same node, and there is none. If you did " \
+                'add one, add it before this component: a node that is already in the tree ' \
+                'attaches each component as it arrives, so a sibling added after this one is ' \
+                'not there yet when this one attaches.')
+      end
+
+      def control(actions); end
+      def update(dt); end
+      def draw(renderer, view); end
+
+      # Container components (e.g. SceneStack) that hold nodes off the normal child
+      # list override this to forward the deferred-free sweep into them.
+      def sweep_freed; end
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    module Components
+      # Maps held input actions to an `on_triggered(action)` signal, rate-limited by a
+      # per-action cooldown. One instance covers several actions (the engine allows
+      # only one component of a class per node), so it emits the action name and lets
+      # listeners filter — reusable for "fire" here, or "jump"/"fire" in a platformer.
+      #
+      #   trigger = node.add_component(ActionTrigger.new(fire: 0.22, dash: 0.5))
+      #   trigger.on_triggered { |action| fire if action == :fire }
+      #
+      # Semantics: while an action is held and its cooldown has elapsed, it fires and
+      # the cooldown restarts — i.e. auto-repeat at the cooldown rate.
+      class ActionTrigger < Engine::Component
+        signal :on_triggered, Engine::Signal.define(:action)
+
+        def initialize(cooldowns)
+          super()
+          @cooldowns = cooldowns
+          @timers = cooldowns.transform_values { 0.0 }
+        end
+
+        def update(dt)
+          @timers.each { |action, remaining| @timers[action] = remaining - dt if remaining.positive? }
+        end
+
+        def control(actions)
+          @cooldowns.each_key do |action|
+            next unless actions.held?(action) && @timers[action] <= 0.0
+
+            @timers[action] = @cooldowns[action]
+            on_triggered_signal.emit(action)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    module Components
+      # Draws a sprite-sheet animation for a walking actor, picking the animation from its
+      # Mover sibling's heading: walk_left/right/up/down while moving, stand when still. The
+      # larger axis of the heading picks the direction and a tie goes horizontal, so a
+      # keyboard diagonal walks sideways and a route running mostly downhill walks down.
+      # Any mover will do — a CharacterBody faces its intent, a PathFollow the road it is
+      # on — and a node with two movers raises at attach, since there would be no telling
+      # which way it faces. Owns its Animator + the pure AnimationSet built from the sheet's
+      # animation table.
+      #
+      # Like Sprite, it passes NO angle and NO position: it draws at (0, 0), which
+      # Node2D#draw has already made mean "at this node, correctly rotated", and a
+      # WorldView ancestor has already made mean "through the camera". `z` is the
+      # render layer (kept as @layer, distinct from the node's transform z); it must
+      # sit between the tile map's ground and canopy z bands, so canopies draw in
+      # front.
+      #
+      # `sheet` is the asset's relative path. The component resolves it from the game's
+      # asset manager on attach — via node.root.context.assets (the platform seam) — to
+      # build its animation table and to size the node to the sprite's frame, so siblings
+      # like FeetCollider can read node.width/height. The renderer resolves the same
+      # symbol when drawing, so nothing is registered or passed in by hand.
+      class AnimatedSprite < Engine::Component
+        include Engine::Culling
+
+        def initialize(sheet:, z: 0)
+          super()
+          @sheet = sheet
+          @layer = z
+        end
+
+        def on_attach
+          sheet = context.assets.sheet(@sheet)
+          @animator = Engine::Animator.new(Engine::AnimationSet.new(sheet.animations))
+          node.width = sheet.frame_width
+          node.height = sheet.frame_height
+          @mover = require_sibling(Mover)
+        end
+
+        def update(dt)
+          @animator.play(walk_animation(@mover.heading_x, @mover.heading_y))
+          @animator.update(dt)
+        end
+
+        # Top-left anchored, sized by the sheet's frame and lifted by the node's
+        # elevation — so the footprint to cull against is the node's box, raised
+        # by the same amount the picture is.
+        def draw(renderer, view)
+          lift = node.elevation
+          return if culled?(view, node.world_x, node.world_y - lift, node.width, node.height)
+
+          renderer.sprite(@sheet, @animator.row, @animator.col, 0, -lift,
+                          flip_x: @animator.flip_x, z: @layer)
+        end
+
+        private
+
+        def walk_animation(heading_x, heading_y)
+          if heading_x.zero? && heading_y.zero? then :stand
+          elsif heading_x.abs >= heading_y.abs then heading_x.negative? ? :walk_left : :walk_right
+          else heading_y.negative? ? :walk_up : :walk_down
+          end
+        end
+      end
+    end
+  end
+end

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