rgame 0.2.0 → 0.3.1

data/lib/rgame/engine/node2d.rb

@@ -8,16 +8,155 @@ module RGame
     # DSL to allow for easy signal usage.
     class Node2D
       extend Engine::Signal::DSL
+      extend Engine::SealedPrivates
 
-      attr_accessor :x, :y, :angle, :width, :height, :parent
+      # 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
 
-      # Insertion order among siblings, the tie-breaker for equal `z`. Engine
-      # bookkeeping, set by the parent's #add_node the way `parent` is — not for
-      # game code, and meaningless on a node with no parent.
-      attr_accessor :sibling_order
-      attr_reader :children, :components, :abs_x, :abs_y, :abs_angle, :abs_input_owner, :z,
-                  :band, :abs_band
+      # 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.
       #
@@ -38,7 +177,7 @@ module RGame
       # front of something the node itself was behind. See RGame::Util::Z.
       def z=(value)
         @z = value
-        @parent&.children_unsorted!
+        @parent&._children_unsorted!
       end
 
       # Which band this node and everything under it draws in — `:world` (the
@@ -66,13 +205,13 @@ module RGame
       # mention of this at all.
       #
       # **Not `player`**, deliberately, and not `controller` either. `@player` is
-      # what a game's own code calls its hero node (`examples/15_tiled_world`
-      # does), 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
+      # 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:
-      # Actor#controller is the thing that produces movement intent, a different
-      # idea entirely. This name says exactly what it decides and collides with
-      # neither.
+      # 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
@@ -92,30 +231,23 @@ module RGame
                      band: nil)
         @input_owner = input_owner
         @paused = false
-        @x = x
-        @y = y
+        @rel_x = x
+        @rel_y = y
         @z = z
         self.band = band
-        @angle = angle
+        @rel_angle = angle
         @width = width
         @height = height
-        # Resolved by #resolve_origin at the top of every phase. Seeded here so
-        # a node that has not been driven yet reads as being at the origin
-        # rather than as nil — which is the same answer resolve_origin gives an
-        # unparented node, and saves every reader of abs_* from a NoMethodError
-        # on a node built but not yet ticked.
-        @abs_x = @abs_y = @abs_angle = 0
+        @elevation = 0
+        @world_current = false
+        @world_x = @world_y = @world_angle = 0
         @abs_input_owner = @input_owner
         @abs_band = @band || Util::Z::DEFAULT
         @children = []
-        # Siblings are drawn in `z` order, and in insertion order within one
-        # `z`. Ruby's sort is not stable, so insertion order is carried as a
-        # number rather than relied on — the same reason the C draw queue
-        # compares (z, order) instead of trusting qsort.
         @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
@@ -125,21 +257,12 @@ module RGame
       def add_node(node)
         @children << node
         node.parent = self
-        node.sibling_order = (@child_seq += 1)
+        node._sibling_order = (@child_seq += 1)
         @children_sorted = false
-        # 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
 
-      # A child was added, or one changed its `z`, so the child order is stale.
-      # The sort is deferred to the next traversal rather than done here, so
-      # building a scene of a thousand nodes costs one sort rather than a
-      # thousand. Called by the engine; a game only ever assigns `z`.
-      def children_unsorted! = @children_sorted = false
-
       def remove_node(node)
         node.exit_tree if @in_tree
         @children.delete(node)
@@ -191,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
@@ -217,13 +335,6 @@ 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.
-
       # `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).
@@ -239,11 +350,11 @@ module RGame
       def control(input)
         return if @paused
 
-        resolve_origin
+        _resolve_inherited
         actions = input.actions_for(@abs_input_owner)
         @components.each { it.control(actions) }
         on_control(actions)
-        children_in_order.each { it.control(input) }
+        _children_in_order.each { it.control(input) }
       end
 
       # update game logic and physics (might become two calls with
@@ -252,10 +363,9 @@ module RGame
       def update(dt)
         return if @paused
 
-        resolve_origin
         @components.each { it.update(dt) }
         on_update(dt)
-        children_in_order.each { it.update(dt) }
+        _children_in_order.each { it.update(dt) }
       end
 
       # update visual game state, drawing the node. This runs last in
@@ -267,27 +377,11 @@ module RGame
       # 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_origin
-        # This node's own drawing goes in its own layer: the renderer hands out
-        # the next slot in the node's band, and every `z:` the node passes is an
-        # offset inside it. Because the traversal takes slots in the order it
-        # reaches nodes, draw order *is* tree order — and because a slot is
-        # narrow, nothing a node draws can reach past itself. The node never
-        # asks for this and cannot forget it; see RGame::Util::Z.
-        renderer.layered(@abs_band) do
-          # 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, view)
-          else
-            renderer.rotated(abs_angle * 180.0 / Math::PI, abs_x, abs_y) { draw_content(renderer, view) }
-          end
+        _resolve_inherited
+        _in_local_space(renderer) do
+          renderer.layered(@abs_band) { _draw_content(renderer, view) }
+          draw_children(renderer, view)
         end
-        # Outside the block: a child takes a slot of its own, after this one.
-        draw_children(renderer, view)
       end
 
       def in_tree? = @in_tree
@@ -309,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
@@ -325,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_in_order.each(&:enter_tree)
+        _children_in_order.each(&:enter_tree)
       end
 
       # Leaving-tree cascade: mirror of #enter_tree (children first, then this
@@ -336,17 +430,12 @@ module RGame
       def exit_tree
         return unless @in_tree
 
-        children_in_order.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, view); end
@@ -355,85 +444,111 @@ module RGame
 
       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.
       # hot-path
-      def draw_content(renderer, view)
+      # 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
+
+      # hot-path
+      def _draw_content(renderer, view)
         @components.each { it.draw(renderer, view) }
         on_draw(renderer, view)
       end
 
-      # Draw the child subtrees. Its own method so a node can wrap the whole subtree's
-      # draw in a transform without each child knowing about it.
       # hot-path
       def draw_children(renderer, view)
-        children_in_order.each { it.draw(renderer, view) }
+        _children_in_order.each { it.draw(renderer, view) }
       end
 
-      # The children, in the order every phase visits them: by `z`, then by when
-      # they were added. Sorted lazily — a scene that never touches `z` after
-      # building sorts once and then pays one boolean per phase.
       # hot-path
-      def children_in_order
-        sort_children unless @children_sorted
+      def _children_in_order
+        _sort_children unless @children_sorted
         @children
       end
 
-      # Ruby's sort is not stable, so the insertion counter is compared
-      # explicitly. Without it two same-z siblings would swap places between
-      # frames, which reads on screen as flicker rather than as a sort problem.
-      def sort_children
+      def _sort_children
         @children_sorted = true
-        # Nothing to order, and the overwhelmingly common case for a leaf or a
-        # node with one visual — worth skipping before touching the array.
         return if @children.size < 2
 
         @children.sort! do |a, b|
           order = a.z <=> b.z
-          order.zero? ? a.sibling_order <=> b.sibling_order : order
+          order.zero? ? a._sibling_order <=> b._sibling_order : order
         end
       end
 
-      # Resolve this node's absolute transform from the parent origin passed down by the
-      # traversal. Relative x/y/angle accumulate, so a nested Node offsets 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.
-      #
-      # `z` is **not** among them, and that is the point: depth is decided by
-      # where the traversal reaches a node, not by summing what its ancestors
-      # picked. See #z= and RGame::Util::Z.
-      # TODO: Do not recalculate every time, but use a @dirty flag
-      def resolve_origin
+      # hot-path
+      def _resolve_transform
+        @world_current = true
         if @parent.nil?
-          @abs_x = @abs_y = 0
-          @abs_angle = 0 # root pinned to identity, like its position
-          @abs_input_owner = @input_owner
-          @abs_band = @band || Util::Z::DEFAULT
+          @world_x = @world_y = 0
+          @world_angle = 0
           return
         end
 
-        # Ownership accumulates the same way the transform does: this node's own
-        # if it has one, otherwise whatever it inherits. Resolved here rather
-        # than walked on demand so it costs one assignment per phase, and so it
-        # is equally available in update and draw — a HUD node drawing in its
-        # player's corner wants the same answer `control` used.
-        @abs_input_owner = @input_owner || @parent.abs_input_owner
-        # The band inherits the same way. A node that declares one overrides it
-        # for its whole subtree, which is the only way out of a band and is
-        # spelled with a name rather than a number.
-        @abs_band = @band || @parent.abs_band
-
-        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_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/players.rb

@@ -62,9 +62,6 @@ module RGame
       def initialize(players = [])
         super()
         @list = players
-        # One seat means there is no second player to become, so an unassigned
-        # device is that player picking up a controller. More than one means the
-        # game expects company.
         @on_unassigned_input = players.size > 1 ? :join : :takeover
         @accepting_joins = true
         @connected = []
@@ -96,6 +93,8 @@ module RGame
       # Nobody in particular means the primary player, which is what makes the
       # single-player path free: no node claims ownership, every node resolves
       # to nil, and every nil resolves to the one player there is.
+      #
+      # @api private
       # hot-path
       def actions_for(player)
         owner = player || primary
@@ -119,6 +118,8 @@ module RGame
 
       # A controller arrived in a slot. Recorded, not seated: this is what makes
       # the slot *scannable*, and someone using it is what seats it.
+      #
+      # @api private
       def device_connected(slot)
         @connected << slot unless @connected.include?(slot)
         self
@@ -130,6 +131,8 @@ module RGame
       #
       # Under `:takeover` there is no second player to become, so the seat falls
       # back to the keyboard rather than the game going dead in someone's hands.
+      #
+      # @api private
       def device_disconnected(slot)
         @connected.delete(slot)
         device = Controls.gamepad(slot)
@@ -157,10 +160,6 @@ module RGame
 
       private
 
-      # Watch the devices nobody is holding, and seat one when it is used.
-      #
-      # Costs nothing when there is nobody to seat: with every seat full, or the
-      # policy set to ignore, there is no candidate and no device is looked at.
       def admit(backend)
         return if @on_unassigned_input == :ignore || candidate.nil?
 
@@ -172,8 +171,6 @@ module RGame
         end
       end
 
-      # Who the next unassigned device would go to, and therefore whose bindings
-      # decide what counts as a press. Nil when nobody could take one.
       def candidate
         return primary if @on_unassigned_input == :takeover
 
@@ -191,10 +188,6 @@ module RGame
         buttons.any? { |id| backend.down?(id, device: device) }
       end
 
-      # Connected pads nobody holds — plus the keyboard, but only while taking
-      # over. The keyboard is always "connected", so under `:join` it would sit
-      # waiting to seat whoever pressed Return, which is right for some games and
-      # a surprise in most; one that wants a keyboard player seats it explicitly.
       def each_unassigned_device
         @connected.each do |slot|
           device = Controls.gamepad(slot)