rgame 0.1.0

data/lib/rgame/core/nine_slice.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+module RGame
+  module Core
+    # A bordered texture drawn at any size, by cutting it into nine pieces and
+    # treating each differently.
+    #
+    #   panel = RGame::Core::NineSlice.new(image, x: 0, y: 0, w: 26, h: 28,
+    #                                     border: 7, scale: 3)
+    #   panel.draw(renderer, x, y, width, height, z: 0)
+    #
+    # The four corners keep their size, the four edges stretch along one axis
+    # and the centre along both — so one small piece of art fills a button, a
+    # dialog or a health bar without the corners smearing.
+    #
+    # ```
+    #   ┌──┬────────┬──┐   corners: fixed
+    #   │tl│  top   │tr│   top / bottom: tiled across
+    #   ├──┼────────┼──┤   left / right: tiled down
+    #   │l │ centre │ r│   centre: tiled both ways
+    #   ├──┼────────┼──┤
+    #   │bl│ bottom │br│
+    #   └──┴────────┴──┘
+    # ```
+    #
+    # **Edges and the centre are *tiled*, not stretched.** Repeating a 7-pixel
+    # motif keeps pixel art crisp at any widget size; stretching it would blur
+    # exactly the detail the art was drawn for. Each band is clipped to itself,
+    # so the last tile in a row is cropped cleanly rather than spilling over the
+    # corner next to it.
+    #
+    # `scale` is an integer pixel scale for the chrome itself. Source art is
+    # small — corners are often 7 pixels — so a scale of 2 or 3 gives legible
+    # borders on a 640x480 screen without any blurring, because every source
+    # pixel becomes a whole square of screen pixels.
+    #
+    # The nine pieces are cut once at construction, so `#draw` allocates
+    # nothing. It is called once per widget per frame.
+    class NineSlice
+      # `border` is a uniform integer or a hash of `left`/`right`/`top`/`bottom`.
+      # (x, y, w, h) is the source rectangle inside `image`, so one sheet can
+      # hold many of these — which is what UiAtlas does with it.
+      def initialize(image, x:, y:, w:, h:, border:, scale: 1)
+        # A zero or negative scale would give every tile a step of zero pixels,
+        # and `#draw`'s tiling loops would never advance. Refusing it here costs
+        # nothing; a guard inside the loop would cost a branch per tile, per
+        # widget, per frame.
+        raise ArgumentError, "nine-slice scale must be positive, got #{scale}" unless scale.positive?
+
+        @scale = scale
+        border = normalize_border(border)
+        @l = border.fetch(:left)
+        @r = border.fetch(:right)
+        @t = border.fetch(:top)
+        @b = border.fetch(:bottom)
+
+        cut_pieces(image, x, y, w, h)
+      end
+
+      # Fills the rectangle (dx, dy, dw, dh).
+      #
+      # `color` tints every piece — a focus highlight, a disabled grey. A
+      # rectangle smaller than its own borders draws its corners and nothing
+      # else, which is the least misleading thing a widget too small for its own
+      # chrome can look like.
+      def draw(renderer, dx, dy, dw, dh, z: 0, color: nil)
+        s = @scale
+        l = @l * s
+        r = @r * s
+        t = @t * s
+        b = @b * s
+        # These go negative for a rectangle narrower than its own borders, and
+        # are not clamped: #band refuses a non-positive size anyway, so clamping
+        # here would be a second guard that cannot change any outcome — and
+        # would read as if the case were handled in two places.
+        inner_w = dw - l - r
+        inner_h = dh - t - b
+
+        band(renderer, @centre, dx + l, dy + t, inner_w, inner_h, z, color)
+        band(renderer, @top, dx + l, dy, inner_w, t, z, color)
+        band(renderer, @bottom, dx + l, dy + dh - b, inner_w, b, z, color)
+        band(renderer, @left, dx, dy + t, l, inner_h, z, color)
+        band(renderer, @right, dx + dw - r, dy + t, r, inner_h, z, color)
+
+        # Last, so a tile that reached the edge of its band is covered rather
+        # than showing through a corner's transparent pixels.
+        piece(renderer, @tl, dx, dy, z, color)
+        piece(renderer, @tr, dx + dw - r, dy, z, color)
+        piece(renderer, @bl, dx, dy + dh - b, z, color)
+        piece(renderer, @br, dx + dw - r, dy + dh - b, z, color)
+      end
+
+      private
+
+      # A uniform integer becomes four equal sides. Accepting both shapes here
+      # rather than in the callers is what makes `NineSlice.new(image, border: 7,
+      # ...)` work on its own — a bare integer would otherwise fail as
+      # `7[:left]`, which names nothing that appears in the caller's code.
+      def normalize_border(border)
+        return border.transform_keys(&:to_sym) unless border.is_a?(Integer)
+
+        { left: border, right: border, top: border, bottom: border }
+      end
+
+      def cut_pieces(image, x, y, w, h)
+        centre_w = w - @l - @r
+        centre_h = h - @t - @b
+        if centre_w.negative? || centre_h.negative?
+          raise ArgumentError,
+                "nine-slice borders (#{@l}, #{@r}, #{@t}, #{@b}) do not fit in a #{w}x#{h} rect"
+        end
+
+        @tl = cut(image, x, y, @l, @t)
+        @tr = cut(image, x + w - @r, y, @r, @t)
+        @bl = cut(image, x, y + h - @b, @l, @b)
+        @br = cut(image, x + w - @r, y + h - @b, @r, @b)
+
+        @top = cut(image, x + @l, y, centre_w, @t)
+        @bottom = cut(image, x + @l, y + h - @b, centre_w, @b)
+        @left = cut(image, x, y + @t, @l, centre_h)
+        @right = cut(image, x + w - @r, y + @t, @r, centre_h)
+        @centre = cut(image, x + @l, y + @t, centre_w, centre_h)
+      end
+
+      # A piece with no pixels is a legitimate part of a legitimate slice — a
+      # border with no centre column is a bar that only stretches vertically,
+      # and a zero border is one that does not stretch at all on that side. Such
+      # a piece is `nil` and simply never drawn; asking `Image#subimage` for it
+      # would raise.
+      def cut(image, x, y, width, height)
+        return nil unless width.positive? && height.positive?
+
+        image.subimage(x, y, width, height)
+      end
+
+      def piece(renderer, image, x, y, z, color)
+        return unless image
+
+        renderer.image_at(image, x, y, scale_x: @scale, scale_y: @scale, z: z, color: color)
+      end
+
+      # Repeats `image` across (bx, by, bw, bh), clipped to it so the trailing
+      # tile is cropped instead of overrunning into the next band.
+      def band(renderer, image, bx, by, bw, bh, z, color)
+        return if image.nil? || bw <= 0 || bh <= 0
+
+        step_x = image.width * @scale
+        step_y = image.height * @scale
+        renderer.clipped(bx, by, bw, bh) do
+          y = by
+          while y < by + bh
+            x = bx
+            while x < bx + bw
+              piece(renderer, image, x, y, z, color)
+              x += step_x
+            end
+            y += step_y
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rgame/core/recording.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require 'rgame/core_ext'
+require_relative '../util/color'
+
+module RGame
+  module Core
+    # A block of drawing baked once and replayed cheaply.
+    #
+    #   ground = renderer.record do
+    #     tiles.each { |tile| renderer.image(tile.image, tile.x, tile.y) }
+    #   end
+    #
+    #   def draw
+    #     ground.draw(-camera.x, -camera.y)
+    #   end
+    #
+    # A screen of tiles is a couple of thousand quads that have not changed
+    # since the level loaded. Baking them turns the per-frame cost from "walk
+    # every tile and transform four corners" into one call per texture — the
+    # work happens at bake time and never again.
+    #
+    # Recordings come from `Renderer#record`; there is no `new`.
+    #
+    # ## What is baked in and what is not
+    #
+    # Positions, texture coordinates and colours are baked, and so are any
+    # transforms applied *inside* the block. The transform in effect when the
+    # recording is *drawn* is applied on top, which is what lets a baked layer
+    # scroll under a camera without being rebuilt.
+    #
+    # Clipping is not baked — it happens when pixels are rasterised, so a clip
+    # rectangle captured in one place would be wrong everywhere else the
+    # recording is drawn. Pushing a clip inside a `record` block raises. Clip
+    # the replay instead:
+    #
+    #   renderer.clipped(0, 0, 400, 600) { ground.draw(0, 0) }
+    class Recording
+      Color = RGame::Util::Color
+
+      # Replays everything that was recorded, with the recording's origin at
+      # (x, y).
+      #
+      # `color` tints what was baked: each recorded colour is multiplied by it,
+      # so white (the default) draws the recording unchanged and a colour with
+      # alpha fades the whole layer out at once.
+      def draw(x = 0, y = 0, z: 0, color: nil)
+        draw_at(x, y, z, Color.coerce(color).packed)
+      end
+    end
+  end
+end

data/lib/rgame/core/renderer.rb

@@ -0,0 +1,363 @@
+# frozen_string_literal: true
+
+require 'rgame/core_ext'
+require_relative 'font'
+require_relative '../util/color'
+
+module RGame
+  module Core
+    # What a game draws with.
+    #
+    #   class MyGame < RGame::Core::App
+    #     def initialize
+    #       super(width: 800, height: 600, caption: 'demo')
+    #       @renderer = RGame::Core::Renderer.new(self)
+    #       @hero = RGame::Core::Image.new(self, 'hero.png')
+    #     end
+    #
+    #     def draw
+    #       @renderer.rect(10, 10, 100, 40, color: RGame::Util::Color::WHITE)
+    #       @renderer.image(@hero, 400, 300, angle: 45)
+    #     end
+    #   end
+    #
+    # Drawing is only legal inside `draw`, and calling one of these outside it
+    # raises. That is on purpose: the frame is not open, so the vertices would
+    # be silently discarded, and an invisible failure is the worst kind.
+    #
+    # Nothing is drawn immediately. Calls accumulate and are z-sorted when the
+    # frame closes, so `z:` decides what ends up on top — not call order. Equal
+    # z keeps call order, which is what stops same-layer sprites flickering
+    # between frames.
+    #
+    # The C half of this class (ext/rgame_core/ruby/renderer_ext.c) has the `draw_*`
+    # and `push_*` primitives; everything here is the comfortable surface over
+    # them.
+    #
+    # ## Colours
+    #
+    # Every drawing method takes `color:`, accepting whatever `Color.coerce`
+    # does: `nil` (white — an untinted draw), `[r, g, b]`, `[r, g, b, a]`, or a
+    # `RGame::Util::Color`. Passing a `Color` is the allocation-free path and is
+    # what per-frame code should do; an array allocates one colour per call.
+    class Renderer
+      Color = RGame::Util::Color
+
+      # Shapes default above sprites, so a debug box or a health bar drawn
+      # without a `z:` lands on top of the scene rather than under it. The
+      # values match the layer this replaces.
+      SHAPE_Z = 50
+      IMAGE_Z = 0
+
+      # Enough segments that a circle reads as round at the sizes a 2D game
+      # draws one, and few enough that a screenful of them is still one batch.
+      CIRCLE_SEGMENTS = 64
+
+      # Text defaults above sprites but below shapes, and the size matches what
+      # the layer this replaces used, so ported UI lays out unchanged.
+      TEXT_Z = 10
+      FONT_SIZE = 18
+
+      # Translucent red, for #debug_box.
+      DEBUG_BOX_COLOR = Color.new(255, 40, 40, 120)
+
+      # `assets:` is where a draw id that is not registered gets resolved from,
+      # and defaults to the app's own manager — so the common case wires itself
+      # and `renderer.sprite('hero.json', …)` works with nothing set up.
+      #
+      # A Ruby `self.new` because the C `initialize` has fixed arity and no
+      # business knowing what an asset manager is; the same shape `Font`'s
+      # `path:` uses.
+      def self.new(app, assets: nil)
+        renderer = super(app)
+        renderer.assets = assets.nil? ? app.assets : assets
+        renderer
+      end
+
+      attr_accessor :assets
+
+      # --- draw-by-id ---------------------------------------------------------
+      #
+      # Game logic names assets, it does not hold them: the engine layer may
+      # hold `RGame::Util` values but no `RGame::Core` handle at all, so a
+      # Symbol or a path is the only thing a node *can* carry. Resolving it is
+      # this side of the boundary's job.
+      #
+      # An id is normally a **root-relative path**, resolved through the asset
+      # manager and then remembered, so a per-frame draw neither re-resolves nor
+      # allocates a lookup key:
+      #
+      #   renderer.sprite('example 09/player.json', row, col, x, y)
+      #
+      # `register_*` pre-binds an id to a chosen object, for the two things a
+      # path cannot name: an id that is not a file (nine-slice ids are *atlas
+      # element* names) and an object the game assembled itself.
+
+      def register_image(id, image) = registry(:image)[id] = image
+      def register_sheet(id, sheet) = registry(:sheet)[id] = sheet
+      def register_tilemap(id, tilemap) = registry(:tilemap)[id] = tilemap
+      def register_nine_slice(id, nine_slice) = registry(:nine_slice)[id] = nine_slice
+
+      # Registers every element of a UiAtlas under its own name, since those
+      # names are what a widget asks for.
+      def register_ui_atlas(atlas)
+        atlas.nine_slices.each { |id, nine_slice| register_nine_slice(id, nine_slice) }
+        self
+      end
+
+      # One frame of a registered or resolvable sprite sheet, top-left at (x, y).
+      def sprite(id, row, col, x, y, flip_x: false, z: IMAGE_Z)
+        lookup(:sheet, id).draw(self, row, col, x, y, flip_x: flip_x, z: z)
+      end
+
+      # A nine-slice filling (x, y, width, height), tinted by `tint` if given.
+      # Registration only: a nine-slice id names an element of an atlas, not a
+      # file, so there is nothing for the asset manager to resolve it to.
+      def nine_slice(id, x, y, width, height, z: IMAGE_Z, tint: nil)
+        lookup(:nine_slice, id).draw(self, x, y, width, height, z: z, color: tint)
+      end
+
+      # A tile map's below-the-actor band (ground and same-level detail).
+      #
+      # `elapsed` is the seconds its animated tiles have been running for, and
+      # is an argument rather than a clock read on purpose — see CLAUDE.md,
+      # "`draw` renders state; time enters through `update`". A scene
+      # accumulates it in `update`, which is what makes pausing work.
+      def tilemap(id, camera_x, camera_y, viewport_width, viewport_height, elapsed: 0.0)
+        lookup(:tilemap, id)
+          .draw(self, camera_x, camera_y, viewport_width, viewport_height, elapsed: elapsed)
+      end
+
+      # Its above-the-actor band (canopies, roofs), at a `z` the scene picks so
+      # it lands over the actors.
+      def tilemap_overlay(id, camera_x, camera_y, viewport_width, viewport_height,
+                          z:, elapsed: 0.0)
+        lookup(:tilemap, id).draw_overlay(self, camera_x, camera_y, viewport_width,
+                                          viewport_height, z: z, elapsed: elapsed)
+      end
+
+      # A filled axis-aligned rectangle.
+      def rect(x, y, width, height, z: SHAPE_Z, color: nil)
+        draw_rect(x, y, width, height, z, packed(color))
+      end
+
+      # Four arbitrary points, in loop order: listing them in Z order gives an
+      # hourglass rather than a shape.
+      def quad(x1, y1, x2, y2, x3, y3, x4, y4, z: SHAPE_Z, color: nil)
+        draw_quad(x1, y1, x2, y2, x3, y3, x4, y4, z, packed(color))
+      end
+
+      def triangle(x1, y1, x2, y2, x3, y3, z: SHAPE_Z, color: nil)
+        draw_triangle(x1, y1, x2, y2, x3, y3, z, packed(color))
+      end
+
+      # A line of real thickness — drawn as a quad, because GL's own line width
+      # is a suggestion drivers may ignore above one pixel.
+      def line(x1, y1, x2, y2, thickness: 1.0, z: SHAPE_Z, color: nil)
+        draw_line(x1, y1, x2, y2, thickness, z, packed(color))
+      end
+
+      # A filled circle, as a fan of triangles around its centre.
+      def circle(cx, cy, radius, z: SHAPE_Z, color: nil, segments: CIRCLE_SEGMENTS)
+        draw_circle(cx, cy, radius, segments, z, packed(color))
+      end
+
+      # An image centred on (cx, cy), rotated `angle` degrees clockwise about
+      # that centre and uniformly scaled. Unrotated and unscaled is a fast path
+      # that skips the transform stack entirely.
+      #
+      # Takes an `Image` or an id for one — see #resolve_image.
+      def image(image, cx, cy, angle: 0, scale: 1, z: IMAGE_Z, color: nil)
+        draw_image_rot(resolve_image(image), cx, cy, angle, scale, z, packed(color))
+      end
+
+      # An image with its top-left at (x, y), scaled independently per axis —
+      # a tile, a nine-slice corner, a sprite-sheet frame.
+      #
+      # A **negative scale mirrors the image inside the same rectangle**; it
+      # does not move it. So a frame drawn at (x, y) covers the same pixels
+      # whichever way it faces, and `scale_x: -1` means "facing the other way"
+      # rather than "one width to the left":
+      #
+      #   renderer.image_at(frame, x, y, scale_x: facing_left ? -1 : 1)
+      #
+      # A zero scale draws nothing.
+      def image_at(image, x, y, scale_x: 1, scale_y: 1, z: IMAGE_Z, color: nil)
+        draw_image_scaled(resolve_image(image), x, y, scale_x, scale_y, z, packed(color))
+      end
+
+      # An image with its top-left at (x, y), at its natural size — a
+      # full-screen backdrop by default. `image_at` with both scales at 1, kept
+      # because "put this at the origin" is worth a name of its own.
+      def background(image, x = 0, y = 0, z: IMAGE_Z, color: nil)
+        draw_image(resolve_image(image), x, y, z, packed(color))
+      end
+
+      # Everything drawn in the block is rotated `angle` degrees about
+      # (pivot_x, pivot_y), so a node can spin all of its parts coherently
+      # around one point.
+      #
+      # A zero angle skips the push entirely — unrotated drawing pays nothing,
+      # which matters because most drawing is unrotated.
+      def rotated(angle, pivot_x, pivot_y)
+        return yield if angle.zero?
+
+        push_rotate(angle, pivot_x, pivot_y)
+        begin
+          yield
+        ensure
+          # An ensure, not a plain pop: a scene that raises mid-draw would
+          # otherwise leave the stack deeper than it found it, and every
+          # later frame would draw askew for a reason nothing points at.
+          pop
+        end
+      end
+
+      # Everything drawn in the block is shifted by (dx, dy) screen pixels —
+      # the camera's view transform. Because it is a draw-time transform rather
+      # than something baked into positions, the same world can be drawn again
+      # under a different offset and clip, which is what split-screen is.
+      def translated(dx, dy)
+        return yield if dx.zero? && dy.zero?
+
+        push_translate(dx, dy)
+        begin
+          yield
+        ensure
+          pop
+        end
+      end
+
+      def scaled(sx, sy = sx)
+        return yield if sx == 1 && sy == 1
+
+        push_scale(sx, sy)
+        begin
+          yield
+        ensure
+          pop
+        end
+      end
+
+      # Everything drawn in the block is confined to the given rectangle.
+      #
+      # A clip only ever narrows: nesting one inside another intersects them, so
+      # a child cannot draw outside the region its parent allowed. Give each
+      # player a clipped block and you have split-screen.
+      def clipped(x, y, width, height)
+        push_clip(x, y, width, height)
+        begin
+          yield
+        ensure
+          pop
+        end
+      end
+
+      # The font this renderer draws with when a call does not name one.
+      #
+      # Built on first use rather than in the constructor: creating a font needs
+      # a GL context, and a renderer is often built before there is one. Set
+      # your own with #font= to change what every unqualified #text call uses.
+      def font
+        @font ||= Font.new(app, FONT_SIZE)
+      end
+
+      attr_writer :font
+
+      # One line of text, with its top-left corner at (x, y) — the same corner
+      # every other drawing method takes, rather than the baseline typography
+      # would use.
+      #
+      # Newlines are not special. A caller wanting two lines draws two, stepping
+      # by #text_height.
+      def text(string, x, y, z: TEXT_Z, color: nil, font: nil)
+        draw_text(font || self.font, string, x, y, z, packed(color))
+      end
+
+      # What #text would occupy, for centring and layout. Unlike the drawing
+      # methods this works outside `draw`, because measuring touches no GL.
+      def text_width(string, font: nil) = (font || self.font).text_width(string)
+
+      # The line height: what to step y by for a second line.
+      def text_height(font: nil) = (font || self.font).height
+
+      # Bakes everything the block draws into a RGame::Core::Recording, which
+      # can then be replayed for the cost of one call per texture however many
+      # draws went into it. Nothing is drawn *now* — the block's output goes
+      # into the recording instead of into this frame.
+      #
+      #   ground = renderer.record { tiles.each { |t| renderer.image(t.img, t.x, t.y) } }
+      #   ground.draw(-camera.x, -camera.y)
+      #
+      # Recording happens inside `draw` like everything else, and does not
+      # nest. A clip pushed inside the block raises: clipping cannot be baked,
+      # so clip the replay instead. See RGame::Core::Recording.
+      def record
+        begin_record
+        completed = false
+        begin
+          yield
+          completed = true
+        ensure
+          # A block that raised leaves a half-built recording open, and the
+          # next frame would keep drawing into it. Unwinding here means the
+          # exception is the only thing the caller has to deal with.
+          cancel_record unless completed
+        end
+        end_record
+      end
+
+      # A translucent overlay for visualising a collision box, so a scene can
+      # ask for one without knowing what colour "debug" is.
+      def debug_box(x, y, width, height, z: SHAPE_Z)
+        rect(x, y, width, height, z: z, color: DEBUG_BOX_COLOR)
+      end
+
+      private
+
+      # Colours cross into C as a packed integer. `Color.coerce` is the single
+      # place nil/array/Color are turned into one, so no drawing method has its
+      # own idea of what a colour is.
+      def packed(color) = Color.coerce(color).packed
+
+      # An `Image` is already what it is; anything else is an id for one.
+      #
+      # The two callers this serves cannot be reconciled any other way. Core's
+      # own drawing classes — SpriteSheet, NineSlice — hold real images and pass
+      # them; the engine layer is forbidden from holding one and can only pass
+      # an id. Dispatching on the type keeps both spellings of `#image` and
+      # `#background` working without two parallel method names for the same
+      # picture.
+      def resolve_image(image) = image.is_a?(Image) ? image : lookup(:image, image)
+
+      def registry(type) = (@registries ||= {})[type] ||= {}
+
+      # Prefer an explicit registration, otherwise ask the asset manager, then
+      # remember the answer — so a per-frame draw neither re-resolves nor
+      # allocates a lookup key.
+      def lookup(type, id)
+        # `nil` is never an id, and reporting it as one ("no image registered
+        # for nil") describes a typo when the actual bug is an asset that
+        # resolved to nothing. The two want different fixes.
+        raise TypeError, "no implicit conversion of nil into #{type}" if id.nil?
+
+        table = registry(type)
+        table.fetch(id) { table[id] = resolve_asset(type, id) }
+      end
+
+      # Only a String is offered to the asset manager, because only a String can
+      # be a path. A Symbol id is a name a game chose, so a missing one is the
+      # KeyError below — naming the id — rather than whatever the manager makes
+      # of being handed a Symbol where it wanted a filename.
+      #
+      # `respond_to?` for the same reason one step along: the manager grows an
+      # accessor per asset type, and asking for one it does not have yet should
+      # be this error rather than a NoMethodError from inside it.
+      def resolve_asset(type, id)
+        resolved = @assets.public_send(type, id) if id.is_a?(String) && @assets.respond_to?(type)
+        resolved || raise(KeyError, "no #{type} registered for #{id.inspect} " \
+                                    'and no AssetManager to resolve it')
+      end
+    end
+  end
+end

data/lib/rgame/core/sprite_sheet.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require 'json'
+
+require_relative 'image'
+
+module RGame
+  module Core
+    # A texture atlas — one image plus a JSON descriptor — sliced into frames and
+    # drawn one at a time.
+    #
+    #   sheet = RGame::Core::SpriteSheet.load(app, 'media/hero.json')
+    #   sheet.draw(renderer, row, col, x, y, flip_x: facing_left, z: 10)
+    #
+    # ## The descriptor
+    #
+    #   {
+    #     "image": "hero.png",
+    #     "frame_width": 16, "frame_height": 24,
+    #     "cell_width": 32, "cell_height": 32,
+    #     "origin_x": 8, "origin_y": 4,
+    #     "animations": { "walk_left": { "row": 1, "frames": 4, "fps": 8 } }
+    #   }
+    #
+    # `image` is resolved next to the descriptor. The rest describes the grid.
+    #
+    # **A frame can be smaller than its cell.** Cells are laid out on a fixed
+    # `cell_width` x `cell_height` grid, but what is *drawn* is a
+    # `frame_width` x `frame_height` rectangle offset by `origin_x`/`origin_y`
+    # inside the cell. That is what lets a sheet whose cells are sized for the
+    # widest pose — an attack, a swing — still expose a tight, centred box for
+    # walking, so a character does not appear to change size between animations.
+    # Leave the cell and origin keys out and frame == cell, which is what a
+    # simple sheet wants.
+    #
+    # `animations` is handed back untouched by `#animations`. This class knows
+    # nothing about time; the scene layer builds its own animation table from
+    # that hash, which is why the raw form is what gets exposed.
+    #
+    # ## Slicing costs nothing
+    #
+    # Every frame is cut once, at construction, as a view onto the one upload —
+    # so a sheet of two hundred frames is two hundred small objects and a single
+    # texture, and `#draw` is an array index plus one call.
+    class SpriteSheet
+      attr_reader :frame_width, :frame_height, :animations
+
+      # Loads a descriptor and the image beside it.
+      #
+      # The `AssetManager` does not use this — it calls `.new` with an image it
+      # has already cached, so a sheet's PNG is shared with a standalone load of
+      # the same file. This is the standalone path, for a game with one sheet
+      # and no asset manager.
+      def self.load(app, atlas_path)
+        atlas = JSON.parse(File.read(atlas_path), symbolize_names: true)
+        directory = File.dirname(File.expand_path(atlas_path))
+        new(Image.new(app, File.join(directory, atlas[:image])), atlas)
+      end
+
+      # `atlas` is the parsed descriptor; `image` an already-loaded sheet image.
+      def initialize(image, atlas)
+        @frame_width = atlas.fetch(:frame_width) { missing(:frame_width) }
+        @frame_height = atlas.fetch(:frame_height) { missing(:frame_height) }
+        @animations = atlas[:animations] || {}
+
+        @frames = slice(image, atlas)
+      end
+
+      # Draws one frame with its top-left at (x, y).
+      #
+      # `flip_x` mirrors the frame within that same rectangle, so a character
+      # occupies the same pixels whichever way it faces — see
+      # RGame::Core::Renderer#image_at.
+      def draw(renderer, row, col, x, y, flip_x: false, z: 0)
+        renderer.image_at(@frames[row][col], x, y, scale_x: flip_x ? -1 : 1, z: z)
+      end
+
+      # How many frames the sheet was cut into, as [rows, columns].
+      def grid = [@frames.length, @frames.empty? ? 0 : @frames[0].length]
+
+      private
+
+      def slice(image, atlas)
+        cell_width = atlas[:cell_width] || @frame_width
+        cell_height = atlas[:cell_height] || @frame_height
+        origin_x = atlas[:origin_x] || 0
+        origin_y = atlas[:origin_y] || 0
+
+        columns = image.width / cell_width
+        rows = image.height / cell_height
+
+        Array.new(rows) do |row|
+          Array.new(columns) do |col|
+            image.subimage((col * cell_width) + origin_x, (row * cell_height) + origin_y,
+                           @frame_width, @frame_height)
+          end
+        end
+      end
+
+      # A typo'd or missing key would otherwise surface as a NoMethodError on nil
+      # from inside the slicing arithmetic, which says nothing about the file
+      # that is actually wrong.
+      def missing(key)
+        raise ArgumentError, "sprite sheet descriptor has no #{key}"
+      end
+    end
+  end
+end