rgame 0.2.0 → 0.3.1

data/lib/rgame/core/asset_manager.rb

@@ -12,7 +12,7 @@ module RGame
     #   app.assets.release(:level1)
     #
     # The built-in types are `image`, `sound`, `song` and `read`, plus the
-    # composites `sheet` and `ui_atlas`. A game or its glue adds more with
+    # composites `sheet` and `ui_atlas`; `glob` lists what is there to load. A game or its glue adds more with
     # {#add_loader}, which is how a tile map gets loaded without Core having to
     # know what one is.
     #
@@ -55,7 +55,6 @@ module RGame
     # `loaders:` is what lets the caching, path resolution and grouping be
     # specced with no window, no GL context and no files at all.
     class AssetManager
-      # Owner of every ungrouped load. Never released, only cleared.
       PERMANENT = :__permanent__
 
       # `app` is what images are loaded into and where the audio device comes
@@ -65,7 +64,7 @@ module RGame
         @app = app
         @loaders = {}
         @cache = {}
-        @owners = {} # cache key => Set of groups holding it
+        @owners = {}
 
         (loaders || default_loaders).each { |type, loader| add_loader(type, &loader) }
       end
@@ -91,9 +90,6 @@ module RGame
       # offering it an id.
       def add_loader(type, &loader)
         @loaders[type] = loader
-        # A singleton method rather than a class-level one: two managers may
-        # know different types, and a game that adds `:tilemap` should not be
-        # teaching it to everyone else's.
         define_singleton_method(type) { |path, group = PERMANENT| leaf(type, path, group) }
         self
       end
@@ -130,10 +126,6 @@ module RGame
       # Takes `group` off every asset's owner set and drops whatever no group
       # still holds.
       def release(group)
-        # Without this, `release(PERMANENT)` would empty every ungrouped
-        # asset's owner set and drop the lot — the exact opposite of what the
-        # constant's name promises, and silent. It is only reachable by naming
-        # the sentinel, so saying what to use instead beats ignoring the call.
         raise ArgumentError, 'ungrouped assets are dropped by #clear, not #release' if group == PERMANENT
 
         @owners.each_value { |groups| groups.delete(group) }
@@ -153,15 +145,23 @@ module RGame
         self
       end
 
+      # The paths under the media root that match `pattern`, relative to the
+      # root and sorted, so what a caller loads from the list — and the order it
+      # merges in — is the same on every platform and file system:
+      #
+      #   assets.glob('locales/**/*.yml')   # => ["locales/de.yml", "locales/en.yml"]
+      #
+      # A directory that does not exist matches nothing, so a game without one
+      # gets `[]` rather than an error. An absolute pattern is used as it
+      # stands, and its matches come back absolute. Nothing is loaded or cached.
+      def glob(pattern) = Dir.glob(pattern, base: File.expand_path(@root)).sort
+
       # How many assets are cached. For tests and for a debug overlay; a game
       # has no reason to ask.
       def size = @cache.size
 
       private
 
-      # The app is reached through the ivar rather than captured, so
-      # `app.audio` is not called until a sound is actually asked for — loading
-      # an image opens no sound device.
       def default_loaders
         {
           image: ->(path) { Image.new(@app, path) },
@@ -175,20 +175,8 @@ module RGame
         fetch(type, path, group) { @loaders.fetch(type).call(resolve(path)) }
       end
 
-      # Where a path actually is on disk.
-      #
-      # `expand_path` rather than `join` for two reasons. An **absolute** path
-      # is used as it stands, which is what lets a loader hand one back — the
-      # tile-map loader gets its tileset image that way, since the path comes
-      # out of a `.tsx` that was itself found on disk. And `'a/./b.png'`,
-      # `'a/../b.png'` and `'b.png'` all land on one cache key rather than
-      # three, so a file cannot be loaded twice by being named twice.
       def resolve(path) = File.expand_path(path, @root)
 
-      # Memoise on miss, then record the owning group — so a cache *hit* under a
-      # new group is tagged too. Tagging after the load rather than before is
-      # what leaves a failed load with no owner behind it, which makes a retry a
-      # clean retry rather than a permanently half-registered asset.
       def fetch(type, path, group)
         key = [type, resolve(path)]
         object = (@cache[key] ||= yield)
@@ -204,17 +192,11 @@ module RGame
         UiAtlas.new(*composite_parts(relative_path, group))
       end
 
-      # The two halves a composite is made of, both through the cache: the
-      # descriptor as a cached `read`, and the image it names as a cached
-      # `image` resolved beside it.
       def composite_parts(relative_path, group)
         data = JSON.parse(read(relative_path, group), symbolize_names: true)
         [image(sibling(relative_path, data[:image]), group), data]
       end
 
-      # A path next to `relative_path`, still relative to the root — so a
-      # descriptor's image lands on the same `[:image, path]` cache key a
-      # standalone `image` of that file would.
       def sibling(relative_path, name)
         directory = File.dirname(relative_path)
         directory == '.' ? name : File.join(directory, name)

data/lib/rgame/core/audio.rb

@@ -19,6 +19,21 @@ module RGame
     # the alternative is a crash at startup for something nobody asked for.
     # `#backend` says which one was chosen.
     class Audio
+      # `assets` is what a path id is resolved through, and may be nil — a
+      # device built by hand plays only what it is handed. `RGame::Core::App`
+      # passes its own manager, so a game never sets this.
+      #
+      # A Ruby `self.new` because the C `initialize` takes no arguments and has
+      # no business knowing what an asset manager is — the same shape
+      # `Renderer.new` uses for the same reason.
+      def self.new(assets: nil)
+        audio = super()
+        audio.assets = assets
+        audio
+      end
+
+      attr_accessor :assets
+
       # Loads a short sound to play over itself. The same thing as
       # `Sample.new(audio, path)`, and the form to prefer: it reads in the
       # direction the objects depend, and it is the form a stand-in device can
@@ -28,15 +43,6 @@ module RGame
       # Loads a long one to stream. See {Song}.
       def song(path) = Song.new(self, path)
 
-      # --- play-by-id -----------------------------------------------------
-      #
-      # The same boundary the renderer's draw-by-id serves: game logic emits
-      # facts — "the ship was hit" — and names the sound, because a scene may
-      # not hold a `Sample`. Registration only, unlike the renderer: a sound id
-      # is whatever a game wants to call it, and there is no per-frame path to
-      # make resolving one worth caching.
-      #
-      #   audio.register_sound(:hit, app.assets.sound('example 09/hurt.ogg'))
       #   audio.play_sound(:hit)
 
       def register_sound(id, sample)
@@ -49,17 +55,17 @@ module RGame
         self
       end
 
-      # Plays a registered sample. Each call is another voice, layered over the
-      # ones already sounding.
+      # Plays a sample by id. Each call is another voice, layered over the ones
+      # already sounding.
       def play_sound(id)
-        samples.fetch(id).play
+        lookup(:sound, id).play
       end
 
-      # Starts a registered song looping, and does **nothing** if it is already
-      # playing — so a scene that re-emits the same request every time it is
-      # entered never restarts the music mid-loop.
+      # Starts a song looping, and does **nothing** if it is already playing —
+      # so a scene that re-emits the same request every time it is entered never
+      # restarts the music mid-loop.
       def play_music(id)
-        song = songs.fetch(id)
+        song = lookup(:song, id)
         return song if song.playing?
 
         @playing_song = song
@@ -81,6 +87,21 @@ module RGame
 
       def samples = @samples ||= {}
       def songs = @songs ||= {}
+
+      def registry(type) = type == :sound ? samples : songs
+
+      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
 
     # A short sound, decoded once and played many times over.

data/lib/rgame/core/font.rb

@@ -34,9 +34,6 @@ module RGame
     # Scripts outside the shipped font's coverage — CJK, Arabic, Hebrew — need
     # their own file. No font of this size covers them.
     class Font
-      # Shipped with the gem, alongside its SIL OFL 1.1 licence. Resolved from
-      # this file's location so it works the same from a checkout and from an
-      # installed gem.
       DEFAULT_PATH = File.expand_path('../fonts/LiberationSans-Regular.ttf', __dir__)
 
       # `path:` is a keyword for callers but positional for the C initialize,

data/lib/rgame/core/locale.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'rgame/core_ext'
+
+module RGame
+  # `RGame::Core.preferred_locales` is C (`ext/rgame_core/app/locale.c`, bound in
+  # `ruby/locale_ext.c`): the user's preferred locales as the operating system
+  # reports them through SDL, most preferred first.
+  #
+  #   RGame::Core.preferred_locales   # => ["de-AT", "en"]
+  #
+  # Each is a language, then a hyphen and a country when the OS names one. The
+  # list is `[]` when the OS names none — on Linux, under `LANG=C`. It needs no
+  # app: SDL reads it without being initialised, so it is a module function
+  # rather than an `App` method.
+  #
+  # What it returns is taken as given. SDL on Linux reads `LANG` and then
+  # `LANGUAGE`, and ignores `LC_ALL`, so the list can repeat a locale; choosing
+  # among them is `RGame::Engine::I18n.choose`, which the glue calls.
+  module Core
+  end
+end

data/lib/rgame/core/nine_slice.rb

@@ -41,10 +41,6 @@ module RGame
       # (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
@@ -69,10 +65,6 @@ module RGame
         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
 
@@ -82,8 +74,6 @@ module RGame
         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)
@@ -92,10 +82,6 @@ module RGame
 
       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)
 
@@ -122,11 +108,6 @@ module RGame
         @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?
 
@@ -139,8 +120,6 @@ module RGame
         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
 

data/lib/rgame/core/renderer.rb

@@ -44,8 +44,9 @@ module RGame
     # 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
     #
@@ -58,22 +59,14 @@ module RGame
 
       Z = RGame::Util::Z
 
-      # Shapes default above sprites, so a debug box or a health bar drawn
-      # without a `z:` lands on top of *that node's* sprite rather than under
-      # it. Well inside one slot, so the defaults order a node's own drawing and
-      # nothing further.
       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, within the same slot.
       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,
@@ -91,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
 
@@ -226,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
@@ -280,9 +254,6 @@ module RGame
         begin
           yield
         ensure
-          # An ensure for the same reason `rotated` has one: a scene that raises
-          # mid-draw would otherwise leave every later node drawing in its
-          # layer, and the frame would come out interleaved with no clue why.
           pop
         end
       end
@@ -347,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
@@ -363,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

@@ -81,8 +81,6 @@ module RGame
         @tileset = map.tileset
         @tiles = tiles
         @animated = collect_animated_tiles
-        # Baked on first draw, not here: recording needs a live frame, and there
-        # is no renderer at construction.
         @static = Array.new(map.layer_count)
       end
 
@@ -102,6 +100,8 @@ module RGame
       # 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})"
@@ -115,10 +115,6 @@ module RGame
 
       private
 
-      # [col, row, local_id] for every animated tile, per layer. 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
         found = Array.new(@map.layer_count) { [] }
         each_tile do |layer, col, row, local|
@@ -129,7 +125,6 @@ module RGame
         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|
@@ -143,9 +138,6 @@ module RGame
         end
       end
 
-      # Bakes one layer's static tiles into a recording. An empty layer bakes an
-      # empty recording, which replays as nothing — so a map with a spacer layer
-      # in it needs no special case here or at the call site.
       def bake(renderer, index)
         renderer.record do
           each_tile do |layer, col, row, local|
@@ -161,15 +153,8 @@ module RGame
         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 = cull_x.fdiv(tile_width).floor
         row_start = cull_y.fdiv(tile_height).floor
         col_end = (cull_x + cull_width).fdiv(tile_width).ceil
@@ -178,8 +163,6 @@ module RGame
         tiles.each do |col, row, local|
           next if col < col_start || col >= col_end || row < row_start || row >= row_end
 
-          # World coordinates, like the baked band above it: the caller's
-          # transform is what puts either on screen.
           renderer.image_at(@tiles[@tileset.frame_local_id(local, ms)],
                             col * tile_width, row * tile_height)
         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'