rgame 0.1.0 → 0.2.0

data/lib/rgame/engine/layout.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    # Where each viewport goes on screen: pure rectangle arithmetic, and nothing
+    # else.
+    #
+    #   Layout.rects(2, 640, 480)   # => [[0, 0, 640, 240], [0, 240, 640, 240]]
+    #
+    # No state, no anchors, no lifetime — so it is specced on its own with no
+    # tree and no window, which is the point of separating it from Viewports.
+    # That system holds *which* mode is current and *who* is playing; this only
+    # answers "given a count and a window, where do they go".
+    #
+    # ## Rects tile exactly
+    #
+    # Edges are computed as `(i * total) / count` rather than by multiplying a
+    # rounded size, so three rows of a 481-pixel window are 161, 160 and 160 and
+    # the last one still ends exactly at 481. Dividing first leaves a seam at the
+    # bottom of the screen that nothing draws into — a one-pixel line that looks
+    # like a rendering bug and is really a rounding one.
+    module Layout
+      # A window's worth of rows, columns or cells for `count` viewports.
+      #
+      # Two players get rows rather than columns because halving the height of a
+      # landscape window leaves each view landscape, while halving the width
+      # leaves two tall slots that fit a 2D scene badly. Three and four share a
+      # 2x2 grid, with the fourth cell left empty for three.
+      # Forwards its block with `&block` rather than re-yielding through
+      # `{ |*args| yield(*args) }`, which builds an Array per yield. Passing a
+      # block straight on allocates nothing — measured, not assumed; see the
+      # allocation example in layout_spec.rb.
+      def self.each_rect(count, width, height, &)
+        return if count <= 0
+        return yield(0, 0, 0, width, height) if count == 1
+        return each_row(count, width, height, &) if count == 2
+
+        each_cell(count, 2, 2, width, height, &)
+      end
+
+      # The same, as an Array of `[x, y, width, height]`. For specs and setup;
+      # the per-frame path uses #each_rect, which allocates nothing.
+      def self.rects(count, width, height)
+        result = []
+        each_rect(count, width, height) { |_i, x, y, w, h| result << [x, y, w, h] }
+        result
+      end
+
+      # `count` full-width rows, stacked.
+      def self.each_row(count, width, height)
+        count.times do |i|
+          top = edge(i, count, height)
+          yield(i, 0, top, width, edge(i + 1, count, height) - top)
+        end
+      end
+
+      # `count` full-height columns, side by side.
+      def self.each_column(count, width, height)
+        count.times do |i|
+          left = edge(i, count, width)
+          yield(i, left, 0, edge(i + 1, count, width) - left, height)
+        end
+      end
+
+      # The first `count` cells of a `cols` x `rows` grid, filled left to right,
+      # top to bottom.
+      def self.each_cell(count, cols, rows, width, height)
+        count.times do |i|
+          col = i % cols
+          row = i / cols
+          left = edge(col, cols, width)
+          top = edge(row, rows, height)
+          yield(i, left, top, edge(col + 1, cols, width) - left, edge(row + 1, rows, height) - top)
+        end
+      end
+
+      # The i-th boundary of `count` even divisions of `total`. Multiplying
+      # before dividing is what makes the divisions tile with no seam.
+      def self.edge(index, count, total) = (index * total) / count
+    end
+  end
+end

data/lib/rgame/engine/node2d.rb

@@ -9,18 +9,111 @@ module RGame
     class Node2D
       extend Engine::Signal::DSL
 
-      attr_accessor :x, :y, :z, :angle, :width, :height, :parent
+      attr_accessor :x, :y, :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)
+      # 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
+
+      # 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 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
+      # 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.
+      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
         @x = x
         @y = y
         @z = z
+        self.band = band
         @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
+        @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
         @parent = nil
@@ -32,6 +125,8 @@ module RGame
       def add_node(node)
         @children << node
         node.parent = self
+        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.
@@ -39,6 +134,12 @@ module RGame
         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)
@@ -123,38 +224,70 @@ module RGame
       # transform flowing downward: a component or hook that moves this node
       # does so before children resolve their origin from it.
 
-      def control(actions)
+      # `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_origin
+        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)
+        return if @paused
+
         resolve_origin
         @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)
+      # `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_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) }
+        # 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
         end
-        draw_children(renderer)
+        # Outside the block: a child takes a slot of its own, after this one.
+        draw_children(renderer, view)
       end
 
       def in_tree? = @in_tree
@@ -195,7 +328,7 @@ module RGame
         @freed = false # revive: a pooled node reacquired after death re-enters here
         @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,7 +336,7 @@ 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
@@ -216,7 +349,7 @@ module RGame
 
       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
 
@@ -224,35 +357,72 @@ module RGame
 
       # 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
+      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 — 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) }
+      # 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) }
       end
 
-      # TODO: Calculate (and cache?) depth
-      # depth = z + highest z of children, maybe +1?
+      # 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
+        @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
+        @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
+        end
+      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.
+      # 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
-      # 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_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
           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
@@ -263,7 +433,6 @@ module RGame
           @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

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

data/lib/rgame/engine/player_layer.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    # One player's own corner of the screen.
+    #
+    #   layer = scene.add_node(PlayerLayer.new(player: players[1]))
+    #   layer.add_node(inventory)
+    #
+    # Its subtree is drawn **once**, clipped to that player's viewport and
+    # translated to its corner, in screen space. That is the third kind of
+    # content a frame holds: the world is drawn once per viewport under a
+    # camera, a global overlay once across the whole window, and this once per
+    # player inside their own region.
+    #
+    # It is also the `:hud` z band's structural counterpart: everything under
+    # here draws above everything in the world, whatever either asked for.
+    #
+    # ## Its children are positioned relative to it
+    #
+    # A node at (10, 10) under this layer is ten pixels inside *that player's*
+    # region, wherever the layout has put it. The layer's translate is what does
+    # that, so the same HUD class serves either player with nothing to configure
+    # — which is the point of it being a node rather than a rect a HUD looks up.
+    #
+    # For laying out against the far edge, use the view's **size**:
+    # `view.width - margin`. `view.x` and `view.y` are where the region sits on
+    # the window and are the clip's business, not a layout origin; adding them
+    # would offset a second time.
+    #
+    # ## It says whose input its subtree reads
+    #
+    # `input_owner` is set to that player, and ownership is inherited, so a menu
+    # anywhere under here reads their controller and nobody else's. Two players
+    # with a menu open at once are independent without either one knowing the
+    # other exists — see docs/api/scene_graph.md, "Who a node answers to".
+    #
+    # ## An empty region draws nothing
+    #
+    # `Viewports#screen_for` is nil for a seat nobody is in, and for everybody
+    # while the split is collapsed — a cutscene is everyone looking at one thing,
+    # so per-player UI has no place to be. Either way this draws nothing and
+    # needs no guard at the call site.
+    class PlayerLayer < Node2D
+      # `:hud` is this player's own screen space, above every world slot and
+      # below a global overlay. It is inherited, so a menu three nodes down is
+      # in it without saying so — which is the point of the band being
+      # structural rather than a number each widget carries.
+      def initialize(player:, **)
+        super(band: :hud, **)
+        self.input_owner = player
+      end
+
+      # Whose layer this is. The same thing as `input_owner`, and stored only
+      # there: two fields would be two things to keep in step.
+      def player = input_owner
+
+      def draw(renderer, _view = nil)
+        region = system(Viewports).screen_for(player)
+        return if region.nil?
+
+        renderer.clipped(region.x, region.y, region.width, region.height) do
+          renderer.translated(region.offset_x, region.offset_y) do
+            super(renderer, region)
+          end
+        end
+      end
+    end
+  end
+end