rgame 0.4.0-x86_64-linux-gnu

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

data/lib/rgame/engine/players.rb

@@ -0,0 +1,205 @@
+# 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
+        @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.
+      #
+      # @api private
+      # 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.
+      #
+      # @api private
+      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.
+      #
+      # @api private
+      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
+
+      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
+
+      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
+
+      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/pool.rb

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

data/lib/rgame/engine/presentation.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    # How a game's own resolution is presented on a window that may be a
+    # different size. Pure arithmetic: a size, a mode, and the scale and offset
+    # they imply. No renderer, no window, nothing to draw with.
+    #
+    #   presentation = Presentation.new(width: 640, height: 480, mode: :integer)
+    #   presentation.fit(1920, 1080)
+    #   presentation.scale_x   # => 2.0
+    #   presentation.offset_x  # => 320   (1920 - 640*2, halved)
+    #
+    # ## The problem it exists for
+    #
+    # A game laid out against fixed numbers — a 500x500 board centred by writing
+    # `x: 150` in a 800x600 window — keeps those numbers when the window grows.
+    # It does not re-centre; it sits in the top-left corner with the new space
+    # piled up to its right. Fullscreen makes that happen to every game that has
+    # not thought about it, because fullscreen is the screen's resolution and
+    # never the one the game asked for.
+    #
+    # There are two honest answers, and this is the second one:
+    #
+    # - **Re-layout.** Read the size you are drawing into and place things
+    #   relative to its edges. Right for a HUD or a menu, where extra space is
+    #   extra room. `examples/fullscreen` does this.
+    # - **Scale.** Keep the design size, and map it onto whatever the window is.
+    #   Right for a play area, where extra space should mean a bigger picture of
+    #   the same thing rather than more world. This class.
+    #
+    # A game usually wants both at once, which works: the scale applies to
+    # everything, and nodes still read their view's size — that size is just the
+    # *logical* one now, so it stops changing.
+    #
+    # ## The modes
+    #
+    # | | |
+    # |---|---|
+    # | `:disabled` | No scaling. The logical size *is* the window size, so it changes as the window does. |
+    # | `:stretch` | Fill the window exactly, distorting if the aspect ratios differ. |
+    # | `:letterbox` | Largest scale that fits, equal on both axes, centred. Bars on two sides. |
+    # | `:integer` | The same, rounded down to a whole number. |
+    #
+    # `:integer` is the one pixel art wants. A sprite drawn at 1.875x with nearest
+    # filtering has some source pixels covering two screen pixels and some
+    # covering one, and the unevenness crawls as anything moves. A whole-number
+    # factor makes every source pixel exactly the same square, which is what
+    # "pixel perfect" means.
+    #
+    # **It costs screen, sometimes a lot of it.** The factor is bounded by the
+    # tighter axis, and rounding that down can throw away most of a window. A
+    # 640x480 design measured against real screens:
+    #
+    # | window | `:integer` | `:letterbox` |
+    # |---|---|---|
+    # | 1920x1080 | 2x, 320px border | 2.25x |
+    # | 2560x1440 | 3x, 320px border | 3x |
+    # | 1600x900 | **1x**, 480px border | 1.875x |
+    # | 1280x720 | **1x**, 320px border | 1.5x |
+    #
+    # The 16:9 rows are the ones to look at before choosing this mode: 900 and
+    # 720 pixels of height are both short of the 960 that 2x needs, so the whole
+    # window drops to 1x and the game sits in a small island. A design height
+    # that divides common screen heights — 360 rather than 480 — is what avoids
+    # that, and it is a decision about the game's art, not about this class.
+    #
+    # ## What `:integer` does when the window is too small
+    #
+    # It scales by 1 and lets the content overrun, rather than dropping below a
+    # whole number. So the design size is a **minimum**: shrink the window under
+    # it and you see part of the game rather than all of it, smaller.
+    #
+    # That is the same choice SDL makes, and the alternative is worse for the
+    # case the mode exists for — falling back to a fractional scale would
+    # reintroduce exactly the uneven pixels the game asked to avoid, at the
+    # moment nobody is looking. Nothing here enforces a minimum window size;
+    # that would need SDL, and this class is pure.
+    class Presentation
+      MODES = %i[disabled stretch letterbox integer].freeze
+
+      # The logical size a game draws in. Under `:disabled` these follow the
+      # window; under every other mode they are fixed and the window does not
+      # matter to anything above this class.
+      attr_reader :width, :height
+
+      attr_reader :mode, :scale_x, :scale_y, :offset_x, :offset_y
+
+      def initialize(width:, height:, mode: :disabled)
+        raise ArgumentError, "unknown scale mode #{mode.inspect} — one of #{MODES.inspect}" \
+          unless MODES.include?(mode)
+        raise ArgumentError, 'a logical size needs a positive width and height' \
+          unless width.positive? && height.positive?
+
+        @logical_width = width
+        @logical_height = height
+        @mode = mode
+        fit(width, height)
+      end
+
+      # Switches mode and refits against the window it last saw, so a settings
+      # screen can change this while the game runs.
+      #
+      # The window size is remembered for exactly this: a caller changing the
+      # mode knows which mode it wants and has no reason to also know how big
+      # the window currently is, and asking it to pass one would be asking it to
+      # keep a copy of something this object already has.
+      def mode=(mode)
+        raise ArgumentError, "unknown scale mode #{mode.inspect} — one of #{MODES.inspect}" \
+          unless MODES.include?(mode)
+
+        @mode = mode
+        fit(@window_width, @window_height)
+      end
+
+      # Whether anything is being scaled. `:disabled` means the caller can skip
+      # pushing a transform at all rather than pushing an identity one.
+      #
+      # @api private
+      def scaled? = @mode != :disabled
+
+      # Recomputes for a window of this size. Mutates rather than returning a
+      # new object: it is read every frame and recomputed only on a resize, so
+      # there is no reason to allocate.
+      def fit(window_width, window_height)
+        @window_width = window_width
+        @window_height = window_height
+        case @mode
+        when :disabled then fit_disabled(window_width, window_height)
+        when :stretch then fit_stretch(window_width, window_height)
+        else fit_uniform(window_width, window_height)
+        end
+        self
+      end
+
+      private
+
+      def fit_disabled(window_width, window_height)
+        @width = window_width
+        @height = window_height
+        @scale_x = @scale_y = 1.0
+        @offset_x = @offset_y = 0.0
+      end
+
+      def fit_stretch(window_width, window_height)
+        @width = @logical_width
+        @height = @logical_height
+        @scale_x = window_width.to_f / @logical_width
+        @scale_y = window_height.to_f / @logical_height
+        @offset_x = @offset_y = 0.0
+      end
+
+      def fit_uniform(window_width, window_height)
+        @width = @logical_width
+        @height = @logical_height
+
+        fitting = [window_width.to_f / @logical_width, window_height.to_f / @logical_height].min
+        scale = @mode == :integer ? integer_scale(fitting) : fitting
+
+        @scale_x = @scale_y = scale
+        @offset_x = ((window_width - (@logical_width * scale)) / 2.0).floor
+        @offset_y = ((window_height - (@logical_height * scale)) / 2.0).floor
+      end
+
+      def integer_scale(fitting)
+        floored = fitting.floor
+        floored < 1 ? 1.0 : floored.to_f
+      end
+    end
+  end
+end

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

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    module Scene
+      class SceneStack < Engine::Component
+        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
+          scene.scene = scene
+          scene.enter_tree
+          self
+        end
+
+        def pop
+          scene = @stack.pop
+          return self unless scene
+
+          scene.exit_tree
+          scene.scene = nil
+          scene.parent = nil
+          self
+        end
+
+        def replace(scene)
+          pop
+          push(scene)
+        end
+
+        def current
+          @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(@players || actions)
+        end
+
+        def update(dt)
+          return unless (current_scene = current)
+
+          current_scene.update(dt)
+        end
+
+        # 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, view)
+          end
+        end
+
+        # Scenes live in @stack, off the host's child list, so the host's #sweep_freed
+        # can't reach them — forward the sweep into the active scene's subtree.
+        def sweep_freed
+          current&.sweep_freed
+        end
+      end
+    end
+  end
+end

data/lib/rgame/engine/sealed_privates.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    # The rule for the two classes a game subclasses, Node2D and Component: a
+    # non-public method whose name starts with `_` is the engine's machinery, and
+    # a subclass defining a method of the same name raises where it is defined.
+    #
+    #   class Hop < RGame::Engine::Node2D
+    #     def _draw_content(renderer, view) = ...   # NameError: would replace Node2D#_draw_content
+    #     def draw_children(renderer, view) = ...   # fine: no underscore, meant to be overridden
+    #   end
+    #
+    # `private` in Ruby says who may *call* a method, not who may *replace* one: a
+    # subclass method of the same name is found first, and the base class quietly
+    # stops doing what that method did — for that subclass only, with the failure
+    # somewhere else entirely. So the underscore is the opt-in. A private or
+    # protected method *without* one is a seam, meant to be overridden with
+    # `super`, and nothing guards it.
+    #
+    # Only the base class's own methods are sealed. A private hook an engine
+    # subclass writes for its own subclasses — Components::Mover's `take_step` —
+    # is not covered, and the underscore convention does not apply outside these
+    # two classes.
+    #
+    # What it cannot see: a method arriving through `include` or `prepend` of a
+    # module, which does not pass through `method_added`.
+    module SealedPrivates
+      def self.extended(base)
+        base.define_singleton_method(:sealed_base) { base }
+        base.singleton_class.send(:private, :sealed_base)
+      end
+
+      # Every method a subclass may not define: the base's non-public methods
+      # whose names start with `_`.
+      def sealed_methods
+        base = sealed_base
+        (base.private_instance_methods(false) + base.protected_instance_methods(false))
+          .select { |name| name.start_with?('_') }
+      end
+
+      def method_added(name)
+        super
+        base = sealed_base
+        return if equal?(base) || !name.start_with?('_')
+        return unless base.private_method_defined?(name, false) || base.protected_method_defined?(name, false)
+
+        raise NameError.new("#{self}##{name} would replace #{base}##{name}, which #{base} calls " \
+                            "itself, and #{base} would silently stop doing its job for this class. " \
+                            'Give the method another name.', name)
+      end
+    end
+  end
+end