rgame 0.1.0 → 0.2.0

data/lib/rgame/engine/players.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    # Who is playing, as a root-scoped system.
+    #
+    #   players = node.system(Players)
+    #   players.primary.camera
+    #   players.each_active { |player| ... }
+    #
+    # A Component on the root node, so any node reaches it by walking the tree
+    # rather than having it threaded through a constructor — the same shape
+    # CollisionWorld and TileWorld use (see docs/api/systems.md).
+    #
+    # It owns the list, polls every player's mapper once per tick, and decides
+    # who a newly used controller belongs to. It does **not** own the screen
+    # rects — those come from the layout, because they depend on how many
+    # players are active and change without the players doing so.
+    #
+    # ## Seats, and how a device comes to occupy one
+    #
+    # Every seat exists from the start; the unfilled ones are inactive and draw
+    # no viewport. So the number of seats is also the maximum number of players,
+    # rather than a separate cap that could disagree with the list.
+    #
+    # **A device is seated when someone uses it, not when it is plugged in.** A
+    # connect says something about hardware; seating a player creates a camera, a
+    # viewport and a screen split, and that should follow a statement of intent.
+    # Seating on connect drops a pad a solo player plugs in (no seat is free),
+    # splits the screen when a spare pad wakes up, and cannot be refused during a
+    # cutscene.
+    #
+    #   players.on_unassigned_input = :join   # :join | :takeover | :ignore
+    #   players.accepting_joins = false       # temporarily refuse either
+    #
+    # - `:join` — a press on an unassigned device fills the next free seat.
+    #   Couch co-op, and the default when a game asks for more than one seat.
+    # - `:takeover` — it becomes the *primary* player's device instead. Single
+    #   player, where picking up a controller is not a second person arriving,
+    #   and the default when there is one seat.
+    # - `:ignore` — the game seats devices itself, with #seat.
+    #
+    # The trigger is a **`ui_confirm` press**, read through the map of whoever
+    # would receive the device. One action rather than "any input", because a
+    # stick resting slightly off centre must never seat a player, and an edge
+    # rather than held so one press does one thing.
+    class Players < Component
+      extend Engine::Signal::DSL
+
+      Controls = RGame::Util::Controls
+
+      include Enumerable
+
+      # Fires when a device is seated, with the player who got it. A scene
+      # listens to spawn that player's avatar — which is how a game gains a
+      # second character mid-session without polling for one.
+      signal :on_joined, Engine::Signal.define(:player)
+
+      attr_reader :list
+      attr_accessor :on_unassigned_input, :accepting_joins
+
+      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 = []
+        @confirm_held = {}
+      end
+
+      # The player a single-player game means, and the one an unowned node reads
+      # from. Always present: a game with no players declared still has this one,
+      # which is what keeps single-player free of ceremony.
+      def primary = @list.first
+
+      def each(&) = @list.each(&)
+
+      # Players with a device driving them. An empty seat waiting for a
+      # controller is in `list` but not here, so a viewport loop skips it.
+      def each_active(&) = @list.select(&:active?).each(&)
+
+      def active_count = @list.count(&:active?)
+
+      def [](id) = @list.find { |player| player.id == id }
+
+      def add(player)
+        @list << player
+        player
+      end
+
+      # The input a node owned by `player` should read this tick.
+      #
+      # 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.
+      # hot-path
+      def actions_for(player)
+        owner = player || primary
+        raise 'no players are registered, so nothing can read input' if owner.nil?
+
+        owner.actions
+      end
+
+      # Every player's input for this tick, in one call. Each has their own
+      # mapper and their own previous-frame state, so one player's press cannot
+      # consume another's edge.
+      # Then the devices nobody holds are checked for someone starting to use
+      # one. Here rather than in a hot-plug hook because a *press* is a per-tick
+      # idea, and this is the one place that already has the backend and runs
+      # once a tick.
+      def poll(backend)
+        @list.each { |player| player.poll(backend) }
+        admit(backend)
+        self
+      end
+
+      # A controller arrived in a slot. Recorded, not seated: this is what makes
+      # the slot *scannable*, and someone using it is what seats it.
+      def device_connected(slot)
+        @connected << slot unless @connected.include?(slot)
+        self
+      end
+
+      # A controller left its slot. Whoever was on it loses it; their camera,
+      # bindings and UI stay exactly as they were, so plugging back in and
+      # pressing confirm resumes rather than restarts.
+      #
+      # 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.
+      def device_disconnected(slot)
+        @connected.delete(slot)
+        device = Controls.gamepad(slot)
+        seated = @list.find { |player| player.device == device }
+        seated&.device = @on_unassigned_input == :takeover ? Controls::KEYBOARD : nil
+        seated
+      end
+
+      # Give `device` to whoever should have it, and say who that was. The join
+      # path's own last step, and the one call a game running `:ignore` uses to
+      # seat devices on its own terms.
+      #
+      # Refused while `accepting_joins` is false — which covers taking over as
+      # well as joining, since both change who is holding what.
+      def seat(device)
+        return nil unless @accepting_joins
+
+        player = candidate
+        return nil if player.nil?
+
+        player.device = device
+        on_joined_signal.emit(player)
+        player
+      end
+
+      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?
+
+        each_unassigned_device do |device|
+          down = confirm_down?(backend, device)
+          was_down = @confirm_held[device]
+          @confirm_held[device] = down
+          seat(device) if down && !was_down
+        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
+
+        @list.find { |player| !player.active? }
+      end
+
+      # hot-path
+      def confirm_down?(backend, device)
+        player = candidate
+        return false if player.nil?
+
+        buttons = player.input_map[:ui_confirm]&.buttons
+        return false if buttons.nil?
+
+        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)
+          yield device unless assigned?(device)
+        end
+        return unless @on_unassigned_input == :takeover && !assigned?(Controls::KEYBOARD)
+
+        yield Controls::KEYBOARD
+      end
+
+      # hot-path
+      def assigned?(device) = @list.any? { |player| player.device == device }
+    end
+  end
+end

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

@@ -7,8 +7,13 @@ module RGame
         def initialize
           super
           @stack = []
+          @players = nil
         end
 
+        # See #control: the scenes this holds need the input source, and a
+        # component is only handed one player's snapshot.
+        def on_attach = @players = node.system(Engine::Players)
+
         def push(scene)
           @stack.push(scene)
           scene.parent = node          # so scene.root resolves up to the host
@@ -36,10 +41,24 @@ module RGame
           @stack.last
         end
 
+        # Scenes live off the host's child list, so the traversal does not reach
+        # them on its own — and what has to reach them is the input *source*,
+        # not the snapshot this component was handed.
+        #
+        # A component receives one player's resolved Actions, which is right for
+        # a component: it belongs to exactly one node. A scene is a whole subtree
+        # and may contain nodes owned by different players, so handing it a
+        # single snapshot would flatten all of them onto whoever owns the host.
+        # The registry is pulled from the tree instead, the same way any system
+        # is, and passed down so each node in the scene resolves its own.
+        #
+        # Without a registry — a spec driving a stack with a bare snapshot — the
+        # snapshot is passed on, which is exactly what it means: one answer for
+        # everyone.
         def control(actions)
           return unless (current_scene = current)
 
-          current_scene.control(actions)
+          current_scene.control(@players || actions)
         end
 
         def update(dt)
@@ -48,9 +67,12 @@ module RGame
           current_scene.update(dt)
         end
 
-        def draw(renderer)
+        # Every scene in the stack, not just the current one — that asymmetry
+        # with control/update is what lets a menu pushed on top keep the world
+        # visible underneath while freezing it.
+        def draw(renderer, view)
           @stack.each do |scene|
-            scene.draw(renderer)
+            scene.draw(renderer, view)
           end
         end
 

data/lib/rgame/engine/spatial_hash.rb

@@ -14,10 +14,23 @@ module RGame
     #   hash.query(*bullet.aabb) { |rock| ...narrowphase... }
     class SpatialHash
       # Cell (col, row) → one integer key. The offset keeps negative cells (objects
-      # off-screen / mid-wrap) non-negative; the stride keeps pairs unique. Both fit
-      # in a tagged Fixnum, so keying allocates nothing.
-      OFFSET = 1 << 20
-      STRIDE = 1 << 21
+      # off-screen / mid-wrap) non-negative; the stride keeps pairs unique. Both are
+      # sized to keep every packed key inside a tagged Fixnum, so keying allocates
+      # nothing on the query path (CLAUDE.md: never allocate on the per-frame path).
+      #
+      # The ceiling that sizes them is Windows, not Linux/macOS: CRuby's immediate
+      # Fixnum range comes from a C `long`, which is 64 bits on LP64 (Linux, macOS)
+      # but stays 32 bits on Windows' LLP64 even in a 64-bit process — so a value
+      # comfortably inside Fixnum range on Linux (this packing used to run up to
+      # ~2**42) silently becomes a heap-allocated Bignum on Windows instead, one
+      # allocation per cell per query. OFFSET/STRIDE here keep the largest possible
+      # packed key (both coordinates at the far corner) under 2**28 — well inside
+      # Windows' ~2**30 Fixnum ceiling — while still allowing cell coordinates out
+      # to +/-8192, i.e. a world some sixteen million pixels wide at this file's own
+      # cell_size: 64 example. A game whose world exceeds that wraps into a
+      # neighbouring cell's key instead of raising; see #each_cell below.
+      OFFSET = 1 << 13
+      STRIDE = 1 << 14
 
       def initialize(cell_size:)
         @cell_size = cell_size

data/lib/rgame/engine/tile_map_layer.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    # One layer of the scene's tile map, drawn in world space, once per viewport.
+    #
+    #   world  = scene.add_node(WorldView.new)
+    #   actors = TileMapLayer.mount(world)
+    #   actors.add_node(player)
+    #
+    # A node per layer, and the layers Tiled lists are the layers you get. The
+    # scene tree is then what says what covers what: everything mounted before
+    # the actors draws under them, everything after draws over them, and the
+    # gap `mount` leaves is where the actors go.
+    #
+    # It belongs **inside a WorldView**, which is the whole point of it existing
+    # separately from Components::TileWorld. The map is world content: it
+    # scrolls under a camera and every player sees their own part of it, so it
+    # has to be drawn where the rest of the world is drawn rather than once for
+    # the frame.
+    #
+    # It carries no state. The map id and the animation clock come from the
+    # scene's TileWorld system, and the region worth drawing comes from the view.
+    #
+    # ## Why a node per layer, rather than two passes
+    #
+    # There used to be one of these, drawing a "below" band and an "above" band
+    # in one go and relying on a global z to slot the actors between them. Draw
+    # order is tree order now (see RGame::Util::Z), so a node's drawing is
+    # contiguous and "between them" has to mean "between two nodes".
+    #
+    # That turned out to be the better shape anyway. A designer already orders
+    # layers in Tiled and can see the result there; content can go between *any*
+    # two of them rather than at one flagged boundary; and the `above` property
+    # stops being something to remember on every layer — it is read once, by
+    # `mount`, to decide where the gap goes.
+    class TileMapLayer < Node2D
+      # Mounts one node per layer of the scene's map under `parent`, and returns
+      # an empty node sitting in the gap between them — what the scene hangs its
+      # actors on. Nothing here picks a z by hand, and neither does the caller.
+      #
+      # `under` names the first layer that should cover the actors, as a layer
+      # index. It defaults to the first layer the map flags `above` in Tiled, so
+      # a map that already marks its canopies needs nothing said; a map that
+      # marks none puts the actors on top of everything.
+      #
+      # `parent` must be inside a WorldView, like the nodes themselves.
+      def self.mount(parent, under: nil)
+        world = parent.system(Components::TileWorld)
+        gap = under || world.first_above_layer
+
+        world.layer_count.times do |index|
+          # A layer at or past the gap sits above the actors; z is only ever
+          # compared to a sibling's, so the +1 is a gap, not a magnitude.
+          parent.add_node(new(layer: index, z: index < gap ? index : index + 1))
+        end
+        parent.add_node(Node2D.new(z: gap))
+      end
+
+      def initialize(layer:, **)
+        super(**)
+        @layer = layer
+      end
+
+      def on_add = @world = system(Components::TileWorld)
+
+      # The view supplies the cull rect: which part of the world this viewport
+      # can see. The map draws in world coordinates and the WorldView's
+      # translate puts it on screen, so nothing here does camera arithmetic —
+      # which is exactly what lets the same map serve every viewport.
+      #
+      # A screen-space view has no camera and nothing to cull against, so
+      # there is nothing sensible to draw; that is a misplaced layer rather than
+      # a state to handle, and it says so.
+      def on_draw(renderer, view)
+        camera = view.camera
+        raise 'TileMapLayer must be inside a WorldView — this view has no camera' if camera.nil?
+
+        renderer.tilemap(@world.tilemap_id, @layer, camera.x, camera.y,
+                         view.width, view.height, elapsed: @world.elapsed)
+      end
+    end
+  end
+end

data/lib/rgame/engine/ui/menu.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    module UI
+      # A vertical list of things to choose from, navigated by keyboard or
+      # controller.
+      #
+      #   menu = layer.add_node(UI::Menu.new(item_width: 220, item_height: 44))
+      #   menu.add_item('Resume').on_activated { close }
+      #   menu.add_item('Quit').on_activated   { game.close }
+      #
+      # ## Focus is the whole design
+      #
+      # With no pointer there is no hover, so something has to own *which
+      # control is focused* and how the directions move it. That is this class,
+      # and everything else about a menu follows from it: an item draws
+      # differently because it is focused, and `ui_confirm` activates the focused
+      # one.
+      #
+      # ## Focus is per player, and that costs nothing
+      #
+      # A Menu inside a PlayerLayer inherits that player as its `input_owner`,
+      # so the `actions` its `on_control` receives are already that player's.
+      # Two players with a menu open at once are independent without either menu
+      # knowing the other exists, and without a word of focus-specific
+      # per-player machinery. That falls out of ownership being inherited down
+      # the tree — see docs/api/scene_graph.md, "Who a node answers to".
+      #
+      # ## What this is not
+      #
+      # It is a menu, not a widget library. Items are stacked vertically at a
+      # fixed size, and that is the whole of its layout. The package this
+      # replaces positioned everything absolutely and hit-tested a mouse; none
+      # of it is a reference, and how UI should be laid out in general is still
+      # an open question — see docs/api/ui.md, "What this is not".
+      class Menu < Node2D
+        # Navigation wraps: a short vertical list is quicker to use when the
+        # ends join, and every console menu does it.
+        def initialize(item_width:, item_height:, spacing: 8,
+                       style: MenuItem::STYLE, **)
+          super(**)
+          @item_width = item_width
+          @item_height = item_height
+          @spacing = spacing
+          @style = style
+          @items = []
+          @focused_index = 0
+        end
+
+        attr_reader :items, :focused_index
+
+        # Adds an item below the last one and returns it, so a caller can
+        # connect to its signal in the same line.
+        def add_item(label, enabled: true)
+          item = MenuItem.new(label: label, enabled: enabled, style: @style,
+                              x: 0, y: @items.size * (@item_height + @spacing),
+                              width: @item_width, height: @item_height)
+          @items << item
+          add_node(item)
+          refocus
+          item
+        end
+
+        def focused = @items[@focused_index]
+
+        # Moves focus by `delta`, skipping anything disabled, and wrapping. Does
+        # nothing at all if no item can take focus.
+        def focus_by(delta)
+          return if @items.empty?
+
+          index = @focused_index
+          @items.size.times do
+            index = (index + delta) % @items.size
+            next unless @items[index].enabled?
+
+            focus(index)
+            return
+          end
+        end
+
+        def focus(index)
+          @focused_index = index
+          @items.each_with_index { |item, i| item.focused = (i == index) }
+        end
+
+        def on_control(actions)
+          focus_by(-1) if actions.pressed?(:ui_up)
+          focus_by(1) if actions.pressed?(:ui_down)
+
+          current = focused
+          return if current.nil?
+
+          current.pressed = actions.held?(:ui_confirm)
+          current.activate if actions.pressed?(:ui_confirm)
+        end
+
+        private
+
+        # Keeps focus on something usable as items arrive: the first item to be
+        # added takes it, and a disabled first item hands it on.
+        def refocus
+          return if focused&.enabled?
+
+          @items.each_with_index do |item, index|
+            next unless item.enabled?
+
+            return focus(index)
+          end
+          focus(0)
+        end
+      end
+    end
+  end
+end

data/lib/rgame/engine/ui/menu_item.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    module UI
+      # One entry in a Menu: a label on a nine-slice, and a signal for when it is
+      # chosen.
+      #
+      #   resume = menu.add_item('Resume')
+      #   resume.on_activated { cutscene.close }
+      #
+      # It draws itself from its **state** — focused, pressed, disabled or
+      # idle — which is why the shipped atlas has an element for each. There is
+      # no hover, because there is no pointer: what a mouse-driven control would
+      # get from the cursor being over it, this gets from the Menu telling it it
+      # is the focused one.
+      #
+      # Its position is its own, resolved through the tree like any node's, so a
+      # Menu inside a PlayerLayer puts its items inside that player's region
+      # without either of them arranging it.
+      class MenuItem < Node2D
+        signal :on_activated # emits no payload; the item is the handle
+
+        # Atlas element per state. Replaceable per menu, so a game with its own
+        # art is not obliged to name it the way the shipped atlas does.
+        STYLE = {
+          idle: :button_idle,
+          focus: :button_focus,
+          pressed: :button_pressed,
+          disabled: :button_disabled
+        }.freeze
+
+        LABEL_COLOR = [46, 34, 24].freeze
+        DISABLED_LABEL_COLOR = [120, 110, 100].freeze
+
+        attr_accessor :label, :enabled
+        attr_writer :focused, :pressed
+
+        def initialize(label:, style: STYLE, enabled: true, **)
+          super(**)
+          @label = label
+          @style = style
+          @enabled = enabled
+          @focused = false
+          @pressed = false
+        end
+
+        def enabled? = @enabled
+        def focused? = @focused
+
+        # Fires the signal and returns the item, or nil if it is disabled — so a
+        # caller never has to check first, and a disabled item cannot be
+        # activated by any route.
+        def activate
+          return nil unless @enabled
+
+          on_activated_signal.emit
+          self
+        end
+
+        # The panel and its label share this node's slot, so the only ordering
+        # question is which of the two goes on top — and `z: 1` says exactly
+        # that, about this item and nothing else in the frame.
+        def on_draw(renderer, _view)
+          renderer.nine_slice(@style.fetch(state), abs_x, abs_y, width, height)
+          renderer.text(@label, label_x(renderer), label_y(renderer),
+                        z: 1, color: @enabled ? LABEL_COLOR : DISABLED_LABEL_COLOR)
+        end
+
+        private
+
+        def state
+          return :disabled unless @enabled
+          return :idle unless @focused
+
+          @pressed ? :pressed : :focus
+        end
+
+        def label_x(renderer) = abs_x + ((width - renderer.text_width(@label)) / 2)
+        def label_y(renderer) = abs_y + ((height - renderer.text_height) / 2)
+      end
+    end
+  end
+end

data/lib/rgame/engine/view.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    # One viewport being drawn: a rectangle of the screen, and (for a world
+    # view) the camera to look through it with.
+    #
+    #   view.x, view.y, view.width, view.height   # the screen rect
+    #   view.camera                               # nil in screen space
+    #   view.player                               # whose view this is, or nil
+    #   view.visible?(x, y, w, h)                 # is this worth drawing
+    #
+    # ## What a view is for
+    #
+    # `draw(renderer, view)` hands every node the view it is being drawn into,
+    # which answers two questions nothing else can. **Where the edges are**: a
+    # HUD laying itself out against the whole window is wrong the moment the
+    # window is a player's half of one, and until this existed there was nothing
+    # else to ask. And **what is worth drawing**: with the world drawn once per
+    # player, culling stops being an optimisation and starts being the
+    # difference between one frame's work and four.
+    #
+    # ## It is reused, not rebuilt
+    #
+    # Viewports owns one of these per viewport and mutates it in place each
+    # frame, the way ActionMapper reuses its Actions. Building fresh ones would
+    # allocate a handful of objects every frame — invisible by every measure
+    # except the frame that stutters. **Hold the player or the viewports, never
+    # this**: the object a node was handed last frame is the same one, with
+    # different numbers in it.
+    class View
+      attr_reader :x, :y, :width, :height, :camera, :player
+
+      def initialize(x: 0, y: 0, width: 0, height: 0, camera: nil, player: nil)
+        set(x, y, width, height, camera: camera, player: player)
+      end
+
+      # Mutated in place by Viewports once per frame. Not for game code.
+      def set(x, y, width, height, camera: nil, player: nil)
+        @x = x
+        @y = y
+        @width = width
+        @height = height
+        @camera = camera
+        @player = player
+        self
+      end
+
+      # Where this view's contents start, in the space its nodes draw in: the
+      # camera's offset for a world view, and the origin for a screen-space one,
+      # whose nodes draw relative to the view's own corner.
+      # hot-path
+      def origin_x = @camera ? @camera.x : 0
+      # hot-path
+      def origin_y = @camera ? @camera.y : 0
+
+      # Does a rectangle overlap what this view shows? Coordinates are in the
+      # space the caller draws in — world coordinates under a camera, view-local
+      # ones in screen space — which is the same space `origin_x` is in.
+      # hot-path
+      def visible?(x, y, width, height)
+        left = origin_x
+        top = origin_y
+        x + width > left && x < left + @width &&
+          y + height > top && y < top + @height
+      end
+
+      # The offset to translate by so that content at `origin` lands at this
+      # view's corner on screen. The whole of split-screen, in two numbers.
+      # hot-path
+      def offset_x = @x - origin_x
+      # hot-path
+      def offset_y = @y - origin_y
+    end
+  end
+end