rgame 0.1.0 → 0.3.0

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

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

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

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