rgame 0.4.0-x86_64-linux-gnu

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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    module Components
+      # 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 mover's heading, which is what AnimatedSprite faces by, so
+      # a character is just CharacterBody + a controller + AnimatedSprite.
+      #
+      # 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(speed:, blocked_by: [])
+          super(blocked_by: blocked_by)
+          @speed = speed
+          @move_x = 0.0
+          @move_y = 0.0
+        end
+
+        # 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)
+          @move_x = intent_x
+          @move_y = intent_y
+        end
+
+        private
+
+        def take_step(dt)
+          return if @move_x.zero? && @move_y.zero?
+
+          apply_move(@move_x * @speed * dt, @move_y * @speed * dt)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    module Components
+      # 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 world origin; 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.
+      #
+      # 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
+        # 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
+
+        # 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 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
+
+        # @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 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/collision_world.rb

@@ -0,0 +1,231 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    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). 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()
+          @hash = Engine::SpatialHash.new(cell_size: cell_size)
+          @colliders = []
+        end
+
+        # 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 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
+        # block. Allocation-free.
+        def query_circle(x, y, r)
+          r2 = r * r
+          @hash.query_circle(x, y, r) do |collider|
+            next if collider.node.freed?
+
+            dx = collider.cx - x
+            dy = collider.cy - y
+            yield collider if (dx * dx) + (dy * dy) <= r2
+          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 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)
+          best = nil
+          best_d2 = nil
+          query_circle(x, y, r) do |collider|
+            next if layer && collider.layer != layer
+
+            dx = collider.cx - x
+            dy = collider.cy - y
+            d2 = (dx * dx) + (dy * dy)
+            next unless best_d2.nil? || d2 < best_d2
+
+            best = collider
+            best_d2 = d2
+          end
+          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 do |collider|
+            collider.contacts.begin_frame
+            insert(collider)
+          end
+
+          report_contacts
+          report_separations
+        end
+
+        private
+
+        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
+            a = @colliders[i]
+            i += 1
+            next if a.node.freed?
+
+            pair_up(a)
+          end
+        end
+
+        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)
+
+            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
+  end
+end

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

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    module Components
+      # 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: nil, height: nil, margin: 0.0)
+          super()
+          @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.world_x
+          y = node.world_y
+          offscreen = x < -@margin || x > @width + @margin || y < -@margin || y > @height + @margin
+          node.queue_free if offscreen
+        end
+      end
+    end
+  end
+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

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

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    module Components
+      # A jump in a top-down view. Pressing the action lifts the node along a
+      # parabola that peaks at `peak` pixels halfway through `duration` seconds,
+      # then puts it back on the ground.
+      #
+      # The height is written to Node2D#elevation, never to `y`. In a top-down view
+      # a jump is a *drawing* offset: the sprite arcs above the spot the character
+      # stands on, while that spot, and every collider and camera reading it, stays
+      # on the ground. So a hop does not carry anyone over a wall. What it
+      # crosses is the game's decision, made by reading `airborne?`.
+      #
+      #   node.add_component(Engine::Components::Hop.new(peak: 18, duration: 0.5))
+      #
+      # The arc is a function of the time accumulated in `update`, not of a clock,
+      # so a paused node hangs in the air and a spec can ask for the height at 0.25s.
+      # It starts on the action's press edge, so holding the button hops once.
+      # `action: nil` leaves only #jump, for something that is not a player.
+      class Hop < Engine::Component
+        attr_reader :peak, :duration, :height
+
+        def initialize(peak:, duration:, action: :jump)
+          super()
+          raise ArgumentError, "peak must be positive, got #{peak.inspect}" unless peak.positive?
+          raise ArgumentError, "duration must be positive, got #{duration.inspect}" unless duration.positive?
+
+          @peak = peak
+          @duration = duration
+          @action = action
+          @height = 0.0
+          @elapsed = 0.0
+          @airborne = false
+        end
+
+        # Attaching lands the node, so a pooled node reused mid-hop starts on the ground.
+        def on_attach = land
+
+        def airborne? = @airborne
+
+        # Leave the ground. Does nothing while already off it; `airborne?` says which.
+        def jump
+          return if @airborne
+
+          @airborne = true
+          @elapsed = 0.0
+        end
+
+        def control(actions)
+          jump if @action && actions.pressed?(@action)
+        end
+
+        def update(dt)
+          return unless @airborne
+
+          @elapsed += dt
+          return land if @elapsed >= @duration
+
+          @height = 4.0 * @peak * @elapsed * (@duration - @elapsed) / (@duration * @duration)
+          node.elevation = @height
+        end
+
+        private
+
+        def land
+          @airborne = false
+          @elapsed = 0.0
+          @height = 0.0
+          node.elevation = 0
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    module Components
+      # A stable name for one node, so something outside the tree can refer to it.
+      #
+      #   sheep.add_component(Identity.new(id: 7))
+      #   Identity.of(sheep)   # => 7
+      #
+      # ## What it is for, and what does not need it
+      #
+      # Most saving needs no identity at all. A scene is a recipe and a save file
+      # is state: the scene rebuilds itself identically, and the save supplies the
+      # few facts that differ. A *singular* thing needs no id because the variable
+      # holding it is one — `@dog` is set where the dog is built and written
+      # straight to on load. *Interchangeable* things need none either, because
+      # their order will do: an array of positions restored in order is correct
+      # precisely when swapping two of them changes nothing observable.
+      #
+      # This is for the case those two do not cover:
+      #
+      # - **members of a collection that can die**, where each survivor keeps
+      #   state of its own. An array index stops meaning anything the first time
+      #   the middle of the list is removed;
+      # - **a reference from one saved thing to another** — a dog chasing a
+      #   particular sheep. A node reference cannot be written to a file, and this
+      #   is what it is written *as*.
+      #
+      # The second is the one that genuinely forces ids. A collection could always
+      # be respawned from its own records; a reference between two of them could
+      # not.
+      #
+      # ## The engine supplies the mechanism, a game supplies the meaning
+      #
+      # What gets an id, what the ids are, and how they are handed out are the
+      # game's business — the same division as `Timer`, which counts down without
+      # an opinion about what happens next. Two things follow from that, and both
+      # are the game's to get right:
+      #
+      # **Ids must be unique among the things that can refer to each other.** This
+      # component checks nothing; a duplicate is a save that restores the wrong
+      # object, silently.
+      #
+      # **The allocator belongs in the save.** A counter that restarts at 1 on
+      # load will reissue ids that the restored objects are already using, and the
+      # collision surfaces later as a reference pointing at the wrong thing. Save
+      # the next id alongside the objects and restore it too — it is one number,
+      # and forgetting it is the classic way this goes wrong.
+      class Identity < Engine::Component
+        attr_reader :id
+
+        def initialize(id:)
+          super()
+          raise ArgumentError, 'an identity needs an id' if id.nil?
+
+          @id = id
+        end
+
+        # The id of a node, or nil for one that carries no identity.
+        #
+        # This is the direction that matters at save time: a component holding a
+        # *node* — `Targeting#target` is the worked example — has to turn it into
+        # something writable, and it has only the node to go on. Going the other
+        # way is a game's own lookup, because only the game knows which
+        # collection to search.
+        def self.of(node)
+          node&.get_component(self)&.id
+        end
+      end
+    end
+  end
+end