rgame 0.1.0 → 0.3.0

data/lib/rgame/engine/node2d.rb

@@ -8,21 +8,246 @@ module RGame
     # DSL to allow for easy signal usage.
     class Node2D
       extend Engine::Signal::DSL
-
-      attr_accessor :x, :y, :z, :angle, :width, :height, :parent
+      extend Engine::SealedPrivates
+
+      # This node's transform **in its parent's space** — where it sits inside
+      # whatever contains it, and the only position a node ever sets. `x`, `y`
+      # and `angle` are the short spelling of the same three, because that is
+      # what reads well where a node moves itself:
+      #
+      #   def on_update(dt) = self.x += @speed * dt
+      #
+      # Not for drawing, though it is tempting: `on_draw` runs with the renderer
+      # already on this node (see #_in_local_space), so drawing at `x` offsets by
+      # this node's own position a second time. `Game/DrawInLocalSpace` says so.
+      #
+      # The ivar carries the longer name so that `@x` does not exist. Reaching
+      # for a parent-relative coordinate where a world one was meant is the
+      # mistake this whole design is arranged against, and the spelling that used
+      # to make it silent is simply not there any more.
+      attr_reader :rel_x, :rel_y, :rel_angle
+      alias x rel_x
+      alias y rel_y
+      alias angle rel_angle
+
+      attr_accessor :width, :height
+
+      # Height above the ground in pixels, for a top-down view: how far this
+      # node's picture is drawn above the spot it stands on. Positive is up.
+      #
+      # It is **not** part of the transform. `y`, `world_y`, colliders, cameras
+      # and children all ignore it, which is what lets a character leave the
+      # ground without its feet box leaving too. Components::Sprite and
+      # Components::AnimatedSprite draw lifted by it, in the node's local space;
+      # Components::Hop is one thing that writes it.
+      attr_accessor :elevation
       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
+      # The other way a node moves, and the only one that does not go through a
+      # coordinate writer: its `x`/`y` do not change, but they are now an offset
+      # from somewhere else. Set by #add_node and #remove_node — a game does not
+      # call this — and it invalidates the subtree for the same reason a move
+      # does.
+      def parent=(value)
+        @parent = value
+        _soil
+      end
+
+      # Moving a node invalidates the world transform of the node *and its whole
+      # subtree* — every one of them is now somewhere else — but computes none of
+      # them. Whoever reads one next pays for that one.
+      #
+      # `node.x += dx` from a component (Components::Velocity does exactly that)
+      # is two writes and so two invalidations, which is why #_soil returns
+      # immediately on a subtree that is already stale.
+      def rel_x=(value)
+        @rel_x = value
+        _soil
+      end
+
+      def rel_y=(value)
+        @rel_y = value
+        _soil
+      end
+
+      def rel_angle=(value)
+        @rel_angle = value
+        _soil
+      end
+
+      alias x= rel_x=
+      alias y= rel_y=
+      alias angle= rel_angle=
+
+      # This node's transform **in world space**, accumulated from its whole
+      # ancestry. A node lives in its parent's space and is moved by setting
+      # `x`/`y`/`angle`; `world_x=`/`world_y=` below are that same move, worked
+      # out from a world position for the code that thinks in one.
+      #
+      # `world_` rather than `abs_`, because the name should say which space the
+      # value is in. `abs_band` and `abs_input_owner` keep theirs deliberately —
+      # those are *inherited* from the nearest ancestor that declares one rather
+      # than expressed in a space, and a band is not in world coordinates.
+      #
+      # **Computed on demand and cached**, which is how Godot and Unity do it and
+      # why no phase resolves this any more. Moving a node marks it and its whole
+      # subtree stale (see #_soil); the next read walks up to the nearest node
+      # still current, recomputing on the way back down. Two consequences worth
+      # knowing:
+      #
+      # - It is never stale. There is no "resolved at the top of the phase" value
+      #   to go out of date, so a node that moved, a node whose *ancestor* moved,
+      #   and a paused node under a moving ancestor all answer correctly, at any
+      #   point in any phase.
+      # - Nothing is computed for a node nobody asks about. A still frame costs
+      #   nothing at all, where resolving the tree eagerly cost a full pass per
+      #   phase whether or not anything had moved.
+      # hot-path
+      def world_x
+        _resolve_transform unless @world_current
+        @world_x
+      end
+
+      # hot-path
+      def world_y
+        _resolve_transform unless @world_current
+        @world_y
+      end
+
+      # Place the node at a world coordinate, leaving the other one where it is.
+      #
+      # For code that decides where a node goes in world space — the edge of the
+      # world, a resolved collision — and must still write the node's own, local
+      # position. The target is turned back into the parent's frame, so the
+      # answer is exact under a rotated ancestor too: there it moves the local
+      # position along *both* axes, which is what one world axis looks like from
+      # inside a turned frame.
+      #
+      # A node with no parent is pinned to the origin (see #_resolve_transform),
+      # so there is no local position that would put it anywhere else, and this
+      # changes nothing.
+      # hot-path
+      def world_x=(value)
+        return if @parent.nil?
+
+        pa = @parent.world_angle
+        if pa.zero?
+          self.rel_x = value - @parent.world_x
+        else
+          _place_in_rotated_parent(value - @parent.world_x, world_y - @parent.world_y, pa)
+        end
+      end
+
+      # hot-path
+      def world_y=(value)
+        return if @parent.nil?
+
+        pa = @parent.world_angle
+        if pa.zero?
+          self.rel_y = value - @parent.world_y
+        else
+          _place_in_rotated_parent(world_x - @parent.world_x, value - @parent.world_y, pa)
+        end
+      end
+
+      # hot-path
+      def world_angle
+        _resolve_transform unless @world_current
+        @world_angle
+      end
+
+      attr_reader :children, :components, :parent, :abs_input_owner, :z, :band, :abs_band
+
+      # Where this node sits among its **siblings**, and nowhere else.
+      #
+      # The tree is drawn depth-first with siblings in `z` order, so a node's
+      # whole subtree is drawn before or after a sibling's whole subtree —
+      # never interleaved with it. Clouds over birds over people is three
+      # children of one node at `z` 2, 1 and 0, and each of them may be built
+      # out of as many parts as it likes without any of those parts escaping.
+      #
+      # Only the *comparison* matters. `z` is never added to anything and never
+      # reaches the renderer, so its magnitude means nothing: 1 and 1_000_000
+      # behave identically if they are the only two children, and a negative is
+      # ordinary. Equal `z` keeps the order the nodes were added in.
+      #
+      # This is deliberately unlike the additive relative z it replaces
+      # (`abs_z = parent.abs_z + z`), where a node at z 2 with a child at z 5
+      # resolved to 7 and overtook a sibling at 4 — some of a node's parts in
+      # front of something the node itself was behind. See RGame::Util::Z.
+      def z=(value)
+        @z = value
+        @parent&._children_unsorted!
+      end
+
+      # Which band this node and everything under it draws in — `:world` (the
+      # default), `:hud`, `:overlay` or `:debug`. A band beats every `z` in the
+      # tree: nothing in `:world` can draw over anything in `:hud`.
+      #
+      # Inherited like `input_owner`, and normally set by a node that exists to
+      # mark one: WorldView is `:world`, PlayerLayer is `:hud`. Setting it
+      # directly is the escape hatch — a node inside the world that must draw
+      # over the HUD says `band: :overlay` and does, still clipped to whatever
+      # its ancestors allowed. That is explicit and named, which is the whole
+      # difference from the Integer bases this replaces.
+      def band=(value)
+        Util::Z.band!(value) unless value.nil?
+        @band = value
+      end
+
+      # Whose input drives this node: an RGame::Engine::Player, or nil.
+      #
+      # Inherited down the tree exactly like the transform. Set it on a node and
+      # its whole subtree reads that player, so `ship.input_owner = players[1]`
+      # is all it takes for everything under the ship to answer to player two. A
+      # node that sets none inherits its parent's, and a tree that sets none
+      # anywhere reads the primary player — which is why single player needs no
+      # mention of this at all.
+      #
+      # **Not `player`**, deliberately, and not `controller` either. `@player` is
+      # what a game's own code naturally calls its hero node, so an
+      # `attr_accessor :player` here would quietly claim that ivar out from
+      # under every scene that has one — which it did, and the symptom
+      # was the input system being handed a Node2D. `controller` is taken too:
+      # a controller is the component that produces movement intent — see
+      # Components::PlayerController — which is a different idea entirely. This
+      # name says exactly what it decides and collides with neither.
+      attr_accessor :input_owner
+
+      # A paused node skips `control` and `update` — and so does everything
+      # under it, because a subtree is only ever reached through its parent.
+      # It still **draws**: pausing is about time, not visibility, which is what
+      # lets a frozen world sit under a cutscene overlay that keeps animating.
+      #
+      #   world_view.paused = true    # the world stops; the overlay above it does not
+      #
+      # There is no `abs_paused` to go with `abs_input_owner`. Ownership has to
+      # be resolved because a node needs to know whose input it reads even when
+      # its parent claims nobody; pausing needs no resolution at all, because a
+      # paused node simply never descends.
+      attr_accessor :paused
+
+      def initialize(x: 0, y: 0, z: 0, angle: 0, width: 0, height: 0, input_owner: nil,
+                     band: nil)
+        @input_owner = input_owner
+        @paused = false
+        @rel_x = x
+        @rel_y = y
         @z = z
-        @angle = angle
+        self.band = band
+        @rel_angle = angle
         @width = width
         @height = height
+        @elevation = 0
+        @world_current = false
+        @world_x = @world_y = @world_angle = 0
+        @abs_input_owner = @input_owner
+        @abs_band = @band || Util::Z::DEFAULT
         @children = []
+        @child_seq = 0
+        @children_sorted = true
         @components = []
-        @component_slots = {} # slot (Class by default, or a Symbol name) => component
+        @component_slots = {}
         @parent = nil
         @scene = nil
         @in_tree = false
@@ -32,9 +257,8 @@ module RGame
       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._sibling_order = (@child_seq += 1)
+        @children_sorted = false
         node.enter_tree if @in_tree
         node
       end
@@ -90,11 +314,6 @@ module RGame
         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
@@ -116,45 +335,53 @@ module RGame
         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
+      # `input` is an input *source*, not one player's snapshot: an
+      # RGame::Engine::Players registry, or a bare Actions when there is only
+      # ever one answer (which is what a spec usually passes).
+      #
+      # Each node asks the source for the actions of whichever player owns it,
+      # and hands its components and its own hook that plain Actions. So a
+      # component never learns there is more than one player — `control(actions)`
+      # means the same thing it always did — while two subtrees under one tick
+      # can read two different controllers.
+      #
+      # The source is what descends, not the resolved snapshot, because
+      # ownership can change further down.
+      def control(input)
+        return if @paused
+
+        _resolve_inherited
+        actions = input.actions_for(@abs_input_owner)
         @components.each { it.control(actions) }
         on_control(actions)
-        @children.each { it.control(actions) }
+        _children_in_order.each { it.control(input) }
       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
+        return if @paused
+
         @components.each { it.update(dt) }
         on_update(dt)
-        @children.each { it.update(dt) }
+        _children_in_order.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) }
+      # `view` is the viewport being drawn into: its rectangle, and the camera
+      # (if any) it is seen through. Every node gets it, because a node cannot
+      # otherwise know where the edges of its own region are — a HUD laying out
+      # against the whole window is wrong the moment the window is one player's
+      # half of it — and because culling needs it once the world is drawn more
+      # than once. Most nodes ignore it and simply draw.
+      def draw(renderer, view)
+        _resolve_inherited
+        _in_local_space(renderer) do
+          renderer.layered(@abs_band) { _draw_content(renderer, view) }
+          draw_children(renderer, view)
         end
-        draw_children(renderer)
       end
 
       def in_tree? = @in_tree
@@ -176,7 +403,7 @@ module RGame
         while i < @children.size
           child = @children[i]
           if child.freed?
-            remove_node(child) # detaches + exit_tree; @children shrinks, so don't advance i
+            remove_node(child)
           else
             child.sweep_freed
             i += 1
@@ -192,10 +419,10 @@ module RGame
         return if @in_tree
 
         @in_tree = true
-        @freed = false # revive: a pooled node reacquired after death re-enters here
+        @freed = false
         @components.each(&:on_attach)
         on_add
-        @children.each(&:enter_tree)
+        _children_in_order.each(&:enter_tree)
       end
 
       # Leaving-tree cascade: mirror of #enter_tree (children first, then this
@@ -203,68 +430,125 @@ module RGame
       def exit_tree
         return unless @in_tree
 
-        @children.each(&:exit_tree)
+        _children_in_order.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_draw(renderer, view); 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)
+      # hot-path
+      # rubocop:disable Style/ExplicitBlockArgument -- an explicit &block would
+      # allocate a Proc for every node, every frame, per viewport. `yield` is
+      # what keeps this path allocation-free, which culling_spec asserts.
+      def _in_local_space(renderer)
+        return yield if @parent.nil?
+        return yield if @rel_x.zero? && @rel_y.zero? && @rel_angle.zero?
+
+        renderer.translated(@rel_x, @rel_y) do
+          if @rel_angle.zero?
+            yield
+          else
+            renderer.rotated(@rel_angle * 180.0 / Math::PI, 0, 0) { yield }
+          end
+        end
       end
+      # rubocop:enable Style/ExplicitBlockArgument
 
-      # 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) }
+      # hot-path
+      def _draw_content(renderer, view)
+        @components.each { it.draw(renderer, view) }
+        on_draw(renderer, view)
       end
 
-      # TODO: Calculate (and cache?) depth
-      # depth = z + highest z of children, maybe +1?
+      # hot-path
+      def draw_children(renderer, view)
+        _children_in_order.each { it.draw(renderer, view) }
+      end
 
-      # 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
+      # hot-path
+      def _children_in_order
+        _sort_children unless @children_sorted
+        @children
+      end
+
+      def _sort_children
+        @children_sorted = true
+        return if @children.size < 2
+
+        @children.sort! do |a, b|
+          order = a.z <=> b.z
+          order.zero? ? a._sibling_order <=> b._sibling_order : order
+        end
+      end
+
+      # hot-path
+      def _resolve_transform
+        @world_current = true
         if @parent.nil?
-          @abs_x = @abs_y = @abs_z = 0
-          @abs_angle = 0 # root pinned to identity, like its position
+          @world_x = @world_y = 0
+          @world_angle = 0
           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
+        pa = @parent.world_angle
+        if pa.zero?
+          @world_x = @parent.world_x + @rel_x
+          @world_y = @parent.world_y + @rel_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)
+          @world_x = @parent.world_x + (@rel_x * cos) - (@rel_y * sin)
+          @world_y = @parent.world_y + (@rel_x * sin) + (@rel_y * cos)
+        end
+        @world_angle = pa + @rel_angle
+      end
+
+      def _place_in_rotated_parent(offset_x, offset_y, pa)
+        cos = Math.cos(pa)
+        sin = Math.sin(pa)
+        self.rel_x = (offset_x * cos) + (offset_y * sin)
+        self.rel_y = (offset_y * cos) - (offset_x * sin)
+      end
+
+      protected
+
+      attr_accessor :_sibling_order
+
+      def _children_unsorted! = @children_sorted = false
+
+      # hot-path
+      def _soil
+        return unless @world_current
+
+        @world_current = false
+        # rubocop:disable Style/SymbolProc -- `&:_soil` would call through
+        # Symbol#to_proc, which dispatches publicly and so cannot reach a
+        # protected method. An explicit receiver is the only form that works
+        # here, and it allocates no more than the symbol would.
+        @children.each { it._soil }
+        # rubocop:enable Style/SymbolProc
+      end
+
+      private
+
+      # hot-path
+      def _resolve_inherited
+        if @parent.nil?
+          @abs_input_owner = @input_owner
+          @abs_band = @band || Util::Z::DEFAULT
+          return
         end
-        @abs_z     = @parent.abs_z + @z
-        @abs_angle = pa + @angle
+
+        @abs_input_owner = @input_owner || @parent.abs_input_owner
+        @abs_band = @band || @parent.abs_band
       end
     end
   end

data/lib/rgame/engine/path.rb

@@ -2,8 +2,8 @@
 
 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
+    # An ordered polyline of waypoints an entity walks along — a road, a patrol
+    # route, a track. 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
@@ -34,7 +34,7 @@ module RGame
       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.
+      # from the road, so a level can keep things from being placed on or beside it.
       # Pure scalar maths, allocation-free.
       def distance_to(x, y)
         min = Float::INFINITY
@@ -47,12 +47,10 @@ module RGame
 
       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)
+        len2 = ((abx * abx) + (aby * aby)).to_f
         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

data/lib/rgame/engine/player.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    # One person playing: their device, their bindings, their camera, and their
+    # own corner of the screen.
+    #
+    #   player = Player.new(id: 0, device: Controls.gamepad(0))
+    #   player.actions.held?(:fire)   # what they are doing this tick
+    #   player.camera                 # where they are looking
+    #   player.ui                     # their HUD and menus, in screen space
+    #
+    # ## Why the player owns these and the scene does not
+    #
+    # A world has one simulation and any number of viewers. Two players share
+    # every NPC and every tile, but not a camera, not a set of bindings, and not
+    # a menu — so those belong to the viewer. Putting the camera on the scene
+    # works exactly until there are two of them, and putting it on a node in the
+    # world is worse: it forces the world to know how many times it is drawn.
+    #
+    # This is the model Unreal calls a LocalPlayer and Unity spreads across
+    # PlayerInput plus a camera.
+    #
+    # ## The action *names* are shared, the bindings are not
+    #
+    # Every player reads `:fire`. What triggers it is per player: one on Space,
+    # one on a pad's X button, and the same InputMap can serve both because a
+    # device only answers for its own kind of input. Each player gets their own
+    # ActionMapper, so their edge queries are independent — one player's press
+    # cannot consume another's.
+    class Player
+      Controls = RGame::Util::Controls
+
+      attr_reader :id, :camera, :ui, :mapper
+      attr_accessor :name
+
+      # `device` may be nil, meaning "nobody is driving this player yet" — a
+      # seat waiting for a controller. Polling one reads as nothing held rather
+      # than raising, so a game can show "Player 2: press a button" without a
+      # special case.
+      def initialize(id: 0, device: Controls::KEYBOARD, input_map: nil, camera: nil)
+        @id = id
+        @camera = camera || Camera.new
+        @mapper = ActionMapper.new(input_map || InputMap.default, device: device)
+        @ui = Node2D.new
+        @name = nil
+      end
+
+      def device = @mapper.device
+      def active? = !@mapper.device.nil?
+
+      # Reassigning is how a hot-plug lands: the pad that just arrived in a slot
+      # becomes this player's, and their bindings and camera carry on unchanged.
+      def device=(value)
+        @mapper.device = value
+      end
+
+      # This player's input for the current tick. Set by #poll, and a reused
+      # object — hold the Player, never this.
+      def actions = @mapper.actions
+
+      def poll(backend) = @mapper.poll(backend)
+
+      # What this player's map can answer for. The vocabulary is the game's, so
+      # it is the same for every player; the bindings behind it are not.
+      def input_map = @mapper.map
+    end
+  end
+end