rgame 0.4.0-x86_64-linux-gnu

data/lib/rgame/core/tile_map_renderer.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+module RGame
+  module Core
+    # Draws a tile map: the static layers baked once, the animated tiles drawn
+    # per frame, both culled to a rectangle of the world.
+    #
+    #   tiles = RGame::Core::TileMapRenderer.new(map, tileset_images)
+    #
+    #   map.layer_count.times do |layer|
+    #     tiles.draw_layer(renderer, layer, cull_x, cull_y, cull_w, cull_h,
+    #                      elapsed: seconds)
+    #   end
+    #
+    # ## It draws in world coordinates
+    #
+    # A tile at column 3 is drawn at `3 * tile_width`, and getting it onto the
+    # screen is the caller's transform — the same deal every other drawable
+    # gets. The rectangle passed in is therefore a **cull rect** and nothing
+    # else: which part of the world is worth drawing.
+    #
+    # It used to be both, offsetting the output by `-camera` as well as culling
+    # to it, which worked exactly as long as there was one camera. Under
+    # split-screen the same map is drawn through several, so a call that bakes
+    # placement into its output can only be right for one of them. Culling is
+    # genuinely per-camera; placement is the transform stack's job.
+    #
+    # ## One call per layer, because the actors go between them
+    #
+    # A layer is drawn on its own, and the order they are drawn in is the
+    # caller's. That is what lets a scene put its actors between two of them —
+    # tree trunks below, canopies above — which is the whole reason this does
+    # not simply draw the map in one go.
+    #
+    # It is also why nothing here consults the map's `above_layer?` flag any
+    # more: which layers cover the actors is a question about where the actors
+    # are in the scene, and Tiled already answers "in what order do the layers
+    # go" by listing them. `RGame::Engine::TileMapLayer` mounts one node per
+    # layer and the tree does the rest.
+    #
+    # ## What is baked and what is not
+    #
+    # Within each layer, every tile that is *not* animated is baked into one
+    # recording, the first time that layer is drawn. Scrolling a baked layer is
+    # then one call per texture however many thousand tiles went into it. The
+    # handful that *are* animated are drawn individually each frame, culled to
+    # the viewport — a map far larger than the screen costs only what is on it.
+    #
+    # Splitting per layer rather than into two bands bakes the same tiles into
+    # more recordings, not more vertices: the partition changed, the contents
+    # did not.
+    #
+    # ## It loads nothing and holds no clock
+    #
+    # The tiles arrive already sliced, so two maps sharing a tileset share one
+    # GPU upload — which is only true if something above pulled the image
+    # through the asset manager, and is why this class does not load its own.
+    #
+    # And `elapsed` is an argument rather than a clock read, so animation is
+    # something the caller advances. Pausing is "stop accumulating"; a spec
+    # picks the frame it wants. See CLAUDE.md, "`draw` renders state; time
+    # enters through `update`".
+    #
+    # ## What it needs of a map
+    #
+    # It never names the map's class — the tile map lives a layer *above* this
+    # one and Core may not reach up (CLAUDE.md, "The rule points both ways").
+    # What it calls is the 'a tile map' contract in
+    # `spec/support/shared_examples/`: `layer_count`, `width`, `height`,
+    # `tile_width`, `tile_height`, `gid`, and a `tileset` answering `local_id`,
+    # `animations` and `frame_local_id`.
+    class TileMapRenderer
+      # The map this was built from. A scene reads it for collision and world
+      # bounds, which are its business rather than this class's.
+      attr_reader :map
+
+      # `tiles` is the tileset image sliced into an Array indexed by local tile
+      # id — what `Image#tiles` returns.
+      def initialize(map, tiles)
+        @map = map
+        @tileset = map.tileset
+        @tiles = tiles
+        @animated = collect_animated_tiles
+        @static = Array.new(map.layer_count)
+      end
+
+      def layer_count = @map.layer_count
+
+      # One layer, culled to `(cull_x, cull_y, cull_width, cull_height)` in world
+      # coordinates and drawn in them.
+      #
+      # The recording is replayed at its own origin, so it lands wherever the
+      # caller's transform puts it. That also makes it **view-independent**: one
+      # bake serves every viewport, which is what keeps split-screen affordable
+      # and is why the bake is not keyed on a camera. Baking happens on the
+      # first draw, and it is safe to do that inside a transform or a clip —
+      # recording runs on its own canvas, begun at identity, and captures
+      # neither.
+      #
+      # No `z:`. A layer is drawn by a node of its own, so where it sits is the
+      # scene tree's answer; everything this issues belongs to that one node and
+      # goes in its slot.
+      #
+      # @api private
+      def draw_layer(renderer, index, cull_x, cull_y, cull_width, cull_height, elapsed: 0.0)
+        unless index.is_a?(Integer) && index >= 0 && index < @static.size
+          raise ArgumentError, "no layer #{index.inspect} in this map (it has #{@static.size})"
+        end
+
+        @static[index] ||= bake(renderer, index)
+        @static[index].draw
+        draw_animated(renderer, @animated[index], cull_x, cull_y,
+                      cull_width, cull_height, elapsed)
+      end
+
+      private
+
+      def collect_animated_tiles
+        found = Array.new(@map.layer_count) { [] }
+        each_tile do |layer, col, row, local|
+          next unless @tileset.animations.key?(local)
+
+          found[layer] << [col, row, local]
+        end
+        found
+      end
+
+      def each_tile
+        @map.layer_count.times do |layer|
+          @map.height.times do |row|
+            @map.width.times do |col|
+              gid = @map.gid(layer, col, row)
+              next if gid.zero?
+
+              yield(layer, col, row, @tileset.local_id(gid))
+            end
+          end
+        end
+      end
+
+      def bake(renderer, index)
+        renderer.record do
+          each_tile do |layer, col, row, local|
+            next unless layer == index
+            next if @tileset.animations.key?(local)
+
+            renderer.image_at(@tiles[local], col * @map.tile_width, row * @map.tile_height)
+          end
+        end
+      end
+
+      def draw_animated(renderer, tiles, cull_x, cull_y, cull_width, cull_height, elapsed)
+        tile_width = @map.tile_width
+        tile_height = @map.tile_height
+
+        ms = (elapsed * 1000.0).to_i
+
+        col_start = cull_x.fdiv(tile_width).floor
+        row_start = cull_y.fdiv(tile_height).floor
+        col_end = (cull_x + cull_width).fdiv(tile_width).ceil
+        row_end = (cull_y + cull_height).fdiv(tile_height).ceil
+
+        tiles.each do |col, row, local|
+          next if col < col_start || col >= col_end || row < row_start || row >= row_end
+
+          renderer.image_at(@tiles[@tileset.frame_local_id(local, ms)],
+                            col * tile_width, row * tile_height)
+        end
+      end
+    end
+  end
+end

data/lib/rgame/core/ui_atlas.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require 'json'
+
+require_relative 'image'
+require_relative 'nine_slice'
+
+module RGame
+  module Core
+    # One sheet of UI chrome, cut into named nine-slices and named images.
+    #
+    #   atlas = RGame::Core::UiAtlas.load(app, 'media/ui.json')
+    #   renderer.register_ui_atlas(atlas)
+    #   renderer.nine_slice(:button_idle, x, y, width, height)
+    #   renderer.image(:home, cx, cy)
+    #
+    # A button has four states, a panel has one, a scrollbar has three pieces —
+    # all of them small, and all of them cheaper as sub-rectangles of a single
+    # texture than as a dozen separate files. This is that texture plus a
+    # descriptor naming what is where.
+    #
+    # ## The descriptor
+    #
+    #   {
+    #     "image": "buttons.png",
+    #     "scale": 3,
+    #     "nine_slices": {
+    #       "button_idle":  { "x": 11, "y": 59, "w": 26, "h": 28, "border": 7 },
+    #       "button_focus": { "x": 43, "y": 59, "w": 26, "h": 28, "border": 7 },
+    #       "panel":        { "x": 0,  "y": 0,  "w": 32, "h": 32,
+    #                         "border": { "left": 4, "right": 4, "top": 8, "bottom": 4 },
+    #                         "scale": 2 }
+    #     },
+    #     "images": {
+    #       "home": { "x": 0,  "y": 96, "w": 50, "h": 50 },
+    #       "gear": { "x": 50, "y": 96, "w": 50, "h": 50 }
+    #     }
+    #   }
+    #
+    # `image` is resolved next to the descriptor. Each nine-slice entry is a
+    # source rectangle plus a border — a uniform integer or one value per side —
+    # and an optional `scale` overriding the sheet default. See
+    # RGame::Core::NineSlice for what those mean when it is drawn.
+    #
+    # Each `images` entry is a rectangle and nothing else: an icon is drawn
+    # whole, so it has no border, and no scale either, because how large to draw
+    # it is the draw call's `scale:`. Either section may be absent or `null`.
+    #
+    # ## Element names, not filenames
+    #
+    # Both sections are keyed by whatever the descriptor calls each element, and
+    # those names are what a widget asks for. That is why nine-slices are the
+    # one asset the renderer resolves by registration only: `:button_focus` is
+    # not a file and never can be. `Renderer#register_ui_atlas` registers every
+    # element of both kinds in one call.
+    #
+    # Parsing happens once, at load. Nothing here is touched again per frame.
+    class UiAtlas
+      # The nine-slice elements, by name. Values are `NineSlice`s.
+      attr_reader :nine_slices
+
+      # The image elements, by name. Values are `Image`s cut from the sheet.
+      attr_reader :images
+
+      # Loads a descriptor and the sheet beside it.
+      #
+      # The `AssetManager` uses `.new` instead, with an image it has already
+      # cached, so the sheet is shared with any other use of the same file.
+      def self.load(app, atlas_path)
+        data = JSON.parse(File.read(atlas_path), symbolize_names: true)
+        directory = File.dirname(File.expand_path(atlas_path))
+        new(Image.new(app, File.join(directory, data[:image])), data)
+      end
+
+      # `data` is the parsed descriptor; `image` an already-loaded sheet.
+      def initialize(image, data)
+        sheet_scale = data[:scale] || 1
+
+        @nine_slices = (data[:nine_slices] || {}).to_h do |id, spec|
+          [id, element(id) { build_nine_slice(image, spec, sheet_scale) }]
+        end
+        @images = (data[:images] || {}).to_h do |id, spec|
+          [id, element(id) { image.subimage(spec[:x], spec[:y], spec[:w], spec[:h]) }]
+        end
+      end
+
+      private
+
+      def build_nine_slice(image, spec, sheet_scale)
+        NineSlice.new(image, x: spec[:x], y: spec[:y], w: spec[:w], h: spec[:h],
+                             border: spec[:border], scale: spec[:scale] || sheet_scale)
+      end
+
+      def element(id)
+        yield
+      rescue StandardError => e
+        raise ArgumentError, "ui atlas element #{id.inspect}: #{e.message}"
+      end
+    end
+  end
+end

data/lib/rgame/core/virtual_gamepad.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'rgame/core_ext'
+
+module RGame
+  module Core
+    # A synthetic game controller, for tests that need the real gamepad path
+    # with no hardware. It is C (`ext/rgame_core/input/virtual_gamepad.c`, bound
+    # in `ruby/virtual_gamepad_ext.c`), and it serves tests, not gameplay.
+    #
+    #   pad = RGame::Core::VirtualGamepad.new   # an App must be open
+    #   pad.set_button(0, true)                  # SDL_CONTROLLER_BUTTON_A
+    #   pad.set_axis(0, -32_768)                 # left stick fully left
+    #   pad.detach                               # the App sees it unplugged
+    #
+    # SDL fabricates the device in-process, so the App seats it and raises its
+    # `gamepad_connected` and `gamepad_disconnected` callbacks as it would for a
+    # real pad. Buttons and axes take SDL's own numbers.
+    #
+    # It is part of the extension rather than a spec helper because only the
+    # extension is guaranteed to reach the SDL the App runs on, whether SDL is
+    # linked statically or dynamically.
+    class VirtualGamepad
+    end
+  end
+end

data/lib/rgame/core.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative 'version'
+require_relative 'core/app'
+require_relative 'core/locale'
+require_relative 'core/input'
+require_relative 'core/gamepad'
+require_relative 'core/virtual_gamepad'
+require_relative 'core/image'
+require_relative 'core/renderer'
+require_relative 'core/recording'
+require_relative 'core/font'
+require_relative 'core/audio'
+require_relative 'core/sprite_sheet'
+require_relative 'core/nine_slice'
+require_relative 'core/ui_atlas'
+require_relative 'core/tile_map_renderer'
+require_relative 'core/asset_manager'

data/lib/rgame/engine/actor_blockers.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    # The registered colliders as a blocker source: the broadphase answers "what is near
+    # this box", and the same snapping arithmetic TileBlockers runs against a tile edge
+    # runs against a collider's edge instead. Pure — it needs no scene, no node and no
+    # tree, only something answering `query_box` and `reindex`.
+    #
+    # It answers the blocker-source question — "where does this box land moving dx" — that
+    # Engine::CollisionSystem asks of every source it holds; see that class's header for
+    # the protocol and for how the most restrictive answer wins across sources. This is
+    # the source that makes two actors stop each other the way a wall stops one.
+    #
+    # ## Per body, unlike the other sources
+    #
+    # A TileBlockers is the same grid for everybody, so one is shared by every actor on
+    # the map. This one takes an `owner` and a layer list, so it belongs to exactly one
+    # body: two actors declaring different `blocked_by` cannot share one. That is why
+    # Components::Mover builds its own resolver rather than borrowing the scene's.
+    #
+    # ## Three things a grid does not need
+    #
+    # - **The most restrictive candidate wins.** Several colliders may be in the way, so
+    #   this keeps a running minimum (maximum, going the other way). That is
+    #   dup-insensitive, which matters because the broadphase may offer the same collider
+    #   once per cell the two share.
+    # - **An overlap that already exists is not resolved.** A step is blocked only if it
+    #   *crosses* an edge the mover was on the near side of. Two actors that start
+    #   overlapping stay overlapping and neither is teleported out — blocking stops the
+    #   mover, it never moves the thing it hit.
+    # - **Boxes only.** A CircleCollider on a blocked layer is skipped, and still reports
+    #   on_hit exactly as it does now. It is a documented limit rather than a raise at
+    #   attach: layer membership is a runtime fact, so a check at attach would catch only
+    #   the circles that already exist and quietly miss the ones spawned later.
+    class ActorBlockers
+      # `world` answers query_box/reindex (a Components::CollisionWorld); `owner` is the
+      # mover's own collider, excluded by identity so a body is never stopped by itself;
+      # `layers` is the set of collider layers that may stop it.
+      def initialize(world:, owner:, layers:)
+        @world = world
+        @owner = owner
+        @layers = Array(layers)
+        @blocker = nil
+      end
+
+      # Who produced the edge the last resolve_x / resolve_y returned, or nil when that
+      # axis was free. Per-move state, and safe because this source belongs to one body,
+      # which reads it inside its own update.
+      attr_reader :blocker
+
+      # Where the box's left edge lands moving dx, snapping flush against the nearest
+      # collider it would cross into.
+      def resolve_x(x, y, w, h, dx)
+        @blocker = nil
+        nx = x + dx
+        return nx if dx.zero?
+
+        sweep_x = dx.negative? ? nx : x
+        @best = nx
+        @world.query_box(sweep_x, y, w + dx.abs, h) do |other|
+          next unless candidate?(other)
+          next unless y < other.aabb_y + other.aabb_h && other.aabb_y < y + h
+
+          if dx.positive?
+            edge = other.aabb_x
+            take_min(edge - w, other) if x + w <= edge && nx + w > edge
+          else
+            edge = other.aabb_x + other.aabb_w
+            take_max(edge, other) if x >= edge && nx < edge
+          end
+        end
+        @best
+      end
+
+      # The mirror of resolve_x. CollisionSystem feeds it the resolved x, which is what
+      # makes a diagonal push into a wall slide along it.
+      def resolve_y(x, y, w, h, dy)
+        @blocker = nil
+        ny = y + dy
+        return ny if dy.zero?
+
+        sweep_y = dy.negative? ? ny : y
+        @best = ny
+        @world.query_box(x, sweep_y, w, h + dy.abs) do |other|
+          next unless candidate?(other)
+          next unless x < other.aabb_x + other.aabb_w && other.aabb_x < x + w
+
+          if dy.positive?
+            edge = other.aabb_y
+            take_min(edge - h, other) if y + h <= edge && ny + h > edge
+          else
+            edge = other.aabb_y + other.aabb_h
+            take_max(edge, other) if y >= edge && ny < edge
+          end
+        end
+        @best
+      end
+
+      # Called by CollisionSystem#move once the resolved position is written back, with
+      # the box the step started from. Re-bucketing the owner here is what keeps the index
+      # exact for whoever resolves next this step; see CollisionWorld#reindex.
+      def moved(_actor, from_x, from_y, from_w, from_h)
+        @world.reindex(@owner, from_x, from_y, from_w, from_h)
+      end
+
+      private
+
+      def take_min(landed, other)
+        return unless landed < @best
+
+        @best = landed
+        @blocker = other
+      end
+
+      def take_max(landed, other)
+        return unless landed > @best
+
+        @best = landed
+        @blocker = other
+      end
+
+      def candidate?(other)
+        !other.equal?(@owner) &&
+          other.is_a?(Components::BoxCollider) &&
+          @layers.include?(other.layer) &&
+          !other.node.freed?
+      end
+    end
+  end
+end

data/lib/rgame/engine/animation_set.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    # Pure animation math: given an atlas's animation table and an elapsed time,
+    # resolve which sprite-sheet cell (row, col) to show. No renderer, no images —
+    # fully testable.
+    #
+    # animations: { name => { row:, col:, frames:, fps:, flip_x: }, ... }
+    #   row     – sheet row
+    #   col     – starting column (default 0); lets an animation begin mid-row,
+    #             e.g. a 1-frame "stand" pointing at the neutral middle pose
+    #   frames  – number of frames, advancing across columns from `col`
+    #   fps     – frames per second
+    #   flip_x  – draw mirrored horizontally
+    class AnimationSet
+      Anim = Struct.new(:row, :first_col, :frames, :frame_secs, :flip_x)
+      private_constant :Anim
+
+      def initialize(animations)
+        @anims = animations.each_with_object({}) do |(name, a), table|
+          table[name.to_sym] = Anim.new(a[:row], a[:col] || 0, a[:frames], 1.0 / a[:fps], a[:flip_x] || false)
+        end
+      end
+
+      # Sheet row of `name` (fixed per animation).
+      def row(name)
+        @anims.fetch(name).row
+      end
+
+      # Sheet column of `name` at `elapsed` seconds — the only part that animates.
+      def col(name, elapsed)
+        anim = @anims.fetch(name)
+        anim.first_col + ((elapsed / anim.frame_secs).floor % anim.frames)
+      end
+
+      # Whether `name` draws mirrored (fixed per animation).
+      def flip_x(name)
+        @anims.fetch(name).flip_x
+      end
+
+      # [row, col, flip_x] for the given animation at `elapsed` seconds. A convenience
+      # for tests/inspection — it allocates an Array, so the per-frame draw path reads the
+      # row/col/flip_x accessors above directly instead.
+      def frame(name, elapsed)
+        [row(name), col(name, elapsed), flip_x(name)]
+      end
+    end
+  end
+end

data/lib/rgame/engine/animator.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    # Owns animation playback state for one actor: the AnimationSet plus the current
+    # animation name and elapsed time. Pure logic — the renderer asks it for the
+    # current [row, col, flip_x] cell. This is what makes an actor own its own
+    # animations instead of the scene passing an AnimationSet in every frame.
+    class Animator
+      def initialize(animation_set, initial: :stand)
+        @animation_set = animation_set
+        @current = initial
+        @elapsed = 0.0
+      end
+
+      attr_reader :current, :elapsed
+
+      # Switch to `name`; restarts elapsed time on an actual change (a no-op if the
+      # animation is already playing, so a continuing walk keeps cycling).
+      def play(name)
+        return if name == @current
+
+        @current = name
+        @elapsed = 0.0
+      end
+
+      def update(dt)
+        @elapsed += dt
+      end
+
+      # Current animation's row/col/flip_x, resolved without allocating — the per-frame
+      # draw path reads these directly.
+      def row = @animation_set.row(@current)
+      def col = @animation_set.col(@current, @elapsed)
+      def flip_x = @animation_set.flip_x(@current)
+
+      # [row, col, flip_x] for the current animation at the current elapsed time. A
+      # convenience for tests/inspection; it allocates, so draw uses the accessors above.
+      def frame
+        @animation_set.frame(@current, @elapsed)
+      end
+    end
+  end
+end

data/lib/rgame/engine/audio_bus.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    # A global, always-present audio bus: gameplay emits audio *facts* here (decoupled
+    # from any actual playback), and an AudioDirector turns them into sound. A module
+    # rather than an instance so any node can reach it without wiring.
+    module AudioBus
+      @on_play_sound = Signal.define(:id).new
+      @on_play_music = Signal.define(:id).new
+      @on_stop_music = Signal.define.new
+
+      def self.on_play_sound = @on_play_sound
+      def self.on_play_music = @on_play_music
+      def self.on_stop_music = @on_stop_music
+
+      # Emit shims so callers say `AudioBus.play_sound(:boom)` rather than reaching
+      # through the signal. The signal is still the subscription seam (AudioDirector).
+      def self.play_sound(id) = @on_play_sound.emit(id)
+      def self.play_music(id) = @on_play_music.emit(id)
+      def self.stop_music = @on_stop_music.emit
+    end
+  end
+end

data/lib/rgame/engine/audio_director.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    # The registered handler that turns audio *events* into audio *playback*.
+    # Gameplay emits facts — `:play_sound`/`:play_music`/`:stop_music` with the asset
+    # id as payload — through the EventDispatcher, never touching the backend; this
+    # observer forwards each to an injected audio server (anything responding to
+    # #play_sound/#play_music/#stop_music: `RGame::Core::Audio` in a game, a recording
+    # fake in specs). Pure logic — it names no audio class, and the 'an audio server'
+    # contract in spec/support/shared_examples/ is the interface it calls, so a
+    # stand-in is checked against what the real device does.
+    class AudioDirector
+      def initialize(audio)
+        @audio = audio
+      end
+
+      # Subscribe to the audio events on a hub (the global AudioBus by default, but
+      # any object exposing the same three signals). Returns self, so a caller can
+      # build and subscribe in one expression.
+      #
+      # **The handles are kept, so `unsubscribe` can take them back off.** AudioBus
+      # is a module — one hub for the whole process — and it holds its listeners
+      # until something removes them. A connected director is therefore reachable
+      # from a global, and it keeps the audio device alive, along with the asset
+      # manager that device resolves paths through and the App that manager loads
+      # images for, down to the window.
+      #
+      # A game never notices, because its App lives as long as the process does.
+      # Anywhere an App is created and discarded — a spec, a tool,
+      # `tools/drive_test_project.rb` — it is the difference between a window
+      # closing and a window leaking. RGame::Game subscribes a director when it
+      # starts and releases it when the loop ends, which is why a game calls
+      # neither method itself.
+      def subscribe(audio_bus = Engine::AudioBus)
+        @bus = audio_bus
+        @handles = [
+          audio_bus.on_play_sound.connect { @audio.play_sound(it) },
+          audio_bus.on_play_music.connect { @audio.play_music(it) },
+          audio_bus.on_stop_music.connect { @audio.stop_music }
+        ]
+        self
+      end
+
+      # Takes this director's listeners back off the hub. Safe to call twice, and
+      # safe on a director that was never subscribed — releasing something is not
+      # a good place to be strict about how many times it happens.
+      def unsubscribe
+        return self if @handles.nil?
+
+        @bus.on_play_sound.disconnect(@handles[0])
+        @bus.on_play_music.disconnect(@handles[1])
+        @bus.on_stop_music.disconnect(@handles[2])
+        @handles = nil
+        self
+      end
+    end
+  end
+end