rgame 0.4.0-x86_64-linux-gnu

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    module Components
+      # Wraps the node's position toroidally within the world bounds (plus margin), so
+      # an entity leaving one edge reappears on the opposite one.
+      #
+      # The bounds come from the scene's world system — anything answering the
+      # WorldBounds contract, so Components::World or Components::TileWorld — and are
+      # resolved when the node enters the tree. Passing `width:`/`height:` overrides
+      # that for a node whose wrap region is not the whole world.
+      #
+      # The node is tested and placed in **world space**, which is the frame WorldBounds
+      # is stated in: a node under an offset container wraps at the world's edge, not at
+      # an edge shifted by wherever the container sits. The write goes through
+      # Node2D#world_x=, so the node's local position is what actually changes.
+      #
+      # A wrap is a placement, not a step: it does not ask a sibling Mover's `blocked_by`
+      # whether the far edge is free, so a node wrapped onto a blocker is left pressed
+      # against it.
+      class ScreenWrap < Engine::Component
+        def initialize(width: nil, height: nil, margin: 0.0)
+          super()
+          @given_width = width
+          @given_height = height
+          @margin = margin
+        end
+
+        # Re-resolved on every entry rather than cached from the first, so a pooled
+        # entity recycled into a differently sized scene wraps against that scene.
+        def on_attach
+          WorldBounds.one_response!(node)
+          @width, @height = WorldBounds.resolve(node, @given_width, @given_height)
+        end
+
+        def update(_dt)
+          x = node.world_x
+          node.world_x = @width + @margin if x < -@margin
+          node.world_x = -@margin if x > @width + @margin
+
+          y = node.world_y
+          node.world_y = @height + @margin if y < -@margin
+          node.world_y = -@margin if y > @height + @margin
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    module Components
+      # Draws a single registered image centred on the node's own origin. It passes
+      # NO angle and NO position to the renderer: Node2D#draw has already pushed the
+      # node's transform, so drawing at (0, 0) *is* drawing at the node, correctly
+      # rotated. Passing either would apply it a second time.
+      #
+      # `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
+        include Engine::Culling
+
+        attr_accessor :scale
+
+        def initialize(id:, scale: 1.0, z: 0)
+          super()
+          @id = id
+          @scale = scale
+          @layer = z
+        end
+
+        # Centred on the node's origin and scaled, so the footprint to cull
+        # against is the node's box scaled and offset back by half of itself. A
+        # node that never set a size is never culled — see Culling.
+        #
+        # Culling is the one thing here still stated in **world** coordinates:
+        # it compares against the camera, which is nowhere near this node's
+        # local space. Drawing is local, culling is world, and the two are
+        # deliberately different arguments.
+        def draw(renderer, view)
+          width = node.width * @scale
+          height = node.height * @scale
+          lift = node.elevation
+          return if culled?(view, node.world_x - (width / 2.0), node.world_y - lift - (height / 2.0),
+                            width, height)
+
+          renderer.image(@id, 0, -lift, scale: @scale, z: @layer)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    module Components
+      # Picks a node for the owning node to aim at: each update it queries the scene's
+      # CollisionWorld around the node's world origin and exposes the chosen target via
+      # #target (the candidate's node, or nil). The owner reads it to act — Targeting only
+      # selects, it never moves or shoots.
+      #
+      # The CollisionWorld it queries is the same broadphase every collider registers with,
+      # so targeting needs no candidate list of its own. The `layer` restricts candidates
+      # (pass :enemy to pick only colliders on that layer, not allies or projectiles).
+      #
+      # Policies (how to choose among the candidates in range):
+      #   - :nearest — the closest candidate (the default; one broadphase nearest-lookup).
+      # More policies (e.g. furthest-along-path) arrive with the state they need.
+      class Targeting < Engine::Component
+        POLICIES = %i[nearest].freeze
+
+        def initialize(range:, policy: :nearest, layer: nil)
+          super()
+          raise ArgumentError, "unknown targeting policy #{policy.inspect}" unless POLICIES.include?(policy)
+
+          @range = range
+          @policy = policy
+          @layer = layer
+          @target = nil
+        end
+
+        # The chosen node, or nil when nothing is in range. Refreshed every update.
+        attr_reader :target
+
+        # Pull the broadphase once it's reachable (scene scope, resolved up the tree).
+        def on_attach = @world = node.system(CollisionWorld)
+
+        def update(_dt)
+          collider = pick
+          @target = collider&.node
+        end
+
+        private
+
+        def pick
+          case @policy
+          when :nearest then @world.nearest(node.world_x, node.world_y, @range, layer: @layer)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    module Components
+      # Inertial "ship" flight on top of a Velocity sibling: a turn axis rotates the
+      # node (angular velocity) and a thrust axis accelerates it along its heading,
+      # with optional drag and a top-speed clamp. Reads intent in `control` and
+      # integrates it in `update`, so it composes with the normal phase order.
+      #
+      # Heading convention: angle 0 points along +x ("right"), so forward is
+      # (cos θ, sin θ) — consistent with the renderer's clockwise rotation under a y-down screen
+      # (e.g. +90° faces down). Firing is intentionally NOT here — see ActionTrigger +
+      # the owning node, which knows its muzzle geometry.
+      class ThrustController < Engine::Component
+        def initialize(turn_speed:, accel:, max_speed:, drag: 0.0,
+                       turn_action: :turn, thrust_action: :thrust)
+          super()
+          @turn_speed = turn_speed
+          @accel = accel
+          @max_speed = max_speed
+          @drag = drag
+          @turn_action = turn_action
+          @thrust_action = thrust_action
+          @thrust = 0.0
+        end
+
+        # The Velocity sibling is only guaranteed present once attached to a node.
+        def on_attach = @velocity = require_sibling(Velocity)
+
+        def control(actions)
+          @velocity.spin = actions.axis(@turn_action) * @turn_speed
+          @thrust = actions.axis(@thrust_action)
+        end
+
+        def update(dt)
+          if @thrust != 0.0
+            @velocity.vx += Math.cos(node.angle) * @accel * @thrust * dt
+            @velocity.vy += Math.sin(node.angle) * @accel * @thrust * dt
+          end
+          apply_drag(dt) if @drag.positive?
+          clamp_speed
+        end
+
+        private
+
+        def apply_drag(dt)
+          factor = 1.0 - (@drag * dt)
+          factor = 0.0 if factor.negative?
+          @velocity.vx *= factor
+          @velocity.vy *= factor
+        end
+
+        def clamp_speed
+          speed = Math.hypot(@velocity.vx, @velocity.vy)
+          return unless speed > @max_speed
+
+          scale = @max_speed / speed
+          @velocity.vx *= scale
+          @velocity.vy *= scale
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    module Components
+      # The scene-scoped tile world: a system component (it lives on the scene node and
+      # is found with node.system(TileWorld)) that owns the parsed Engine::TileMap and
+      # everything an actor needs from it — collision against the solid tiles, the world
+      # bounds, and drawing the map through the scene's camera.
+      #
+      # **It does not resolve a step.** What it owns is the map's solid tiles as a blocker
+      # source (#blockers, an Engine::TileBlockers); the actor that wants to be stopped by
+      # them borrows it and resolves against it — see Components::Mover, which
+      # builds its own Engine::CollisionSystem out of the sources its `blocked_by` names.
+      # A mover may be blocked by tiles, by other actors, or by both, and only the mover
+      # knows which, so the resolver is the mover's and the grid is this system's. The tile
+      # solidity itself is whatever the map's tileset reports (baked per-tile in Tiled).
+      # The same solidity, viewed as a graph for planning routes, is #nav_grid.
+      #
+      # **Solidity is read from the map once**, into one Util::SolidGrid, the first time
+      # anything asks — and #blockers, #nav_grid and #solid? all read that store, never the
+      # map. So they cannot disagree about a cell, and a resolve costs a byte lookup rather
+      # than a walk through the map's layers and tileset.
+      #
+      # **It does not draw.** Drawing the map is RGame::Engine::TileMapLayer, one
+      # node per Tiled layer, mounted inside the WorldView so the map is drawn
+      # once per viewport like the rest of the world. This stays a system — the
+      # thing actors ask about collision and bounds — and a system that also
+      # drew was always the odd part of it.
+      #
+      # It owns the map's **animation clock**. Nothing below reads a wall clock —
+      # see CLAUDE.md, "`draw` renders state; time enters through `update`" — so the
+      # elapsed seconds animated tiles run on are accumulated here and handed down at
+      # draw time. Stop calling `update` and the water freezes, which is what pausing
+      # should look like.
+      class TileWorld < Engine::Component
+        include WorldBounds
+
+        attr_reader :tilemap_id, :elapsed
+
+        # `cameras` are the cameras this map bounds — every player's, normally.
+        # A camera may not show past the world's edges, and this is what knows
+        # how big the world is; the cameras themselves are owned by players.
+        def initialize(map:, tilemap_id:, cameras: [])
+          super()
+          @map = map
+          @tilemap_id = tilemap_id
+          @elapsed = 0.0
+          Array(cameras).each { |camera| bound(camera) }
+        end
+
+        # The map's solid tiles as a blocker source, for a body that declared
+        # `blocked_by: [:tiles]`. The same source every time, so every body on the map
+        # shares one.
+        def blockers
+          @blockers ||= Engine::TileBlockers.new(grid: solid_grid, tile_width: @map.tile_width,
+                                                 tile_height: @map.tile_height)
+        end
+
+        def world_width = @map.pixel_width
+        def world_height = @map.pixel_height
+
+        # The size of one cell, in pixels — what turns a world position into the cell
+        # #nav_grid plans over.
+        def tile_width = @map.tile_width
+        def tile_height = @map.tile_height
+
+        def layer_count = @map.layer_count
+
+        # The first layer Tiled flags `above`, or the layer count if none is —
+        # which is where TileMapLayer.mount leaves the gap for the actors, so a
+        # map with no flag puts them over everything. Read once at mount rather
+        # than per frame: which layers cover the actors is a fact about the
+        # scene's arrangement, and the arrangement is made once.
+        def first_above_layer
+          layer_count.times.find { |index| @map.above_layer?(index) } || layer_count
+        end
+
+        # Clamp a camera to this map's edges. Called for each camera the scene
+        # hands over, and again for one that arrives later (a player joining).
+        def bound(camera)
+          camera.world_width = @map.pixel_width
+          camera.world_height = @map.pixel_height
+          camera
+        end
+
+        def solid?(col, row) = solid_grid.solid?(col, row)
+
+        # The map's solid tiles as an Engine::NavGrid, for planning a route rather than
+        # resolving a step — over the same store #blockers reads, as a second view. Built on
+        # first ask, and the same grid every time after.
+        def nav_grid
+          @nav_grid ||= Engine::NavGrid.new(grid: solid_grid)
+        end
+
+        # Advances the tile animations. Seconds, like every other duration here.
+        def update(dt)
+          @elapsed += dt
+        end
+
+        private
+
+        def solid_grid
+          @solid_grid ||= Util::SolidGrid.build(@map.width, @map.height) { |col, row| @map.solid_tile?(col, row) }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    module Components
+      # A node-driven interval timer: it rides the node's update tick — so nothing can
+      # forget to advance it — and emits `on_timeout` each time a whole interval elapses.
+      # It wraps the pure Engine::Timer, reusing its carry-forward `consume` (the remainder
+      # rolls over, so the cadence doesn't drift); this only adds the per-frame drive and
+      # the signal.
+      #
+      #   timer = node.add_component(Engine::Components::Timer.new(0.8), as: :spawn)
+      #   timer.on_timeout { spawn_enemy }
+      #
+      # `repeating: false` makes it a one-shot: it fires `on_timeout` exactly once and then
+      # goes inert — the fixed-board despawn case (a projectile that vanishes after N
+      # seconds, where DespawnOffscreen doesn't apply):
+      #
+      #   life = node.add_component(Engine::Components::Timer.new(2.0, repeating: false), as: :despawn)
+      #   life.on_timeout { node.queue_free }
+      #
+      # The countdown restarts in `on_attach`, so a pooled node reacquired and re-added
+      # starts fresh — a recycled projectile gets its full interval (and a one-shot can fire
+      # again) rather than inheriting the previous life's elapsed time.
+      #
+      # When a node needs more than one (a spawn cadence and a wave cadence), give them
+      # distinct `as:` names — a node holds one component per slot.
+      class Timer < Engine::Component
+        signal :on_timeout
+
+        def initialize(interval, repeating: true)
+          super()
+          @timer = Engine::Timer.new(interval)
+          @repeating = repeating
+          @done = false
+        end
+
+        def interval = @timer.interval
+
+        def interval=(seconds)
+          @timer.interval = seconds
+        end
+
+        # Start the countdown fresh whenever the node (re-)enters the tree, so a pooled node
+        # never inherits a previous life's accumulated time or spent one-shot.
+        def on_attach = reset
+
+        # Advance one step and fire on_timeout once per whole interval that elapsed — so a
+        # single long step still emits the right number of times (catch-up, not drift). A
+        # one-shot (`repeating: false`) fires once and then stops accumulating.
+        def update(dt)
+          return if @done
+
+          @timer.update(dt)
+          while @timer.ready?
+            @timer.consume
+            on_timeout_signal.emit
+            unless @repeating
+              @done = true
+              break
+            end
+          end
+        end
+
+        # Back to a fresh timer: drop accumulated time and re-arm a spent one-shot (e.g.
+        # after retuning the interval, or when a pooled node is reused). Returns self.
+        def reset
+          @timer.reset
+          @done = false
+          self
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    module Components
+      # Integrates linear and angular velocity into the node's transform each step.
+      # Free-moving entities (rocks, bullets) use it alone; a controller component
+      # (or the node's own control hook) writes vx/vy/spin as intent.
+      #
+      # A Mover, so `blocked_by:` stops it the way it stops a CharacterBody — see Mover's
+      # header. A blocked step keeps `vx`/`vy` as they were: they are the intent, and what
+      # a stop should do to them (nothing, zero them, bounce) is the game's call, made in
+      # an `on_blocked` handler.
+      class Velocity < Mover
+        attr_accessor :vx, :vy, :spin
+
+        def initialize(vx: 0.0, vy: 0.0, spin: 0.0, blocked_by: [])
+          super(blocked_by: blocked_by)
+          @vx = vx
+          @vy = vy
+          @spin = spin
+        end
+
+        # The velocity scaled so its larger axis is ±1 — the direction, without the square
+        # root a unit vector would cost.
+        def heading_x = scale_to_heading(@vx)
+        def heading_y = scale_to_heading(@vy)
+
+        private
+
+        def scale_to_heading(axis)
+          larger = [@vx.abs, @vy.abs].max
+          larger.zero? ? 0.0 : axis / larger.to_f
+        end
+
+        def take_step(dt)
+          apply_move(@vx * dt, @vy * dt)
+          node.angle += @spin * dt
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    module Components
+      # A simple AI driver for a CharacterBody sibling: every so often it rolls a new
+      # direction (one of eight, or idle) and holds it until a timer elapses — or until a
+      # wall blocks it, at which point it re-rolls early instead of pushing into the wall.
+      # The RNG is injected so behaviour is deterministic in tests.
+      #
+      # "Blocked" is measured as *the node did not move while intending to*, not asked of
+      # a collision world — so this works over any CharacterBody, and simply never fires
+      # for one whose steps always land.
+      class WanderController < Engine::Component
+        MOVED_EPS = 1e-6
+        DIRECTIONS = [
+          [-1, 0], [1, 0], [0, -1], [0, 1],
+          [-1, -1], [1, -1], [-1, 1], [1, 1]
+        ].freeze
+
+        def initialize(rng: Random.new, change_interval: 1.0..3.0, idle_chance: 0.25)
+          super()
+          @rng = rng
+          @change_interval = change_interval
+          @idle_chance = idle_chance
+          @timer = 0.0
+        end
+
+        def on_attach
+          @body = require_sibling(CharacterBody)
+          @last_x = node.x
+          @last_y = node.y
+        end
+
+        def update(dt)
+          blocked = intending_to_move? && !moved_since_last?
+          @last_x = node.x
+          @last_y = node.y
+
+          @timer -= dt
+          reroll if blocked || @timer <= 0.0
+        end
+
+        private
+
+        def intending_to_move? = !@body.move_x.zero? || !@body.move_y.zero?
+
+        def moved_since_last?
+          (node.x - @last_x).abs > MOVED_EPS || (node.y - @last_y).abs > MOVED_EPS
+        end
+
+        def reroll
+          if @rng.rand < @idle_chance
+            @body.set_intent(0.0, 0.0)
+          else
+            dx, dy = DIRECTIONS.sample(random: @rng)
+            @body.set_intent(dx.to_f, dy.to_f)
+          end
+          @timer = @rng.rand(@change_interval)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    module Components
+      # How big the world is — the contract, not an implementation.
+      #
+      # Two systems answer it: `World` below, which is nothing *but* the answer,
+      # and `TileWorld`, which derives it from the map it parsed. A component
+      # that needs bounds asks for the contract — `node.system(WorldBounds)` —
+      # and gets whichever of the two the scene mounted. That works because
+      # Node2D#get_component matches with `is_a?`, which matches an included
+      # module as readily as a class.
+      #
+      # Naming the contract is what keeps the two from drifting: ScreenWrap does
+      # not know which kind of world it is wrapping inside, and must not need to.
+      #
+      # ## The bounds are in world coordinates
+      #
+      # The world runs from (0, 0) to (world_width, world_height) in **world**
+      # space — the space `Node2D#world_x` answers in, and the one the tile grid,
+      # the collision world and the camera already use. So everything that
+      # compares a node against these bounds compares `world_x`/`world_y`, never
+      # the node's local `x`/`y`: an entity grouped under an offset container is
+      # still inside the world when it is, whatever its position in the container.
+      # spec/support/shared_examples/a_world_edge_response.rb holds every reader to it.
+      module WorldBounds
+        def world_width = raise(NotImplementedError, "#{self.class} must define #world_width")
+        def world_height = raise(NotImplementedError, "#{self.class} must define #world_height")
+
+        # The bounds a component should use: whatever it was handed, falling back
+        # to the world system on `node` for either axis left nil. The single place
+        # that fallback is written, so the components sharing it cannot drift.
+        #
+        # Call it from `on_attach`, not `initialize` — a node has no scene to ask
+        # until it is in the tree, and a pooled entity is built long before it is.
+        def self.resolve(node, width, height)
+          return [width, height] if width && height
+
+          bounds = node.system(self)
+          if bounds.nil?
+            raise 'no world bounds in scope: mount a World (or TileWorld) system on the scene, ' \
+                  'or pass explicit width:/height:'
+          end
+
+          [width || bounds.world_width, height || bounds.world_height]
+        end
+
+        # Refuse a node carrying more than one response to the edge of the world:
+        # ScreenWrap, DespawnOffscreen, or a Mover declaring `blocked_by: [:bounds]`.
+        #
+        # Stopping at the edge, wrapping past it and being freed beyond it are three
+        # answers to one question, and no two of them mean anything together. Stop and
+        # wrap disagree about where the node ends up; wrap and despawn race on which
+        # margin is reached first; and the stop works on the collision box while the
+        # other two test the node's origin, so a box with an offset holds the origin
+        # just past the edge and the other response fires on a node that was held.
+        # Rather than a rule each game has to remember, it raises.
+        #
+        # Folding wrap and despawn into Mover as one `at_edge:` option would make two
+        # responses inexpressible too, but they act on the node however it moved — a reset,
+        # an ancestor, a direct write — and every option there is a branch on the free
+        # step's path. A refusal at attach costs no frame anything. It is also the place
+        # to change if a game wants wrapping on one axis and stopping on the other: the
+        # rule then becomes one response per axis.
+        #
+        # Every response calls this from its own on_attach, which is what makes it
+        # order-free: a node assembled outside the tree already holds all its
+        # components when the first attaches, and on a live node each attaches on
+        # arrival, so the second response always finds the first.
+        #
+        # A pooled node re-attaches on every spawn, so this walks the components
+        # without allocating, and builds a message only when it raises.
+        def self.one_response!(node)
+          first = nil
+          node.components.each do |component|
+            next unless edge_response?(component)
+            next first = component if first.nil?
+
+            raise "#{node.class} has two responses to the edge of the world: " \
+                  "#{describe_response(first)} and #{describe_response(component)}. " \
+                  'A node can stop at the edge, wrap past it or be freed beyond it, but ' \
+                  'only one of those — keep the one this node is for.'
+          end
+        end
+
+        def self.edge_response?(component)
+          component.is_a?(ScreenWrap) || component.is_a?(DespawnOffscreen) ||
+            (component.is_a?(Mover) && component.blocked_by?(Mover::BOUNDS))
+        end
+        private_class_method :edge_response?
+
+        def self.describe_response(component)
+          name = component.class.name&.split('::')&.last || component.class.inspect
+          component.is_a?(Mover) ? "#{name} (blocked_by :bounds)" : name
+        end
+        private_class_method :describe_response
+      end
+
+      # The scene-scoped world: how big it is, and nothing else yet.
+      #
+      # A game whose world is a plain rectangle mounts one on its scene, and the
+      # components that need bounds — ScreenWrap, DespawnOffscreen — find it
+      # rather than having the numbers threaded through every constructor between
+      # the scene and the entity. That threading is what this replaces, and it was
+      # worse than it looks: a pooled entity is built outside the tree, so its
+      # factory had to close over the size, and every scene above the factory had
+      # to carry the size in order to build it.
+      #
+      # It is deliberately **not** the window size. The two coincide in a
+      # single-screen game, which is exactly what makes the mistake easy to make
+      # and hard to see: bind wrapping to the viewport and the world silently
+      # changes shape when the window is resized, or when the screen is split and
+      # each half is its own viewport. Ask `Viewports` (or the `View` a draw is
+      # handed) how big the *window* is; ask this how big the *world* is.
+      #
+      # The bounds are immutable, which is what lets the components resolve them
+      # once at attach rather than re-reading them every frame. A world that
+      # genuinely changes size is a new scene.
+      class World < Engine::Component
+        include WorldBounds
+
+        attr_reader :world_width, :world_height
+
+        def initialize(width:, height:)
+          super()
+          @world_width = width
+          @world_height = height
+        end
+      end
+    end
+  end
+end