rgame 0.1.0 → 0.2.0

data/lib/rgame/engine/viewports.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    # How the screen is divided, as a root-scoped system.
+    #
+    #   node.system(Viewports).views       # one View per active player
+    #   node.system(Viewports).screen      # the whole window, no camera
+    #   node.system(Viewports).solo!(cam)  # collapse to one view — cutscene
+    #
+    # It holds the mutable half of the question — which mode is current, who is
+    # playing, how big the window is — while Layout holds the arithmetic. That
+    # split is deliberate: the rect maths is pure and gets specced with no tree
+    # and no window, and only the state that genuinely changes lives in a
+    # component.
+    #
+    # It is a Component on the root, so any node reaches it by walking the tree
+    # rather than having it threaded through a constructor — the same shape
+    # CollisionWorld and Players use.
+    #
+    # ## Mode changes are deferred
+    #
+    # `solo!` and `split!` record a request; it is applied in `update`, which
+    # runs in the root's component phase. That matters because this is reachable
+    # from anywhere, including from a `draw` — and a `draw` now runs once per
+    # view, so a mode change made there would fire several times and tear the
+    # frame it was made in. Deferring is the same shape `queue_free` uses, and it
+    # means a change takes effect on the next tick.
+    class Viewports < Component
+      # `views` is the list drawn through this frame — one per active player
+      # while split, exactly one while solo. Reused, like the Views in it.
+      attr_reader :screen, :width, :height, :views
+
+      def initialize(players, width: 0, height: 0)
+        super()
+        @players = players
+        @width = width
+        @height = height
+        @solo_camera = nil
+        @pending = nil
+        # One View per possible player for the world, one more each for their own
+        # screen space, and one for the whole window. Built once and mutated in
+        # place. See View: these are reused, never rebuilt.
+        @pool = []
+        @screen_pool = []
+        @views = []
+        @screen = View.new
+        refresh
+      end
+
+      # The window changed size. Rects are recomputed from it on the next
+      # refresh, and every camera reclamps against its new rect — which is why
+      # a camera does not carry one.
+      def resize(width, height)
+        @width = width
+        @height = height
+        refresh
+      end
+
+      def solo? = !@solo_camera.nil?
+
+      # The screen-space region belonging to `player`: the same rectangle their
+      # world view is drawn into, with **no camera**, so its contents are laid
+      # out against their own corner rather than the window's. Their HUD and
+      # their menus live here.
+      #
+      # `nil` when they have no region to draw into, which is two cases and one
+      # answer. An **empty seat** has no viewport at all. And while the split is
+      # **collapsed**, nobody has a half of the screen to own: a cutscene is
+      # everyone looking at one thing, so per-player UI has no place to be, and
+      # a game wanting something on screen through it draws in the global
+      # overlay band instead.
+      #
+      # Returning nil rather than an empty rectangle is deliberate: one check at
+      # the one caller that needs it beats every caller relying on a zero-sized
+      # clip happening to draw nothing.
+      def screen_for(player)
+        return nil if player.nil? || @solo_camera
+
+        world = @views.find { |view| view.player.equal?(player) }
+        return nil if world.nil?
+
+        pooled_screen(@players.list.index(player))
+          .set(world.x, world.y, world.width, world.height, player: player)
+      end
+
+      # Collapse to a single screen-wide view through `camera`.
+      #
+      # The camera is **required**: promoting one player's would silently give
+      # everyone else their view, and deciding what is on screen is what a
+      # cutscene is for. A game points an ordinary Camera wherever it likes —
+      # with a CameraFollow on a cutscene actor, or its own component framing
+      # every player at once — and hands it here.
+      def solo!(camera)
+        raise ArgumentError, 'solo! needs a camera to look through' if camera.nil?
+
+        @pending = camera
+        self
+      end
+
+      # Back to one view per player.
+      def split! = @pending = :split
+
+      # Applies a pending mode change, then rebuilds the rects. Runs in the
+      # root's component phase, so a change requested during a tick lands on the
+      # next one.
+      def update(_dt)
+        apply_pending
+        refresh
+      end
+
+      # Recompute every rect from the current mode and window, and reclamp each
+      # camera against the rect it is about to be drawn into.
+      #
+      # Allocation-free once the pool has grown: Layout yields its rects rather
+      # than building them, and the Views are mutated in place.
+      def refresh
+        @screen.set(0, 0, @width, @height)
+        @solo_camera ? refresh_solo : refresh_split
+        @views.each { |view| view.camera&.resolve(view.width, view.height) }
+        self
+      end
+
+      private
+
+      def apply_pending
+        return if @pending.nil?
+
+        @solo_camera = @pending == :split ? nil : @pending
+        @pending = nil
+      end
+
+      def refresh_solo
+        @views.clear
+        @views << pooled(0).set(0, 0, @width, @height, camera: @solo_camera)
+      end
+
+      def refresh_split
+        @views.clear
+        count = @players.active_count
+        return if count.zero?
+
+        index = 0
+        Layout.each_rect(count, @width, @height) do |i, x, y, w, h|
+          player = active_at(i)
+          @views << pooled(index).set(x, y, w, h, camera: player.camera, player: player)
+          index += 1
+        end
+      end
+
+      # `each_active` is a filter, so it cannot be indexed without building an
+      # Array. Walking it costs nothing and this runs once per frame.
+      def active_at(index)
+        found = nil
+        i = 0
+        @players.each do |player|
+          next unless player.active?
+
+          found = player if i == index
+          i += 1
+        end
+        found
+      end
+
+      def pooled(index)
+        @pool[index] ||= View.new
+      end
+
+      def pooled_screen(index)
+        @screen_pool[index] ||= View.new
+      end
+    end
+  end
+end

data/lib/rgame/engine/world_view.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    # The node that marks where world space begins.
+    #
+    #   view = scene.add_node(WorldView.new)
+    #   view.add_node(player)     # draws at its own world coordinates
+    #
+    # Its children live in **world** coordinates and are drawn once per active
+    # viewport: for each one, clip to that viewport's rectangle and translate by
+    # its camera, then run the same subtree again. Everything outside a
+    # WorldView is screen space and draws once.
+    #
+    # That is the whole of split-screen, and it is why the transform and clip
+    # stacks in Core are proper push/pop stacks — a clip always narrows, so a
+    # child can never draw outside the region its parent allowed.
+    #
+    # ## The subtree does not know how many times it is drawn
+    #
+    # Children draw at their own absolute origin and never see a camera. This
+    # node supplies the view, so the same world serves one player or four with
+    # nothing below it changing — which is exactly what a camera owned by a node
+    # *inside* the world could not do, and why cameras belong to players.
+    #
+    # ## Only `draw` multiplies, and deliberately
+    #
+    # `control` and `update` still run **once** for this subtree, however many
+    # viewports draw it. That is what keeps simulation cost independent of player
+    # count, and it is also a safety property: a world node's `on_update` is
+    # where mutation belongs, so per-view updating would move an actor at twice
+    # the speed with two players — correctly in single player, silently wrong the
+    # moment somebody joins.
+    #
+    # It does make the standing "draw renders state" rule load-bearing rather
+    # than stylistic: a `draw` with a side effect now happens once per player,
+    # and an allocation in one costs that many times.
+    #
+    # A node that genuinely needs per-view work at draw time can read
+    # `system(Viewports).views` itself. Anything needing per-view state *over
+    # time* — a screen shake, a hit flash — is per-*player* rather than per-view,
+    # and belongs on that player's camera or their own subtree, which tick once.
+    class WorldView < Node2D
+      # World content, which is the default anyway — stated because this is the
+      # node that marks where world space begins, and a reader looking for
+      # "which band is the world in" should find the answer here.
+      def initialize(**)
+        super(band: :world, **)
+      end
+
+      # Drawn once per viewport, so this overrides the whole of `draw` rather
+      # than just `draw_children`: the node's own visuals belong inside the
+      # viewport too, not once outside all of them.
+      #
+      # `view` is the screen-space view this node was reached with, and is
+      # deliberately ignored — a WorldView asks the system which viewports exist
+      # rather than being told, so a game can place one anywhere in the tree.
+      def draw(renderer, _view = nil)
+        viewports = system(Viewports)
+        viewports.views.each do |world_view|
+          renderer.clipped(world_view.x, world_view.y, world_view.width, world_view.height) do
+            renderer.translated(world_view.offset_x, world_view.offset_y) do
+              super(renderer, world_view)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rgame/engine.rb

@@ -19,6 +19,7 @@
 # three-layer rule allows and this file therefore has to declare.
 require_relative 'util'
 
+require_relative 'engine/culling'
 require_relative 'engine/matrix'
 require_relative 'engine/signal'
 require_relative 'engine/node2d'
@@ -26,7 +27,12 @@ require_relative 'engine/component'
 require_relative 'engine/animation_set'
 require_relative 'engine/animator'
 require_relative 'engine/camera'
-require_relative 'engine/camera_view'
+require_relative 'engine/layout'
+require_relative 'engine/view'
+require_relative 'engine/world_view'
+require_relative 'engine/player_layer'
+require_relative 'engine/ui/menu_item'
+require_relative 'engine/ui/menu'
 require_relative 'engine/path'
 require_relative 'engine/timer'
 require_relative 'engine/tileset'
@@ -46,8 +52,12 @@ require_relative 'engine/debug_overlay'
 require_relative 'engine/body'
 require_relative 'engine/actor'
 require_relative 'engine/input/actions'
+require_relative 'engine/input/input_map'
 require_relative 'engine/input/action_mapper'
 require_relative 'engine/input/player_controller'
+require_relative 'engine/player'
+require_relative 'engine/players'
+require_relative 'engine/viewports'
 require_relative 'engine/scene/scene_stack'
 require_relative 'engine/components/velocity'
 require_relative 'engine/components/pool'
@@ -66,3 +76,5 @@ require_relative 'engine/components/character_body'
 require_relative 'engine/components/player_controller'
 require_relative 'engine/components/wander_controller'
 require_relative 'engine/components/animated_sprite'
+require_relative 'engine/components/camera_follow'
+require_relative 'engine/tile_map_layer'

data/lib/rgame/game.rb

@@ -43,22 +43,61 @@ module RGame
     WIDTH = 640
     HEIGHT = 480
 
-    attr_reader :root, :renderer, :action_mapper
+    attr_reader :root, :renderer
 
+    # `input_map:` is what physical inputs mean — one entry per action, naming
+    # ids from RGame::Util::Controls. It is merged over the universal UI set, so
+    # `ui_confirm` and friends work whether or not a game declares them, and it
+    # defaults to RGame::Engine::InputMap::DEFAULT_ACTIONS, so a game wanting
+    # eight-way movement and a fire button declares nothing.
+    #
+    # `device:` is which device drives it — the keyboard, or
+    # `Controls.gamepad(slot)` for a controller.
+    #
+    # `input:` overrides the input backend. It exists so a harness can drive a
+    # game from a script instead of from hardware — see tools/drive_example.rb,
+    # and CLAUDE.md's "The examples are the acceptance test for wiring", which
+    # is why driving one has to be possible at all. A game passes nothing and
+    # gets the real thing.
+    # `players:` is how many seats the game has, and therefore the most people
+    # who can play it. Player 0 starts on `device:`; the rest start empty and
+    # are filled when someone uses a controller — see RGame::Engine::Players for
+    # why that is a press rather than a plug.
     def initialize(root:, width: WIDTH, height: HEIGHT, caption: 'RGame',
-                   media_root: 'media', action_map: {})
+                   media_root: 'media', input_map: nil, device: Controls::KEYBOARD,
+                   players: 1, input: nil)
       super(width: width, height: height, caption: caption, media_root: media_root)
 
       @root = root
       @renderer = RGame::Core::Renderer.new(self)
-      @input = RGame::Core::Input.new(self)
-      @action_mapper = RGame::Engine::ActionMapper.new(action_map)
-      @overlay = RGame::Engine::DebugOverlay.new # always wired up; F1 reveals it
+      @input = input || RGame::Core::Input.new(self)
+      @players = RGame::Engine::Players.new(
+        Array.new(players) do |id|
+          RGame::Engine::Player.new(id: id, device: id.zero? ? device : nil,
+                                    input_map: input_map)
+        end
+      )
+      @viewports = RGame::Engine::Viewports.new(@players, width: width, height: height)
+      @debug = RGame::Engine::DebugOverlay.new # always wired up; F1 reveals it
       @dirty = true # draw the first frame
 
       install_asset_loaders
     end
 
+    # The player registry, also reachable from any node as
+    # `node.system(RGame::Engine::Players)` — which is how a scene gets at a
+    # camera to follow, without anything being threaded into its constructor.
+    #
+    # One player exists from the start, so a single-player game never mentions
+    # players at all: it is `players.primary` that an unowned node reads from,
+    # and `players.primary.camera` that a scene points at its hero.
+    attr_reader :players
+
+    # How the screen is divided. Reachable as `node.system(RGame::Engine::Viewports)`,
+    # which is how a cutscene deep in a scene collapses the split without
+    # anything being handed to it.
+    attr_reader :viewports
+
     # Brings the tree live and runs until the window closes.
     #
     # The root gets this object as its `context`, which is how a node deep in
@@ -66,6 +105,10 @@ module RGame
     # anything being threaded through its constructor.
     def start
       @root.context = self
+      # Root-scoped systems, mounted before the tree comes alive so that an
+      # on_add anywhere in it can already resolve node.system(...) for either.
+      @root.add_component(@players)
+      @root.add_component(@viewports)
       @root.enter_tree # components attach, then on_add
       run
     end
@@ -86,7 +129,10 @@ module RGame
     # read identical state, and the edge lands on the first of them — one press,
     # one `pressed?`, which is what a caller means.
     def update(dt)
-      @root.control(@action_mapper.poll(@input))
+      @players.poll(@input)
+      # The registry, not one player's snapshot: each node resolves the actions
+      # of whoever owns it, and a node that claims nobody gets the primary.
+      @root.control(@players)
       @root.update(dt)
       @root.sweep_freed # flush queue_free'd nodes outside the update traversal
       @dirty = true
@@ -94,17 +140,41 @@ module RGame
 
     # Only the simulation advancing makes the frame stale. While the overlay is
     # up, redraw anyway, so its numbers stay live even when nothing is moving.
-    def needs_redraw? = @dirty || @overlay.visible?
+    def needs_redraw? = @dirty || @debug.visible?
 
+    # The tree is drawn once, with the whole window as its view. Screen-space
+    # content — a HUD, a menu, a title card — lands there and is drawn exactly
+    # once, as it always was.
+    #
+    # **World content multiplies inside the tree, not here.** An
+    # RGame::Engine::WorldView draws its subtree once per viewport, clipping and
+    # translating for each, so where the world begins is the game's choice
+    # rather than a shape the platform imposes. That is also what keeps
+    # `node.root` meaning the game's own root: nothing is inserted above it.
     def draw
-      @root.draw(@renderer)
-      @overlay.draw(@renderer, width, height, fps) # last, so it layers on top
+      @viewports.refresh # rects from the layout, then reclamp every camera
+      @root.draw(@renderer, @viewports.screen)
+      @debug.draw(@renderer, @viewports.screen, fps) # last, so it layers on top
       @dirty = false
     end
 
+    # The window changed size, so every rect and every camera clamp does too.
+    def resize(width, height) = @viewports.resize(width, height)
+
+    # Hot-plug is bookkeeping, not seating: a controller arriving becomes a
+    # device the registry watches, and it is someone *using* it that gives it to
+    # a player. Leaving takes it back off whoever had it.
+    def gamepad_connected(slot) = @players.device_connected(slot)
+    def gamepad_disconnected(slot) = @players.device_disconnected(slot)
+
+    # The two development keys, both function keys on purpose: **Escape is
+    # deliberately not bound here**, because it is the natural `cancel`/`back`
+    # button for a game's own menus, and a debug shortcut has no business taking
+    # the one key every player expects to close a dialog. F1 shows the overlay,
+    # F2 quits.
     def button_down(id)
-      close if id == Controls::KEY_ESCAPE
-      @overlay.toggle if id == Controls::KEY_F1
+      close if id == Controls::KEY_F2
+      @debug.toggle if id == Controls::KEY_F1
     end
 
     private

data/lib/rgame/util/controls.rb

@@ -10,8 +10,14 @@ module RGame
     # layer and a game's own configuration name a physical input without
     # touching RGame::Core, which they may not do:
     #
-    #   bindings = Controls::DEFAULT_KEYBOARD.merge(fire: Controls::KEY_J)
-    #   RGame::Core::Input.new(app, bindings: bindings)
+    #   controls = RGame::Util::Controls
+    #   map = RGame::Engine::InputMap.default.merge(
+    #     fire: { buttons: [controls::KEY_SPACE, controls::PAD_A] }
+    #   )
+    #
+    # This module is the **vocabulary** only. What an id *means* to a game — the
+    # binding table — is RGame::Engine::InputMap, one per player, because two
+    # players share a game's actions but not the buttons that trigger them.
     #
     # The same numbers exist as `#define`s in
     # ext/rgame_core/include/rgame/core.h, because the C engine and the
@@ -20,17 +26,118 @@ module RGame
     # by _Static_assert at compile time, and spec/rgame/util/controls_spec.rb
     # parses that header and compares every value here against it.
     module Controls
-      # --- Keyboard. Values are SDL scancodes. ---
+      # --- Keyboard. Values are SDL scancodes, which name a physical *position*
+      # rather than a letter: KEY_A is the key marked A on a QWERTY board and Q
+      # on AZERTY. A game rebinding controls shows the player what their layout
+      # calls it; the engine only ever compares numbers. ---
+      #
+      # The set is what a Western keyboard can be relied on to have. No numpad
+      # (most laptops have none), no GUI/Windows/Command key, no print-screen
+      # cluster, and nothing whose position depends on the layout.
+
+      # Letters. Scancodes are physical *positions*, so KEY_A is the key marked A on
+      # a QWERTY board and Q on AZERTY.
+      KEY_A = 4
+      KEY_B = 5
+      KEY_C = 6
+      KEY_D = 7
+      KEY_E = 8
+      KEY_F = 9
+      KEY_G = 10
+      KEY_H = 11
+      KEY_I = 12
+      KEY_J = 13
+      KEY_K = 14
+      KEY_L = 15
+      KEY_M = 16
+      KEY_N = 17
+      KEY_O = 18
+      KEY_P = 19
+      KEY_Q = 20
+      KEY_R = 21
+      KEY_S = 22
+      KEY_T = 23
+      KEY_U = 24
+      KEY_V = 25
+      KEY_W = 26
+      KEY_X = 27
+      KEY_Y = 28
+      KEY_Z = 29
+
+      # Digits along the top row.
+      KEY_1 = 30
+      KEY_2 = 31
+      KEY_3 = 32
+      KEY_4 = 33
+      KEY_5 = 34
+      KEY_6 = 35
+      KEY_7 = 36
+      KEY_8 = 37
+      KEY_9 = 38
+      KEY_0 = 39
+
+      # Editing and whitespace.
       KEY_RETURN = 40
       KEY_ESCAPE = 41
+      KEY_BACKSPACE = 42
+      KEY_TAB = 43
       KEY_SPACE = 44
+
+      # Punctuation, by position on a US board.
+      KEY_MINUS = 45
+      KEY_EQUALS = 46
+      KEY_LEFTBRACKET = 47
+      KEY_RIGHTBRACKET = 48
+      KEY_BACKSLASH = 49
+      KEY_SEMICOLON = 51
+      KEY_APOSTROPHE = 52
+      KEY_GRAVE = 53
+      KEY_COMMA = 54
+      KEY_PERIOD = 55
+      KEY_SLASH = 56
+
+      # Function row and caps lock.
+      KEY_CAPSLOCK = 57
       KEY_F1 = 58
+      KEY_F2 = 59
+      KEY_F3 = 60
+      KEY_F4 = 61
+      KEY_F5 = 62
+      KEY_F6 = 63
+      KEY_F7 = 64
+      KEY_F8 = 65
+      KEY_F9 = 66
+      KEY_F10 = 67
+      KEY_F11 = 68
+      KEY_F12 = 69
+
+      # The navigation cluster.
+      KEY_INSERT = 73
+      KEY_HOME = 74
+      KEY_PAGEUP = 75
+      KEY_DELETE = 76
+      KEY_END = 77
+      KEY_PAGEDOWN = 78
+
+      # Arrows.
       KEY_RIGHT = 79
       KEY_LEFT = 80
       KEY_DOWN = 81
       KEY_UP = 82
 
-      # --- Gamepad buttons. The gamepad range plus SDL's controller button. ---
+      # Modifiers. No GUI key: that is Windows on a PC and Command on a Mac, which
+      # is exactly the platform-specific territory this list stays out of.
+      KEY_LCTRL = 224
+      KEY_LSHIFT = 225
+      KEY_LALT = 226
+      KEY_RCTRL = 228
+      KEY_RSHIFT = 229
+      KEY_RALT = 230
+
+      # --- Gamepad buttons. The gamepad range plus SDL's own controller button
+      # number. The first fifteen are on every controller; MISC1, the paddles
+      # and TOUCHPAD are hardware the id space describes but most pads do not
+      # have, and read as never pressed on one that does not. ---
       PAD_A = 4096
       PAD_B = 4097
       PAD_X = 4098
@@ -46,6 +153,12 @@ module RGame
       PAD_DPAD_DOWN = 4108
       PAD_DPAD_LEFT = 4109
       PAD_DPAD_RIGHT = 4110
+      PAD_MISC1 = 4111
+      PAD_PADDLE1 = 4112
+      PAD_PADDLE2 = 4113
+      PAD_PADDLE3 = 4114
+      PAD_PADDLE4 = 4115
+      PAD_TOUCHPAD = 4116
 
       # --- Analog axes. Their own small space: they are float-valued and read
       # through a different call, so folding them into the button space would
@@ -65,43 +178,6 @@ module RGame
 
       # The device id for a player slot: gamepad(0) is the first controller.
       def self.gamepad(slot) = GAMEPAD_FIRST + slot
-
-      # --- Default bindings ---
-      #
-      # Symbolic action => physical input. Games override these to rebind; they
-      # are values, so a config screen can build its own table from the
-      # constants above and hand it to the input layer.
-      #
-      # Two button tables rather than one, because the same action is a
-      # different physical input per device class: :fire is the space bar on a
-      # keyboard and the A button on a pad.
-      DEFAULT_KEYBOARD = {
-        left: KEY_LEFT,
-        right: KEY_RIGHT,
-        up: KEY_UP,
-        down: KEY_DOWN,
-        confirm: KEY_RETURN,
-        fire: KEY_SPACE
-      }.freeze
-
-      DEFAULT_PAD = {
-        left: PAD_DPAD_LEFT,
-        right: PAD_DPAD_RIGHT,
-        up: PAD_DPAD_UP,
-        down: PAD_DPAD_DOWN,
-        confirm: PAD_A,
-        fire: PAD_A
-      }.freeze
-
-      # Analog axes exist only on pads, so there is one table.
-      DEFAULT_AXES = {
-        move_x: AXIS_LEFT_X,
-        move_y: AXIS_LEFT_Y,
-        aim_x: AXIS_RIGHT_X,
-        aim_y: AXIS_RIGHT_Y,
-        trigger_left: AXIS_TRIGGER_LEFT,
-        trigger_right: AXIS_TRIGGER_RIGHT
-      }.freeze
     end
   end
 end