rgame 0.1.0 → 0.3.0

data/lib/rgame/core/renderer.rb

@@ -3,6 +3,7 @@
 require 'rgame/core_ext'
 require_relative 'font'
 require_relative '../util/color'
+require_relative '../util/z'
 
 module RGame
   module Core
@@ -25,14 +26,27 @@ module RGame
     # 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.
+    # 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; everything here is the comfortable surface over
-    # them.
+    # 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
     #
@@ -43,22 +57,16 @@ module RGame
     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.
+      Z = RGame::Util::Z
+
       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,
@@ -76,32 +84,16 @@ module RGame
 
       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.
+      # 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
 
@@ -117,49 +109,54 @@ module RGame
         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).
+      # 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, camera_x, camera_y, viewport_width, viewport_height, elapsed: 0.0)
+      def tilemap(id, layer, cull_x, cull_y, cull_width, cull_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)
+          .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, packed(color))
+        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, packed(color))
+        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, packed(color))
+        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, packed(color))
+        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, packed(color))
+        draw_circle(cx, cy, radius, segments, Z.offset(z), packed(color))
       end
 
       # An image centred on (cx, cy), rotated `angle` degrees clockwise about
@@ -168,7 +165,7 @@ module RGame
       #
       # 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))
+        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 —
@@ -183,14 +180,14 @@ module RGame
       #
       # 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))
+        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, packed(color))
+        draw_image(resolve_image(image), x, y, Z.offset(z), packed(color))
       end
 
       # Everything drawn in the block is rotated `angle` degrees about
@@ -206,9 +203,6 @@ module RGame
         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
@@ -239,6 +233,31 @@ module RGame
         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
@@ -271,7 +290,7 @@ module RGame
       # 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))
+        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
@@ -299,9 +318,6 @@ module RGame
           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
@@ -315,44 +331,19 @@ module RGame
 
       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} " \

data/lib/rgame/core/sprite_sheet.rb

@@ -97,9 +97,6 @@ module RGame
         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

data/lib/rgame/core/tile_map_renderer.rb

@@ -3,31 +3,53 @@
 module RGame
   module Core
     # Draws a tile map: the static layers baked once, the animated tiles drawn
-    # per frame and culled to the viewport.
+    # per frame, both culled to a rectangle of the world.
     #
     #   tiles = RGame::Core::TileMapRenderer.new(map, tileset_images)
     #
-    #   tiles.draw(renderer, camera_x, camera_y, view_w, view_h, elapsed: seconds)
-    #   tiles.draw_overlay(renderer, camera_x, camera_y, view_w, view_h, z: 20,
+    #   map.layer_count.times do |layer|
+    #     tiles.draw_layer(renderer, layer, cull_x, cull_y, cull_w, cull_h,
     #                      elapsed: seconds)
+    #   end
     #
-    # ## Two bands, with the actors between them
+    # ## It draws in world coordinates
     #
-    # Layers split by the map's own `above_layer?` flag. The **below** band —
-    # ground, and detail on the actors' level — is drawn under them by `#draw`;
-    # the **above** band — tree canopies, roofs — over them by `#draw_overlay`,
-    # at a `z` the scene picks. Two calls rather than one because the scene
-    # draws its actors in between, and collapsing them would put every canopy
-    # behind every character.
+    # 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 band, every tile that is *not* animated is baked into one
-    # recording, the first time that band is drawn. Scrolling a baked layer is
+    # 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
@@ -44,9 +66,9 @@ module RGame
     # 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`, `above_layer?`, `width`,
-    # `height`, `tile_width`, `tile_height`, `gid`, and a `tileset` answering
-    # `local_id`, `animations` and `frame_local_id`.
+    # `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.
@@ -58,50 +80,51 @@ module RGame
         @map = map
         @tileset = map.tileset
         @tiles = tiles
-        @animated_below, @animated_above = collect_animated_tiles
-        # Baked on first draw, not here: recording needs a live frame, and there
-        # is no renderer at construction.
-        @static_below = nil
-        @static_above = nil
+        @animated = collect_animated_tiles
+        @static = Array.new(map.layer_count)
       end
 
-      def draw(renderer, camera_x, camera_y, viewport_width, viewport_height, elapsed: 0.0)
-        @static_below ||= bake(renderer) { |layer| !@map.above_layer?(layer) }
-        @static_below.draw(-camera_x, -camera_y, z: BELOW_Z)
-        draw_animated(renderer, @animated_below, camera_x, camera_y,
-                      viewport_width, viewport_height, BELOW_Z, elapsed)
-      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
 
-      def draw_overlay(renderer, camera_x, camera_y, viewport_width, viewport_height,
-                       z:, elapsed: 0.0)
-        @static_above ||= bake(renderer) { |layer| @map.above_layer?(layer) }
-        @static_above.draw(-camera_x, -camera_y, z: z)
-        draw_animated(renderer, @animated_above, camera_x, camera_y,
-                      viewport_width, viewport_height, z, elapsed)
+        @static[index] ||= bake(renderer, index)
+        @static[index].draw
+        draw_animated(renderer, @animated[index], cull_x, cull_y,
+                      cull_width, cull_height, elapsed)
       end
 
-      # The ground band sits at the bottom; the scene chooses where the overlay
-      # goes, because only it knows what its actors are drawn at.
-      BELOW_Z = 0
-
       private
 
-      # [col, row, local_id] for every animated tile, split into the two bands.
-      # Walked once at construction: a map is thousands of tiles and a handful
-      # of animated ones, and finding them again each frame would be the whole
-      # cost this class exists to avoid.
       def collect_animated_tiles
-        below = []
-        above = []
+        found = Array.new(@map.layer_count) { [] }
         each_tile do |layer, col, row, local|
           next unless @tileset.animations.key?(local)
 
-          (@map.above_layer?(layer) ? above : below) << [col, row, local]
+          found[layer] << [col, row, local]
         end
-        [below, above]
+        found
       end
 
-      # Every non-empty tile of every layer, as [layer, col, row, local_id].
       def each_tile
         @map.layer_count.times do |layer|
           @map.height.times do |row|
@@ -115,44 +138,33 @@ module RGame
         end
       end
 
-      # Bakes the static tiles of the layers the block accepts into one
-      # recording, in layer order so a later layer covers an earlier one.
-      def bake(renderer)
+      def bake(renderer, index)
         renderer.record do
           each_tile do |layer, col, row, local|
-            next unless yield(layer)
+            next unless layer == index
             next if @tileset.animations.key?(local)
 
-            renderer.image_at(@tiles[local], col * @map.tile_width, row * @map.tile_height,
-                              z: BELOW_Z)
+            renderer.image_at(@tiles[local], col * @map.tile_width, row * @map.tile_height)
           end
         end
       end
 
-      def draw_animated(renderer, tiles, camera_x, camera_y, viewport_width, viewport_height,
-                        z, elapsed)
+      def draw_animated(renderer, tiles, cull_x, cull_y, cull_width, cull_height, elapsed)
         tile_width = @map.tile_width
         tile_height = @map.tile_height
 
-        # Tiled writes frame durations in milliseconds; everything here counts
-        # in seconds. Converted once per draw rather than once per tile.
         ms = (elapsed * 1000.0).to_i
 
-        # fdiv, not `/`. With two Integers — an integer camera position, which
-        # is entirely ordinary — `/` floors first and the `.ceil` below becomes
-        # a no-op, leaving the last column of tiles undrawn: a one-tile strip of
-        # nothing along the right and bottom edges of the screen, and only when
-        # the camera happens to be on a whole pixel.
-        col_start = camera_x.fdiv(tile_width).floor
-        row_start = camera_y.fdiv(tile_height).floor
-        col_end = (camera_x + viewport_width).fdiv(tile_width).ceil
-        row_end = (camera_y + viewport_height).fdiv(tile_height).ceil
+        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) - camera_x, (row * tile_height) - camera_y, z: z)
+                            col * tile_width, row * tile_height)
         end
       end
     end

data/lib/rgame/core/ui_atlas.rb

@@ -7,11 +7,12 @@ require_relative 'nine_slice'
 
 module RGame
   module Core
-    # One sheet of UI chrome, cut into named nine-slices.
+    # 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
@@ -29,27 +30,38 @@ module RGame
     #       "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 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
+    # `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
     #
-    # `nine_slices` is keyed by whatever the descriptor calls each element, and
+    # 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 in one call.
+    # element of both kinds in one call.
     #
     # Parsing happens once, at load. Nothing here is touched again per frame.
     class UiAtlas
-      # The elements, by name. Values are `NineSlice`s.
+      # 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
@@ -65,19 +77,22 @@ module RGame
         sheet_scale = data[:scale] || 1
 
         @nine_slices = (data[:nine_slices] || {}).to_h do |id, spec|
-          [id, build(image, id, spec, sheet_scale)]
+          [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
 
-      # A descriptor holds many elements, and a mistake in one of them surfaces
-      # from inside NineSlice's arithmetic — "undefined method '-' for nil" says
-      # nothing about *which* button is wrong. Naming the element is the whole
-      # value this wrapper adds, so it catches broadly on purpose.
-      def build(image, id, spec, sheet_scale)
+      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

data/lib/rgame/core.rb

@@ -1,15 +1,8 @@
 # frozen_string_literal: true
 
-# RGame::Core — everything that depends on SDL, OpenGL, or anything built on
-# them. Requiring this file loads those libraries into the process, which is why
-# it is NOT required from lib/rgame.rb; ask for it explicitly:
-#
-#   require "rgame/core"
-#
-# Its counterpart is RGame::Util (see lib/rgame/util.rb), which stays free of
-# graphics dependencies.
 require_relative 'version'
 require_relative 'core/app'
+require_relative 'core/locale'
 require_relative 'core/input'
 require_relative 'core/gamepad'
 require_relative 'core/image'