rgame 0.1.0

data/lib/rgame/engine/collision_box.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    # A character's collision rectangle, expressed as an offset + size relative to
+    # the actor's top-left origin (the sprite's top-left). Decoupled from sprite
+    # size: a 32x32 sprite can have a small 16x16 box at its feet.
+    class CollisionBox
+      attr_reader :offset_x, :offset_y, :width, :height
+
+      # Centre the box horizontally and anchor it to the bottom of the sprite (feet).
+      def self.bottom_anchored(sprite_width:, sprite_height:, width:, height:)
+        new(
+          offset_x: (sprite_width - width) / 2,
+          offset_y: sprite_height - height,
+          width: width,
+          height: height
+        )
+      end
+
+      def initialize(offset_x:, offset_y:, width:, height:)
+        @offset_x = offset_x
+        @offset_y = offset_y
+        @width = width
+        @height = height
+      end
+
+      # World-space AABB [x, y, w, h] for an actor whose origin is at (x, y).
+      def aabb(x, y)
+        [x + @offset_x, y + @offset_y, @width, @height]
+      end
+    end
+  end
+end

data/lib/rgame/engine/collision_system.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    # The actor-facing collision system: moves any actor by a delta, resolving its
+    # *collision box* (not its sprite) against the tiles via TileCollision, then
+    # clamping the box inside the world as a backstop. Reusable by the player and
+    # any NPC.
+    #
+    class CollisionSystem
+      def initialize(tile_collision:, world_width:, world_height:)
+        @tiles = tile_collision
+        @world_width = world_width
+        @world_height = world_height
+      end
+
+      # Move `actor` by (dx, dy), writing the resolved position back to it.
+      def move(actor, dx, dy)
+        box = actor.collision_box
+        # Read the box AABB into locals directly rather than via box.aabb, which would
+        # allocate an Array on this per-frame path.
+        bx = actor.x + box.offset_x
+        by = actor.y + box.offset_y
+        bw = box.width
+        bh = box.height
+
+        bx = @tiles.resolve_x(bx, by, bw, bh, dx)
+        by = @tiles.resolve_y(bx, by, bw, bh, dy)
+
+        # Clamp the box inside the world. Floor each upper bound at 0 without a [span, 0]
+        # array (this runs per actor per frame).
+        max_x = @world_width - bw
+        max_x = 0 if max_x.negative?
+        max_y = @world_height - bh
+        max_y = 0 if max_y.negative?
+        bx = bx.clamp(0.0, max_x.to_f)
+        by = by.clamp(0.0, max_y.to_f)
+
+        actor.x = bx - box.offset_x
+        actor.y = by - box.offset_y
+      end
+    end
+  end
+end

data/lib/rgame/engine/component.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    class Component
+      extend Signal::DSL
+
+      attr_accessor :node
+
+      def context
+        @context ||= node.context
+      end
+
+      # Tree-lifecycle hooks. on_attach fires once the node is in the live tree, so
+      # node.root / node.scene and sibling systems are reachable — pull and register
+      # shared systems here, not in initialize (where the node has no anchors yet).
+      # on_detach mirrors it: release those registrations.
+      def on_attach; end
+      def on_detach; end
+
+      def control(actions); end
+      def update(dt); end
+      def draw(renderer); end
+
+      # Container components (e.g. SceneStack) that hold nodes off the normal child
+      # list override this to forward the deferred-free sweep into them.
+      def sweep_freed; end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+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.
+      #
+      # 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.
+      #
+      # `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
+      # symbol when drawing, so nothing is registered or passed in by hand.
+      class AnimatedSprite < Engine::Component
+        def initialize(sheet:, z: 0)
+          super()
+          @sheet = sheet
+          @layer = z
+        end
+
+        def on_attach
+          sheet = context.assets.sheet(@sheet)
+          @animator = Engine::Animator.new(Engine::AnimationSet.new(sheet.animations))
+          node.width = sheet.frame_width
+          node.height = sheet.frame_height
+          @body = node.get_component(CharacterBody)
+        end
+
+        def update(dt)
+          @animator.play(walk_animation(@body.move_x, @body.move_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,
+                          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
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+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.
+      #
+      # The intent doubles as the facing for AnimatedSprite (move_x / move_y readers), 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
+        attr_reader :move_x, :move_y
+
+        def initialize(feet_width:, feet_height:, speed:)
+          super()
+          @feet_width = feet_width
+          @feet_height = feet_height
+          @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)
+
+        # 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
+
+        def update(dt)
+          return if @move_x.zero? && @move_y.zero?
+
+          @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 y=(value)
+          node.y = value
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,44 @@
+# 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 resolved absolute 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.
+      class CircleCollider < Engine::Component
+        # Fired by CollisionWorld for each overlapping collider; the listener gets the
+        # other collider and reads its #layer / #node to react.
+        signal :on_hit, 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
+
+        def initialize(radius:, layer: :default)
+          super()
+          @radius = radius
+          @layer = layer
+        end
+
+        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
+
+        def overlap?(other)
+          Engine::CircleCollider.overlap?(cx, cy, @radius, other.cx, other.cy, other.radius)
+        end
+
+        # Called by CollisionWorld on contact (the signal's emit is otherwise private).
+        def emit_hit(other) = on_hit_signal.emit(other)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,103 @@
+# 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). 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.
+      class CollisionWorld < Engine::Component
+        def initialize(cell_size:)
+          super()
+          @hash = Engine::SpatialHash.new(cell_size: cell_size)
+          @colliders = []
+        end
+
+        def register(collider) = @colliders << collider
+        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
+        # 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
+
+        # 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
+        # :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
+
+        def update(_dt)
+          @hash.clear
+          @colliders.each { |c| insert(c) }
+
+          # 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.
+          count = @colliders.size
+          i = 0
+          while i < count
+            a = @colliders[i]
+            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
+          end
+        end
+
+        private
+
+        def insert(collider)
+          r = collider.radius
+          d = r * 2
+          @hash.insert(collider, collider.cx - r, collider.cy - r, d, d)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+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.
+      class DespawnOffscreen < Engine::Component
+        def initialize(width:, height:, margin: 0.0)
+          super()
+          @width = width
+          @height = height
+          @margin = margin
+        end
+
+        def update(_dt)
+          x = node.x
+          y = node.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/path_follow.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    module Components
+      # Walks the owning node along an Engine::Path at a constant speed, segment by
+      # segment, and emits `on_finished` once it reaches the final waypoint — the seam a
+      # tower defense game uses to leak a life when an enemy reaches the base.
+      #
+      # The walk is allocation-free: it tracks the current segment and the distance into
+      # it, advancing through as many segments as one step crosses (so a fast mover over
+      # short segments still lands correctly), then interpolates the node's position from
+      # the segment endpoints. Movement is driven purely by `speed * dt`; this is not a
+      # Velocity integrator and ignores the node's angle.
+      class PathFollow < Engine::Component
+        signal :on_finished # emits no payload; the owning node identifies which follower finished
+
+        attr_accessor :speed
+
+        def initialize(path:, speed:)
+          super()
+          @path = path
+          @speed = speed
+          @segment = 0       # walking from waypoint @segment to @segment + 1
+          @distance = 0.0    # distance travelled into the current segment
+          @finished = false
+        end
+
+        def finished? = @finished
+
+        # Restart the walk as the node enters the tree — back to the first waypoint, with
+        # progress cleared — so a pooled follower reacquired and re-added begins a fresh walk
+        # rather than resuming (or staying finished) where its previous life ended.
+        def on_attach
+          @segment = 0
+          @distance = 0.0
+          @finished = false
+          place_at(0)
+        end
+
+        def update(dt)
+          return if @finished
+
+          remaining = @speed * dt
+          while remaining.positive?
+            left = @path.segment_length(@segment) - @distance
+            if remaining < left
+              @distance += remaining
+              break
+            end
+            # Consume the rest of this segment and step onto the next waypoint.
+            remaining -= left
+            @segment += 1
+            @distance = 0.0
+            return finish if @segment >= @path.count - 1
+          end
+          place_along_segment
+        end
+
+        private
+
+        def finish
+          place_at(@path.count - 1)
+          @finished = true
+          on_finished_signal.emit
+        end
+
+        def place_at(waypoint)
+          node.x = @path.x_at(waypoint)
+          node.y = @path.y_at(waypoint)
+        end
+
+        def place_along_segment
+          seg_len = @path.segment_length(@segment)
+          t = seg_len.zero? ? 0.0 : @distance / seg_len
+          sx = @path.x_at(@segment)
+          sy = @path.y_at(@segment)
+          node.x = sx + ((@path.x_at(@segment + 1) - sx) * t)
+          node.y = sy + ((@path.y_at(@segment + 1) - sy) * t)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    module Components
+      # Drives a CharacterBody sibling from two input axes — direct 8-way walking, no
+      # inertia (unlike ThrustController). Each frame it copies the axis snapshot into
+      # the body's movement intent; the body does the collision-checked move.
+      class PlayerController < Engine::Component
+        def initialize(x_axis: :move_x, y_axis: :move_y)
+          super()
+          @x_axis = x_axis
+          @y_axis = y_axis
+        end
+
+        def on_attach = @body = node.get_component(CharacterBody)
+
+        def control(actions)
+          @body.set_intent(actions.axis(@x_axis), actions.axis(@y_axis))
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    module Components
+      # Wraps an Engine::Pool of nodes and folds the tree bookkeeping into the frame tick:
+      # `spawn` takes a node from the pool (recycled or freshly built) and adds it as a
+      # child of the owner, and `update` returns freed nodes to the pool — so a game only
+      # ever writes `pool.spawn` and the ordinary `node.queue_free`, never a hand-written
+      # acquire/add/reclaim bridge. Pooled nodes are normal children, so the scene's usual
+      # traversal updates and draws them; this component only manages their pool membership.
+      #
+      #   pool = add_component(Engine::Components::Pool.new { Enemy.new(path: @path) })
+      #   pool.spawn                       # acquire + add as a child
+      #   pool.spawn { |b| b.reset(x, y) } # reset before it enters the tree (projectiles)
+      #   enemy.queue_free                 # → reclaimed back to the pool automatically
+      #
+      # Add it named (`as:`) like any component when a node needs more than one pool.
+      class Pool < Engine::Component
+        def initialize(&)
+          super()
+          @pool = Engine::Pool.new(&)
+        end
+
+        # Take a node from the pool, let the caller re-initialise it before it goes live
+        # (optional block — runs before on_attach), and add it as a child of the owner.
+        def spawn
+          child = @pool.acquire
+          yield child if block_given?
+          node.add_node(child)
+          child
+        end
+
+        # Ride the tick: return every freed pooled node to the free list, detaching any that
+        # are still in the tree — so a queue_free elsewhere recycles with no game-side wiring.
+        def update(_dt)
+          @pool.reclaim_if do |child|
+            next false unless child.freed?
+
+            node.remove_node(child) # idempotent if the deferred-free sweep already detached it
+            true
+          end
+        end
+
+        def size = @pool.size
+
+        # True when no spawned node is currently live (all reclaimed) — a scene reads this to
+        # tell when a wave/round has been fully cleared.
+        def empty? = @pool.empty?
+      end
+    end
+  end
+end

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

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    module Components
+      # Wraps the node's position toroidally within a rectangle (plus margin), so an
+      # entity leaving one edge reappears on the opposite one. From Body#wrap!. The
+      # bounds are passed in; in a scrolling game they'd come from a scene-scoped
+      # World system instead.
+      class ScreenWrap < Engine::Component
+        def initialize(width:, height:, margin: 0.0)
+          super()
+          @width = width
+          @height = height
+          @margin = margin
+        end
+
+        def update(_dt)
+          node.x = @width + @margin if node.x < -@margin
+          node.x = -@margin if node.x > @width + @margin
+          node.y = @height + @margin if node.y < -@margin
+          node.y = -@margin if node.y > @height + @margin
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    module Components
+      # Draws a single registered image centered on the node's absolute origin. It
+      # passes NO angle to the renderer: Node2D#draw already wraps a node's own draws
+      # in renderer.rotated(abs_angle, abs_x, abs_y), so the node's rotation orients
+      # the sprite — passing an angle here too would rotate it twice.
+      #
+      # `scale` is writable so a pooled entity (e.g. a multi-tier rock) can retune it on
+      # reset. `z` is the render layer (NOT the node's transform z / abs_z) — kept under
+      # @layer to say so. For an animated sprite (sheet + frame index driving
+      # renderer.sprite), add a sibling AnimatedSprite component later.
+      class Sprite < Engine::Component
+        attr_accessor :scale
+
+        def initialize(id:, scale: 1.0, z: 0)
+          super()
+          @id = id
+          @scale = scale
+          @layer = z
+        end
+
+        def draw(renderer)
+          renderer.image(@id, node.abs_x, node.abs_y, scale: @scale, z: @layer)
+        end
+      end
+    end
+  end
+end