rgame 0.1.0

data/lib/rgame/engine/matrix.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    # A fixed-size 2-D grid backed by a single flat (row-major) array, addressed as
+    # [x, y]. The flat backing keeps the whole grid in one contiguous allocation —
+    # cheaper than an array-of-arrays and a straightforward shape to later move into a
+    # C-level buffer. Pure; no bounds checking on the hot path (callers stay in range).
+    #
+    # This stays Ruby, unlike the engine's old `Tensor`, which was deleted in
+    # favour of the C `RGame::Util::Tensor`. The reason is only that there is no
+    # C `Util::Matrix` to swap to — `Util` holds `Tensor`, `Controls` and
+    # `Color`. If one is ever written, this is the caller to point at it.
+    class Matrix
+      attr_reader :width, :height
+
+      def initialize(width, height, initial: nil)
+        @width = width
+        @height = height
+        @data = Array.new(width * height, initial)
+      end
+
+      def [](x, y)
+        @data[(y * @width) + x]
+      end
+
+      def []=(x, y, value)
+        @data[(y * @width) + x] = value
+      end
+    end
+  end
+end

data/lib/rgame/engine/node2d.rb

@@ -0,0 +1,271 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    # A node in a scene graph. We currently have only 2D nodes, but the
+    # name reflects this should there ever be a 3D space. Nodes are
+    # containers for both containers and nodes. They extend the signal
+    # DSL to allow for easy signal usage.
+    class Node2D
+      extend Engine::Signal::DSL
+
+      attr_accessor :x, :y, :z, :angle, :width, :height, :parent
+      attr_writer :scene, :context
+      attr_reader :children, :components, :abs_x, :abs_y, :abs_z, :abs_angle
+
+      def initialize(x: 0, y: 0, z: 0, angle: 0, width: 0, height: 0)
+        @x = x
+        @y = y
+        @z = z
+        @angle = angle
+        @width = width
+        @height = height
+        @children = []
+        @components = []
+        @component_slots = {} # slot (Class by default, or a Symbol name) => component
+        @parent = nil
+        @scene = nil
+        @in_tree = false
+        @freed = false
+      end
+
+      def add_node(node)
+        @children << node
+        node.parent = self
+        # Defer the entered-tree cascade until this node is itself live; otherwise it
+        # fires when an ancestor enters (see #enter_tree). This is the construct-vs-enter
+        # split — a node built inside another node's initialize is not yet in the tree.
+        node.enter_tree if @in_tree
+        node
+      end
+
+      def remove_node(node)
+        node.exit_tree if @in_tree
+        @children.delete(node)
+        node.parent = nil
+        node
+      end
+
+      # Look a component up by its slot. A Class/Module is matched by ancestry across every
+      # component (so a base class finds a subclass instance); a Symbol names a specific slot
+      # (see #add_component's `as:`). A class lookup raises when it's ambiguous — two
+      # components share that type — so the caller reaches for the name instead. The scan is
+      # allocation-free, so it's safe to call on the per-frame path.
+      def get_component(key)
+        return @component_slots[key] unless key.is_a?(Module)
+
+        found = nil
+        @components.each do |component|
+          next unless component.is_a?(key)
+          raise ArgumentError, "Multiple components match #{key}; look one up by name" if found
+
+          found = component
+        end
+        found
+      end
+
+      # Attach a component in a named slot. The slot defaults to the component's class, so a
+      # node still holds at most one component per class — until you give them distinct
+      # names: `add_component(Timer.new, as: :spawn)` / `add_component(Timer.new, as: :wave)`.
+      # A taken slot raises, so an accidental duplicate is still caught.
+      def add_component(component, as: nil)
+        slot = as || component.class
+        raise ArgumentError, "Node already has a component in slot #{slot.inspect}" if @component_slots.key?(slot)
+
+        @components << component
+        @component_slots[slot] = component
+        component.node = self
+        component.on_attach if @in_tree
+        component
+      end
+
+      def remove_component(key)
+        component = get_component(key)
+        return nil unless component
+
+        component.on_detach if @in_tree
+        @components.delete(component)
+        @component_slots.delete(@component_slots.key(component))
+        component.node = nil
+        component
+      end
+
+      # Anchors, resolved by walking parents so they can never go stale (a cached
+      # back-link set at add-time breaks when children are built before the node is
+      # in the tree). Shared systems live as components on an anchor node and are
+      # reached through these, not threaded through constructors.
+
+      # The top-most node — a node with no parent is its own root. Global,
+      # program-lifetime systems live here as components.
+      def root
+        @parent ? @parent.root : self
+      end
+
+      # The nearest enclosing scene node, marked as a boundary by SceneStack
+      # (#scene= self). Scene-lifetime systems live on it as components.
+      def scene
+        @scene || @parent&.scene
+      end
+
+      def context
+        @context ||= root.context
+      end
+
+      # Nearest system of a class: scene scope first, then the global root.
+      def system(klass)
+        scene&.get_component(klass) || root.get_component(klass)
+      end
+
+      # updates input, both from player (readings actions) as well as
+      # AI-driven node control. This run first in a game tick
+      # Each phase settles this node first (components, then the node's own
+      # hook), then descends into children. Self-before-subtree keeps the
+      # transform flowing downward: a component or hook that moves this node
+      # does so before children resolve their origin from it.
+
+      def control(actions)
+        resolve_origin
+        @components.each { it.control(actions) }
+        on_control(actions)
+        @children.each { it.control(actions) }
+      end
+
+      # update game logic and physics (might become two calls with
+      # time, but for now works in one step). This runs second in a
+      # game tick
+      def update(dt)
+        resolve_origin
+        @components.each { it.update(dt) }
+        on_update(dt)
+        @children.each { it.update(dt) }
+      end
+
+      # update visual game state, drawing the node. This runs last in
+      # a game tick
+      def draw(renderer)
+        resolve_origin
+        # Draw this node's own visuals oriented by its absolute angle, then descend.
+        # Children resolve their own world transform (resolve_origin already baked this
+        # node's rotation into their abs_x/abs_y), so they draw in flat world space and
+        # must NOT be nested inside this node's rotation — nesting would apply that
+        # rotation to them a second time. Unrotated nodes skip the wrapper entirely.
+        if abs_angle.zero?
+          draw_content(renderer)
+        else
+          renderer.rotated(abs_angle * 180.0 / Math::PI, abs_x, abs_y) { draw_content(renderer) }
+        end
+        draw_children(renderer)
+      end
+
+      def in_tree? = @in_tree
+
+      # Deferred removal (à la Godot's queue_free): mark this node for removal
+      # instead of detaching it now. A node that removes itself or a sibling
+      # mid-traversal would mutate the parent's @children while it's being iterated;
+      # marking instead and sweeping once after the tick (see #sweep_freed, flushed by
+      # the platform loop) keeps removal safe and allocation-free.
+      def queue_free = @freed = true
+      def freed? = @freed
+
+      # Detach every node marked by #queue_free, depth-first, from a point outside the
+      # update traversal. Components get a hook too, so a container-style component
+      # (e.g. SceneStack) can flush the subtree it owns off the normal child list.
+      def sweep_freed
+        @components.each(&:sweep_freed)
+        i = 0
+        while i < @children.size
+          child = @children[i]
+          if child.freed?
+            remove_node(child) # detaches + exit_tree; @children shrinks, so don't advance i
+          else
+            child.sweep_freed
+            i += 1
+          end
+        end
+      end
+
+      # Entered-tree cascade: anchors (root/scene) and sibling systems are now
+      # reachable, so components attach (register with systems) before this node's
+      # own on_add, and the whole subtree enters depth-first. The engine fires this
+      # — the user never calls it — so registration can't be forgotten. Idempotent.
+      def enter_tree
+        return if @in_tree
+
+        @in_tree = true
+        @freed = false # revive: a pooled node reacquired after death re-enters here
+        @components.each(&:on_attach)
+        on_add
+        @children.each(&:enter_tree)
+      end
+
+      # Leaving-tree cascade: mirror of #enter_tree (children first, then this
+      # node's on_remove, then component on_detach to release registrations).
+      def exit_tree
+        return unless @in_tree
+
+        @children.each(&:exit_tree)
+        on_remove
+        @components.each(&:on_detach)
+        @in_tree = false
+      end
+
+      # Lifecycle hooks: Subclasses should implement these instead of
+      # overwriting the public interface draw/update/add etc. on_add/on_remove
+      # fire when the node enters/leaves the live tree (see #enter_tree), not at
+      # construction — so anchors and systems are available inside them.
+
+      def on_control(actions); end
+      def on_update(dt); end
+      def on_draw(renderer); end
+      def on_add; end
+      def on_remove; end
+
+      private
+
+      # This node's own drawing: its components and its draw hook, in that order.
+      # Wrapped in renderer.rotated by #draw when the node carries an absolute angle.
+      def draw_content(renderer)
+        @components.each { it.draw(renderer) }
+        on_draw(renderer)
+      end
+
+      # Draw the child subtrees. Its own method so a node can wrap the whole subtree's
+      # draw in a transform — e.g. CameraView wraps it in renderer.translated to apply a
+      # camera offset, without each child knowing about the camera.
+      def draw_children(renderer)
+        @children.each { it.draw(renderer) }
+      end
+
+      # TODO: Calculate (and cache?) depth
+      # depth = z + highest z of children, maybe +1?
+
+      # Resolve this node's absolute transform from the parent origin passed down by the
+      # traversal. Relative x/y/z/angle accumulate, so a nested Node offsets, re-layers
+      # and rotates its whole subtree: a child's local (x, y) is rotated by the parent's
+      # accumulated angle before being added to the parent's origin.
+      # TODO: Do not recalculate every time, but use a @dirty flag
+      # TODO: Handle z better - offset not by Z of the parent, but their
+      #       depth
+      def resolve_origin
+        if @parent.nil?
+          @abs_x = @abs_y = @abs_z = 0
+          @abs_angle = 0 # root pinned to identity, like its position
+          return
+        end
+
+        pa = @parent.abs_angle
+        if pa.zero? # fast path: parent unrotated -> plain translation, no trig
+          @abs_x = @parent.abs_x + @x
+          @abs_y = @parent.abs_y + @y
+        else
+          cos = Math.cos(pa)
+          sin = Math.sin(pa)
+          @abs_x = @parent.abs_x + (@x * cos) - (@y * sin)
+          @abs_y = @parent.abs_y + (@x * sin) + (@y * cos)
+        end
+        @abs_z     = @parent.abs_z + @z
+        @abs_angle = pa + @angle
+      end
+    end
+  end
+end

data/lib/rgame/engine/path.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    # An ordered polyline of waypoints an entity walks along — the "road" of a tower
+    # defense level. Pure data: it holds the waypoints and the precomputed per-segment
+    # lengths, so a follower walking it at runtime allocates nothing.
+    #
+    # Waypoints are stored flat (x0, y0, x1, y1, …) in one contiguous array rather than a
+    # pair-object per point, and read back through scalar accessors (`x_at`/`y_at`), so
+    # neither construction shape nor traversal leaks per-waypoint Arrays onto the hot path.
+    # A follower (see Components::PathFollow) reads segments by index and interpolates
+    # itself; Path never returns a coordinate pair.
+    class Path
+      attr_reader :length, :count
+
+      # `points` is an Array of [x, y] waypoint pairs in walk order (construction-time, so
+      # the pair Arrays are fine here). At least two are required — a path with one point
+      # has nowhere to walk.
+      def initialize(points)
+        raise ArgumentError, 'a Path needs at least two waypoints' if points.length < 2
+
+        @coords = points.flatten.freeze
+        @count = points.length
+        @segment_lengths, @length = build_segments
+      end
+
+      # World coordinates of waypoint `i` (0-based), as scalars (no allocation).
+      def x_at(index) = @coords[index * 2]
+      def y_at(index) = @coords[(index * 2) + 1]
+
+      # Length of the segment from waypoint `i` to waypoint `i + 1`. There are
+      # `count - 1` segments, indexed 0..count-2.
+      def segment_length(index) = @segment_lengths[index]
+
+      # Shortest distance from the point (x, y) to the polyline — e.g. how far a spot is
+      # from the road, so a tower-defense level can mask placement cells that sit on it.
+      # Pure scalar maths, allocation-free.
+      def distance_to(x, y)
+        min = Float::INFINITY
+        (@count - 1).times do |i|
+          d = segment_distance(x, y, x_at(i), y_at(i), x_at(i + 1), y_at(i + 1))
+          min = d if d < min
+        end
+        min
+      end
+
+      private
+
+      # Distance from (px, py) to the segment (ax, ay)-(bx, by): project the point onto the
+      # segment, clamp the projection to the segment's ends, and measure to that foot.
+      def segment_distance(px, py, ax, ay, bx, by)
+        abx = bx - ax
+        aby = by - ay
+        len2 = (abx * abx) + (aby * aby)
+        t = len2.zero? ? 0.0 : (((px - ax) * abx) + ((py - ay) * aby)) / len2
+        t = 0.0 if t < 0.0
+        t = 1.0 if t > 1.0
+        dx = px - (ax + (t * abx))
+        dy = py - (ay + (t * aby))
+        Math.sqrt((dx * dx) + (dy * dy))
+      end
+
+      def build_segments
+        lengths = []
+        total = 0.0
+        (@count - 1).times do |i|
+          dx = x_at(i + 1) - x_at(i)
+          dy = y_at(i + 1) - y_at(i)
+          len = Math.sqrt((dx * dx) + (dy * dy))
+          lengths << len
+          total += len
+        end
+        [lengths.freeze, total]
+      end
+    end
+  end
+end

data/lib/rgame/engine/pool.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    # A reuse-don't-allocate pool for many short-lived, homogeneous objects —
+    # bullets, particles, transient enemies. Acquired objects come from a free list
+    # (or the factory when the list is empty) so steady-state spawning allocates
+    # nothing. Pure logic; no graphics.
+    #
+    #   pool = Engine::Pool.new { Bullet.new }
+    #   b = pool.acquire        # recycled or freshly built
+    #   pool.each { |b| b.update(dt) }
+    #   pool.reclaim_if(&:dead?) # sweep dead → free list, once per frame
+    #
+    # The factory builds a blank object; callers re-initialise it after `acquire`.
+    class Pool
+      def initialize(&factory)
+        @factory = factory
+        @free = []
+        @active = []
+      end
+
+      attr_reader :active
+
+      def acquire
+        obj = @free.empty? ? @factory.call : @free.pop
+        @active.push(obj)
+        obj
+      end
+
+      def each(&) = @active.each(&)
+
+      def size = @active.size
+
+      # No live (acquired, not-yet-reclaimed) objects.
+      def empty? = @active.empty?
+
+      # Deferred removal: sweep the active list once, moving every object for which
+      # the block returns true onto the free list. Safe to call after iterating with
+      # `each` — never mutate the active list mid-iteration; mark objects dead during
+      # the frame and reclaim them here.
+      def reclaim_if
+        @active.reject! do |obj|
+          dead = yield(obj)
+          @free.push(obj) if dead
+          dead
+        end
+      end
+    end
+  end
+end

data/lib/rgame/engine/resettable.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    # Builds value-object classes for pooling. Like `Data.define`, instances expose
+    # read-only accessors and carry their fields as a unit — but where a `Data` value
+    # is fully immutable (every change means a fresh allocation), these add exactly
+    # one mutation: `reset`, which overwrites all fields at once and returns self.
+    #
+    # That is the only mutability a pool needs: acquire a recycled instance and
+    # `reset` it, without exposing the per-field setters a `Struct` would. The methods
+    # are generated fixed-arity with direct ivar assignment (as Struct/Data do), so
+    # `reset` is allocation-free and recycling stays zero-allocation in steady state.
+    #
+    # Positional by default; pass `keyword_init: true` for keyword fields. Keywords
+    # are *also* allocation-free here because they are generated as named parameters
+    # (`reset(x:, y:)`), not a `**kwargs` splat — the splat is the one form that builds
+    # a Hash per call.
+    #
+    #   Point = Engine::Resettable.define(:x, :y)
+    #   p = Point.new(3, 4); p.x            # => 3
+    #   p.reset(5, 6)                       # same object, new values; returns p
+    #
+    #   Event = Engine::Resettable.define(:type, :payload, keyword_init: true)
+    #   e = Event.new(type: :hit, payload: 10)
+    #   e.reset(type: :lose, payload: nil)  # same object; returns e
+    #   e.respond_to?(:type=)               # => false (no setters)
+    #
+    # Field names are generated into real methods, so they must be plain identifiers.
+    module Resettable
+      IDENTIFIER = /\A[a-z_][a-zA-Z0-9_]*\z/
+
+      def self.define(*fields, keyword_init: false)
+        fields.each do |field|
+          raise ArgumentError, "invalid field name: #{field.inspect}" unless field.to_s.match?(IDENTIFIER)
+        end
+
+        params = fields.map { |f| keyword_init ? "#{f}:" : f.to_s }.join(', ')
+        assign = fields.map { |f| "@#{f} = #{f}" }.join("\n")
+
+        Class.new do
+          class_eval(<<~RUBY, __FILE__, __LINE__ + 1)
+            # For fields [:x, :y] this generates (keyword_init makes `x, y` -> `x:, y:`):
+            #   attr_reader :x, :y
+            #   def initialize(x, y)
+            #     @x = x; @y = y
+            #   end
+            #   def reset(x, y)
+            #     @x = x; @y = y
+            #     self
+            #   end
+            attr_reader #{fields.map { |f| ":#{f}" }.join(', ')}
+
+            def initialize(#{params})
+              #{assign}
+            end
+
+            def reset(#{params})
+              #{assign}
+              self
+            end
+          RUBY
+        end
+      end
+    end
+  end
+end

data/lib/rgame/engine/scene/scene_stack.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    module Scene
+      class SceneStack < Engine::Component
+        def initialize
+          super
+          @stack = []
+        end
+
+        def push(scene)
+          @stack.push(scene)
+          scene.parent = node          # so scene.root resolves up to the host
+          scene.scene = scene          # mark the scene as its subtree's scene boundary
+          scene.enter_tree             # cascades on_attach/on_add through the scene
+          self
+        end
+
+        def pop
+          scene = @stack.pop
+          return self unless scene
+
+          scene.exit_tree              # cascades on_remove/on_detach, releasing systems
+          scene.scene = nil
+          scene.parent = nil
+          self
+        end
+
+        def replace(scene)
+          pop
+          push(scene)
+        end
+
+        def current
+          @stack.last
+        end
+
+        def control(actions)
+          return unless (current_scene = current)
+
+          current_scene.control(actions)
+        end
+
+        def update(dt)
+          return unless (current_scene = current)
+
+          current_scene.update(dt)
+        end
+
+        def draw(renderer)
+          @stack.each do |scene|
+            scene.draw(renderer)
+          end
+        end
+
+        # Scenes live in @stack, off the host's child list, so the host's #sweep_freed
+        # can't reach them — forward the sweep into the active scene's subtree.
+        def sweep_freed
+          current&.sweep_freed
+        end
+      end
+    end
+  end
+end

data/lib/rgame/engine/signal.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    module Signal
+      IDENTIFIER = /\A[a-z_][a-zA-Z0-9_]*\z/
+
+      # Class-level DSL for declaring signal "slots" so a host class need not hand-write
+      # the connect-forwarding boilerplate. `extend Engine::Signal::DSL`, then:
+      #
+      #   signal :on_clicked               # a no-arg signal
+      #   signal :on_changed, ChangeSignal # a typed signal (Signal.define(:index, :value))
+      #
+      # For :on_clicked this generates:
+      #   def on_clicked(&block) = on_clicked_signal.connect(&block) # public: subscribe, returns handle
+      #   def on_clicked_signal = (@on_clicked ||= type.new)         # private: the Signal, to emit on
+      #
+      # The Signal is built lazily on first use, so the host wires nothing in #initialize;
+      # emit from inside the host via the private `<name>_signal` reader.
+      module DSL
+        def signal(name, type = Signal.define)
+          ivar = :"@#{name}"
+          reader = :"#{name}_signal"
+
+          define_method(reader) do
+            instance_variable_get(ivar) || instance_variable_set(ivar, type.new)
+          end
+          private reader
+
+          define_method(name) { |&block| send(reader).connect(&block) }
+        end
+      end
+
+      def self.define(*fields)
+        fields.each do |field|
+          raise ArgumentError, "invalid field name: #{field.inspect}" unless field.to_s.match?(IDENTIFIER)
+        end
+
+        params = fields.size == 1 ? fields.first : fields.map { |f| "#{f}:" }.join(', ')
+        args = fields.join(', ')
+
+        Class.new do
+          class_eval(<<~RUBY, __FILE__, __LINE__ + 1)
+            # For fields [:x, :y] this generates:
+            #   def initialize
+            #     @listeners = []
+            #   end
+            #   def connect(&callback)
+            #     @listeners << callback
+            #     callback
+            #   end
+            #   def disconnect(handle) = @listeners.delete(handle)
+            #   def emit(x:, y:)
+            #     @listeners.each { it.call(x, y) }
+            #   end
+
+            def initialize
+              @listeners = []
+            end
+
+            def connect(&callback)
+              @listeners << callback
+              callback
+            end
+
+            def disconnect(handle) = @listeners.delete(handle)
+            def emit(#{params})
+              @listeners.each { it.call(#{args}) }
+            end
+          RUBY
+        end
+      end
+    end
+  end
+end