rgame 0.4.0-x86_64-linux-gnu

data/lib/rgame/core/nine_slice.rb

@@ -0,0 +1,142 @@
+# 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)
+        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
+        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)
+
+        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
+
+      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
+
+      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
+
+      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,54 @@
+# frozen_string_literal: true
+
+require 'rgame/core_ext'
+require_relative '../util/color'
+require_relative '../util/z'
+
+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
+      Z = RGame::Util::Z
+
+      # 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.offset(z), Color.coerce(color).packed)
+      end
+    end
+  end
+end

data/lib/rgame/core/renderer.rb

@@ -0,0 +1,354 @@
+# frozen_string_literal: true
+
+require 'rgame/core_ext'
+require_relative 'font'
+require_relative '../util/color'
+require_relative '../util/z'
+
+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 sorted when the
+    # frame closes, so what ends up on top is decided by z rather than by call
+    # order. Equal z keeps call order, which is what stops same-layer sprites
+    # flickering between frames.
+    #
+    # ## `z:` is an offset inside the current layer, not a global number
+    #
+    # A `z:` is added to whatever `#layered` most recently pushed, and must be
+    # within RGame::Util::Z::Z_MIN..Z_MAX — one *node's* worth of room. It
+    # orders that node's own drawing (its panel under its label, a shadow under
+    # its sprite) and can reach nothing else. Which node comes before which is
+    # the scene graph's business, resolved by the traversal and handed here as a
+    # layer; see RGame::Util::Z.
+    #
+    # A caller outside any `#layered` block draws at the base layer 0, which is
+    # what a spec or a bare script gets.
+    #
+    # The C half of this class (ext/rgame_core/ruby/renderer_ext.c) has the `draw_*`
+    # and `push_*` primitives, registered private; everything here is the
+    # surface over them, so a draw cannot skip the z offset or the colour
+    # coercion, and a push cannot go without its pop.
+    #
+    # ## 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
+
+      Z = RGame::Util::Z
+
+      SHAPE_Z = 50
+      IMAGE_Z = 0
+
+      CIRCLE_SEGMENTS = 64
+
+      TEXT_Z = 10
+      FONT_SIZE = 18
+
+      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
+
+      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 — its nine-slices and its images —
+      # 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) }
+        atlas.images.each { |id, image| register_image(id, image) }
+        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
+
+      # One layer of a tile map — the layer a Tiled `.tmx` lists at `layer`,
+      # counting from the bottom.
+      #
+      # One layer rather than the whole map, because a scene draws its actors
+      # between two of them: trunks under, canopies over. Which is which is the
+      # scene tree's business — `RGame::Engine::TileMapLayer` mounts a node per
+      # layer — so this takes no `z:`.
+      #
+      # **Drawn in world coordinates**: a tile at column 3 lands at
+      # `3 * tile_width`, and getting it onto the screen is the caller's
+      # transform, like every other drawing method here. The rectangle is a
+      # **cull rect** — which part of the world is worth drawing — so a camera
+      # supplies it but does not move the result. That is what lets one map be
+      # drawn through several cameras in a frame.
+      #
+      # `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, layer, cull_x, cull_y, cull_width, cull_height, elapsed: 0.0)
+        lookup(:tilemap, id)
+          .draw_layer(self, layer, cull_x, cull_y, cull_width, cull_height, 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.offset(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.offset(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.offset(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.offset(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.offset(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.offset(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.offset(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.offset(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
+          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 draws in its own layer: a fresh slot in
+      # `band`, which every `z:` inside is then an offset from.
+      #
+      #   renderer.layered(:hud) { renderer.text(score, 12, 10) }
+      #
+      # Two things fall out of it, and they are the whole of draw order.
+      # **Slots are handed out in the order they are asked for**, so nesting
+      # this the way a scene graph is nested makes draw order tree order — a
+      # node drawn later is in front, and its whole subtree with it. And **a
+      # band is a hard partition**: every slot in `:hud` is above every slot in
+      # `:world`, whatever either drew, because they are 2**40 apart and a `z:`
+      # cannot reach out of one slot. See RGame::Util::Z.
+      #
+      # A caller that never uses this draws at layer 0 and gets exactly the z it
+      # passes, which is what a spec or a one-off script wants.
+      def layered(band = Z::DEFAULT)
+        index = Z.index(band)
+        push_layer(Z.slot_base(index, next_layer_slot(index)))
+        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.offset(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
+          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
+
+      def packed(color) = Color.coerce(color).packed
+
+      def resolve_image(image) = image.is_a?(Image) ? image : lookup(:image, image)
+
+      def registry(type) = (@registries ||= {})[type] ||= {}
+
+      def lookup(type, id)
+        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
+
+      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,105 @@
+# 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
+
+      def missing(key)
+        raise ArgumentError, "sprite sheet descriptor has no #{key}"
+      end
+    end
+  end
+end