rgame 0.1.0 → 0.3.0

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

@@ -3,23 +3,30 @@
 module RGame
   module Engine
     module Components
-      # Draws a sprite-sheet animation for a walking actor, picking the animation from a
-      # CharacterBody sibling's movement intent: walk_left/right/up/down while moving
-      # (horizontal wins on a diagonal), stand when still. Owns its Animator + the pure
-      # AnimationSet built from the sheet's animation table.
+      # 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 draws at the node's *world* origin
-      # (node.abs_x/abs_y): a CameraView ancestor wraps the draw in renderer.translated to
-      # map world → screen, so this component never touches the camera. `z` is the render
-      # layer (kept as @layer, distinct from the node's transform z); it must sit between
-      # the tile world's ground band and its overlay band so canopies draw in front.
+      # 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 CharacterBody can read node.width/height. The renderer resolves the same
+      # 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
@@ -31,30 +38,31 @@ module RGame
           @animator = Engine::Animator.new(Engine::AnimationSet.new(sheet.animations))
           node.width = sheet.frame_width
           node.height = sheet.frame_height
-          @body = node.get_component(CharacterBody)
+          @mover = require_sibling(Mover)
         end
 
         def update(dt)
-          @animator.play(walk_animation(@body.move_x, @body.move_y))
+          @animator.play(walk_animation(@mover.heading_x, @mover.heading_y))
           @animator.update(dt)
         end
 
-        def draw(renderer)
-          # Read row/col/flip_x separately (not @animator.frame, which allocates an Array
-          # every call) to keep the draw path allocation-free.
-          renderer.sprite(@sheet, @animator.row, @animator.col, node.abs_x, node.abs_y,
+        # 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
 
-        # Horizontal movement wins over vertical, so a diagonal walk faces left/right.
-        def walk_animation(move_x, move_y)
-          if move_x.negative? then :walk_left
-          elsif move_x.positive? then :walk_right
-          elsif move_y.negative? then :walk_up
-          elsif move_y.positive? then :walk_down
-          else :stand
+        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

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    module Components
+      # Points a camera at the node it is attached to.
+      #
+      #   player_node.add_component(CameraFollow.new(camera: players.primary.camera))
+      #
+      # ## Ownership and behaviour are different questions
+      #
+      # The camera cannot be *owned* by a node in the world — with several
+      # viewers there are several cameras, and a world that holds one has to know
+      # how many times it is being drawn. But deciding *where a camera points* is
+      # exactly a per-node concern, so it belongs here: the player owns the
+      # camera, and a component in the world moves it.
+      #
+      # That also makes "player two's camera follows player two" nothing more
+      # than attaching this to their node with their camera.
+      #
+      # `offset_x` / `offset_y` shift the point being centred on, for a node
+      # whose origin is not what should be in the middle of the screen — a
+      # bottom-anchored sprite usually wants its feet, not its head.
+      class CameraFollow < Engine::Component
+        def initialize(camera:, offset_x: 0.0, offset_y: 0.0)
+          super()
+          @camera = camera
+          @offset_x = offset_x
+          @offset_y = offset_y
+        end
+
+        # 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. 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.world_x + @offset_x, node.world_y + @offset_y)
+        end
+      end
+    end
+  end
+end

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

@@ -3,42 +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
-
-        def collision_box
-          @collision_box ||= Engine::CollisionBox.bottom_anchored(
-            sprite_width: node.width, sprite_height: node.height,
-            width: @feet_width, height: @feet_height
-          )
         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)
@@ -46,23 +37,12 @@ module RGame
           @move_y = intent_y
         end
 
-        def update(dt)
-          return if @move_x.zero? && @move_y.zero?
+        private
 
-          @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 take_step(dt)
+          return if @move_x.zero? && @move_y.zero?
 
-        def y=(value)
-          node.y = value
+          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