rgame 0.2.0 → 0.3.1

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

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

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    module Components
+      # A PathFollow that makes its own paths: `go_to(world_x, world_y)` plans a route
+      # over the scene's tile map to the cell containing that point, and walks it.
+      #
+      # Planning is three steps. The scene's TileWorld#nav_grid finds the cheapest route
+      # of cells; the route is **string-pulled** into as few straight segments as the
+      # node's own collider can travel; and those corners become the Engine::Path this
+      # component walks, exactly as a PathFollow walks one it was handed.
+      #
+      # ## The route is checked against what will stop the walk
+      #
+      # A segment is kept only if the map's own blocker source — TileWorld#blockers, the
+      # object a mover declaring `:tiles` resolves its steps against — lets the collider
+      # box travel it. A test on cells alone would keep a diagonal past a solid tile's
+      # corner that a point clears and a 12x6 feet box clips, and a PathFollow does not
+      # slide: the walker would stand at that corner.
+      #
+      # The question is TileBlockers#travel?, which holds for a walker stepping under a
+      # quarter tile at a time — 240 px/s at 60 ticks a second on 16 px tiles.
+      #
+      # Smoothing is greedy: from each corner it extends the segment cell by cell until the
+      # next cell would not be clear, and turns there. The next cell after a corner is taken
+      # without asking, which is sound only for a collider **no larger than a tile** on
+      # either axis — so `go_to` refuses a larger one rather than plan a route it may stall on.
+      #
+      # So what is walked is measured from the **anchor** — the centre of the sibling
+      # BoxCollider's box, or the node's origin on a node with none — and a route ends
+      # with the anchor on the centre of the target cell.
+      #
+      # ## What it does not do
+      #
+      # It does not replan. A route is planned against the map, and the map is all it
+      # knows: a walker declaring other colliders in `blocked_by` waits behind one on its
+      # route, the way any PathFollow waits, and a game that wants it to go round calls
+      # `go_to` again.
+      #
+      # The route is planned in world space and walked in the node's parent's space, which
+      # agree under an unrotated ancestor chain — the same limit a blocked Mover has.
+      class Navigator < PathFollow
+        # The cells of the last route `go_to` planned, start to target, before smoothing —
+        # `[[col, row], ...]`, or nil before the first one. For drawing; `path` is what is
+        # walked.
+        attr_reader :cells
+
+        def initialize(speed:, blocked_by: [])
+          super
+          @cells = nil
+        end
+
+        def on_attach
+          super
+          @world = node.system(TileWorld) ||
+                   raise("#{mover_name} plans routes over the scene's TileWorld, and the scene " \
+                         'has none. Mount one, or use a PathFollow and hand it a path.')
+          @anchor = node.get_component(BoxCollider)
+        end
+
+        # Plan from where the node stands to the cell containing (world_x, world_y), and
+        # start walking it from the node's current position — so a walker already on a
+        # route turns onto the new one without a jump. Returns true.
+        #
+        # Returns false, and leaves whatever the node was doing alone, when there is no
+        # route: the target is solid, outside the map, or cut off from the node.
+        #
+        # Raises ArgumentError when the node's collider is wider or taller than a tile:
+        # pathfinding for such a collider is not supported.
+        #
+        # rubocop:disable Naming/PredicateMethod -- a command that reports whether it could be
+        # carried out, not a question; `go_to?` would read as "may I go there?".
+        def go_to(world_x, world_y)
+          unless @world
+            raise "#{mover_name}#go_to plans over the scene's TileWorld, so the node has to be " \
+                  'in the tree first.'
+          end
+
+          measure_anchor
+          refuse_a_box_larger_than_a_tile
+          cells = @world.nav_grid.find(*cell_at(@anchor_x, @anchor_y), *cell_at(world_x, world_y))
+          return false unless cells
+
+          @cells = cells
+          follow(Engine::Path.new(waypoints(corners(cells))))
+          true
+        end
+        # rubocop:enable Naming/PredicateMethod
+
+        private
+
+        def measure_anchor
+          box = @anchor&.box
+          @box_w = box ? box.width : 0
+          @box_h = box ? box.height : 0
+          @anchor_x = node.world_x + (box ? box.offset_x + (@box_w / 2.0) : 0.0)
+          @anchor_y = node.world_y + (box ? box.offset_y + (@box_h / 2.0) : 0.0)
+        end
+
+        def refuse_a_box_larger_than_a_tile
+          return if @box_w <= @world.tile_width && @box_h <= @world.tile_height
+
+          raise ArgumentError, "#{mover_name}#go_to plans for a collider no larger than a tile, and this " \
+                               "node's is #{@box_w}x#{@box_h} over #{@world.tile_width}x" \
+                               "#{@world.tile_height} tiles. Pathfinding for a larger collider is not supported."
+        end
+
+        def cell_at(x, y) = [(x / @world.tile_width).floor, (y / @world.tile_height).floor]
+
+        def centre_x(cell) = (cell[0] + 0.5) * @world.tile_width
+        def centre_y(cell) = (cell[1] + 0.5) * @world.tile_height
+
+        def corners(cells)
+          corners = [[@anchor_x, @anchor_y]]
+          turn = -1
+          while turn < cells.length - 1
+            turn = furthest_clear(*corners.last, cells, turn + 1)
+            corners << [centre_x(cells[turn]), centre_y(cells[turn])]
+          end
+          corners
+        end
+
+        def furthest_clear(x, y, cells, index)
+          index += 1 while index < cells.length - 1 &&
+                           box_travels?(x, y, centre_x(cells[index + 1]), centre_y(cells[index + 1]))
+          index
+        end
+
+        def box_travels?(from_x, from_y, to_x, to_y)
+          @world.blockers.travel?(from_x - (@box_w / 2.0), from_y - (@box_h / 2.0), @box_w, @box_h,
+                                  to_x - from_x, to_y - from_y)
+        end
+
+        def waypoints(corners)
+          shift_x = node.x - @anchor_x
+          shift_y = node.y - @anchor_y
+          points = corners.map { |(x, y)| [x + shift_x, y + shift_y] }
+          points[0] = [node.x, node.y]
+          points
+        end
+      end
+    end
+  end
+end