rgame 0.2.0 → 0.3.1

data/docs/api/values.md

@@ -1,9 +1,12 @@
 # Value types
 
-Everything in `RGame::Util` is a *value*: cheap, comparable, owning no window,
-GPU handle or file. That is what makes them safe for game logic to hold as
-attributes — they load with `require 'rgame'` and pull in no graphics libraries
-at all.
+**Everything in `RGame::Util` is a value**: cheap, comparable, and owning no
+window or GPU handle. Game logic can therefore hold these types as attributes.
+They load with `require 'rgame'` and pull in no graphics library.
+
+`SaveFile` touches the disk, and still belongs here. It holds a *path*, not an
+open handle. It opens a file, reads or writes it, and closes it again. What
+decides the namespace is ownership, not I/O.
 
 ```ruby
 require 'rgame'
@@ -11,8 +14,8 @@ require 'rgame'
 
 ## `RGame::Util::Color`
 
-An RGBA colour. Instances are **frozen** and compare **by value**, so one can be
-shared freely and used as a Hash key.
+`Color` is an RGBA colour. Instances are **frozen** and compare **by value**, so
+you can share one freely and use it as a Hash key.
 
 ```ruby
 Color = RGame::Util::Color
@@ -30,7 +33,18 @@ Color.from_packed(0xFF8000C8)   # 0xRRGGBBAA
 | `==`, `eql?`, `hash` | Value semantics. |
 | `inspect` | `#<RGame::Util::Color r=1 g=2 b=3 a=4>` |
 
-Named colours: `Color::WHITE`, `Color::BLACK`, `Color::TRANSPARENT`.
+### The named palette
+
+```ruby
+Color::WHITE   Color::BLACK   Color::TRANSPARENT
+Color::RED     Color::GREEN   Color::BLUE
+Color::YELLOW  Color::CYAN    Color::MAGENTA
+Color::ORANGE  Color::PURPLE  Color::BROWN     Color::PINK
+Color::GRAY    Color::LIGHT_GRAY               Color::DARK_GRAY
+```
+
+Every named colour except `TRANSPARENT` is opaque. They use the CSS/X11 values,
+so `Color::ORANGE` matches the orange a colour picker gives you.
 
 ### Out-of-range components raise
 
@@ -38,21 +52,22 @@ Named colours: `Color::WHITE`, `Color::BLACK`, `Color::TRANSPARENT`.
 Color.new(300, 0, 0)   # ArgumentError: red must be in 0..255, got 300
 ```
 
-Silently clamping would hide the bug that produced the 300.
+Clamping would hide the bug that produced the 300.
 
 ### `Color.coerce`
 
-Drawing calls accept a colour in several forms, and `coerce` is the single
-place that conversion happens:
+Drawing calls accept a colour in several forms. **`coerce` performs every such
+conversion:**
 
 ```ruby
 Color.coerce(nil)               # => Color::WHITE — an untinted draw
 Color.coerce([255, 128, 0])     # => opaque
 Color.coerce([255, 128, 0, 64]) # => with alpha
-Color.coerce(Color::WHITE)      # => returned unchanged, not copied
+Color.coerce(Color::WHITE)      # => Color::WHITE — the same object, not copied
 ```
 
-Anything else raises `TypeError`; a wrongly-sized array raises `ArgumentError`.
+Any other type raises `TypeError`. An array of the wrong size raises
+`ArgumentError`.
 
 ### Value semantics in practice
 
@@ -65,14 +80,14 @@ a == b            # => true — two objects, one value
 a.frozen?         # => true
 ```
 
-Because a colour is frozen, handing the same one to two sprites is safe: nobody
-can tint it out from under the other.
+A frozen colour is safe to hand to two sprites. Neither can change it under the
+other.
 
 ## `RGame::Util::Tensor`
 
-A fixed-size three-dimensional grid, addressed as `[x, y, z]`. Backed by a
-single flat array in C, so it stays compact for the sizes a tile map or a
-lighting volume needs.
+`Tensor` is a fixed-size three-dimensional grid, addressed as `[x, y, z]`. One
+flat C array backs it, so it stays compact at the sizes a tile map or a lighting
+volume needs.
 
 ```ruby
 grid = RGame::Util::Tensor.new(width, height, depth)
@@ -86,8 +101,8 @@ grid.width             # also #height and #depth
 
 Cells hold any Ruby object. `initial:` is optional and defaults to `nil`.
 
-The layout is x-fastest, then y, then z, so one z-slice is a contiguous run —
-worth knowing if you iterate a layer at a time and care about locality.
+**x varies fastest, then y, then z**, so each z-slice is one contiguous run. For
+good locality, iterate a layer at a time:
 
 ```ruby
 grid.depth.times do |z|
@@ -100,26 +115,123 @@ grid.depth.times do |z|
 end
 ```
 
+## `RGame::Util::SolidGrid`
+
+`SolidGrid` records which cells of a tile grid are solid, one byte per cell, in C.
+**It is the single store of a tile world's solidity.**
+[`TileWorld`](components.md#tileworld) builds one from its map. The blockers that
+stop a walker and the search that plans a route both read it, so they never
+disagree about a wall.
+
+```ruby
+fence = RGame::Util::SolidGrid.build(8, 3) { |col, row| col == 3 && row < 2 }  # asks once per cell, row by row
+fence.solid?(3, 1)     # => true
+fence.solid?(-1, 0)    # => false — outside the grid is open
+fence.width            # => 8 — and #height
+
+field = RGame::Util::SolidGrid.new(8, 3)                                        # every cell open
+field.set_solid(3, 1, true)
+field.set_solid(3, 1, true)
+field.revision         # => 1 — the second write changed nothing
+```
+
+- **`revision` counts changes.** It advances only when `set_solid` changes a
+  cell. Anything derived from the cells can then tell whether it is stale, such
+  as a [`RouteSearch`](#rgameutilroutesearch)'s region labels.
+- **Coordinates are Integers**; anything else raises `TypeError`. An Integer
+  outside the grid, however large, is outside. `solid?` answers `false` there.
+  `set_solid` raises `IndexError`, because a wall written nowhere does not exist.
+- **The size is fixed.** A negative size, or more than `2**31 - 1` cells, raises
+  `ArgumentError`. A zero size gives an empty grid. A grid cannot be `dup`ed,
+  because a search holds on to the grid it was built over.
+- **`SolidGrid.debug_live_grids`** returns how many grids hold cells. rgame's own
+  suite uses it to check that a grid frees its cells.
+
+## `RGame::Util::RouteSearch`
+
+`RouteSearch` finds connected regions and A* routes over a `SolidGrid`, in C.
+Games use [`Engine::NavGrid`](toolbox.md#navgrid--routes-over-a-tile-grid), which
+wraps a `RouteSearch` and states the route rules.
+
+```ruby
+grid = RGame::Util::SolidGrid.build(8, 3) { |col, row| col == 3 && row < 2 }
+search = RGame::Util::RouteSearch.new(grid)
+
+search.find(0, 0, 7, 0)   # => [[0, 0], [1, 1], [2, 2], [3, 2], [4, 2], [5, 1], [6, 0], [7, 0]]
+search.region(0, 0)       # => 0 — nil for a solid cell or one outside the grid
+search.grid               # => the grid — which the search keeps alive
+```
+
+- **It reads its grid and never writes it.** Any number of searches may share a
+  grid. Each sees a change on its next query. It recomputes region labels then,
+  but only if the grid's `revision` moved.
+- **A repeated query allocates nothing but its result.** The search allocates
+  its per-cell buffers once. Its heap grows to the largest query so far and
+  stays there. One search is therefore not safe to use from two threads at once.
+- Coordinates follow `SolidGrid`'s rules. A non-Integer raises `TypeError`, and
+  for a cell outside the grid `find` and `region` return `nil`.
+- **`RouteSearch.debug_live_searches`** returns how many searches hold buffers,
+  for leak checks in rgame's own suite.
+
+## `RGame::Util::TileSweep`
+
+`TileSweep` tests an axis-aligned box against the solid tiles of a `SolidGrid`,
+at a given tile size, in C. Games use
+[`Engine::TileBlockers`](internals.md#tileblockers--the-tile-grid-as-a-blocker-source).
+Every mover that declares `blocked_by: [:tiles]` resolves against it.
+`TileSweep` does the arithmetic underneath, and both of its queries share one
+implementation.
+
+```ruby
+grid = RGame::Util::SolidGrid.build(20, 15) { |col, _row| col == 5 }   # a wall at x 80..96
+sweep = RGame::Util::TileSweep.new(grid, 16, 16)
+
+sweep.resolve_x(58.0, 32.0, 12, 6, 14.0)    # => 68.0 — flush against the wall
+sweep.resolve_y(58.0, 32.0, 12, 6, 4.0)     # => 36.0
+sweep.travel?(10.0, 32.0, 12, 6, 50.0, 0)   # => true
+sweep.travel?(10.0, 32.0, 12, 6, 90.0, 0)   # => false
+sweep.grid                                  # => the grid — which the sweep keeps alive
+```
+
+- **A box is a top-left corner and a size, in pixels.** Results are Floats.
+  Outside the grid is open.
+- **`resolve_x` and `resolve_y`** move the box along one axis. If the box would
+  enter a solid tile, they snap it flush against that tile. They assume a step
+  smaller than a tile.
+- **`travel?`** answers whether the box can move `(dx, dy)` without any resolve
+  stopping it short. It sweeps overlapping half-tile windows a quarter tile
+  apart, resolving each in both axis orders. The answer holds for a walker that
+  steps less than a quarter tile at a time.
+- **It reads its grid and never writes it**, so the next call sees a
+  `set_solid`. No query allocates.
+- **Refusals.** A tile size that is not positive and finite raises
+  `ArgumentError`. So does a travel too long to sweep, beyond `2**31 - 1`
+  windows. A coordinate that is not a number raises `TypeError`. A non-finite
+  coordinate raises `FloatDomainError`, except in a resolve that does not move:
+  that returns the box where it is.
+- **`TileSweep.debug_live_sweeps`** returns how many sweeps are allocated, for
+  leak checks in rgame's own suite.
+
 ## `RGame::Util::Z`
 
-The vocabulary of draw order: which band a thing is drawn in, and the arithmetic
-that turns a band plus a position in the tree into the single number the renderer
-sorts a frame by.
+`Z` is the vocabulary of draw order. It names the bands, and turns a band plus a
+position in the tree into the single number the renderer sorts by.
 
 ```ruby
 RGame::Util::Z::BANDS     # => [:world, :hud, :overlay, :debug]
 RGame::Util::Z::DEFAULT   # => :world
-RGame::Util::Z::Z_MIN     # => -512, the smallest `z:` a drawing call may pass
+RGame::Util::Z::Z_MIN     # => -512 — the smallest `z:` a drawing call may pass
 RGame::Util::Z::Z_MAX     # =>  511
+RGame::Util::Z.band?(:hud) # => true
 ```
 
-It lives here for the same reason [`Controls`](input.md) does: both the scene
-graph (which decides a node's band) and the renderer (which turns one into a z)
-have to name it, and neither may name the other's layer.
+It lives in `Util` for the same reason as [`Controls`](input.md). The scene
+graph decides a node's band and the renderer turns it into a z. Both must name
+`Z`, and neither may name the other's layer.
 
-Games rarely touch it. What a game writes is a node's `z` and, occasionally, a
-`band:` — see [the scene graph](scene_graph.md#draw-order). What it buys is that
-`z` numbers cannot leak between nodes and bands cannot leak into each other:
+**Games rarely touch `Z`.** A game sets a node's `z` and, occasionally, a
+`band:`; see [the scene graph](scene_graph.md#draw-order). `Z` guarantees that `z`
+numbers cannot leak between nodes, and bands cannot leak into each other:
 
 | | |
 |---|---|
@@ -127,7 +239,78 @@ Games rarely touch it. What a game writes is a node's `z` and, occasionally, a
 | `Z_MIN`…`Z_MAX` | what a `z:` on a drawing call may be; anything else raises |
 | `STRIDE` | `2**40` — the gap between bands, which no `z:` can cross |
 
-Every value is an integer below `2**42`, and the `double` the draw queue sorts on
-is exact below `2**53`, so two different slots can never compare equal by
-rounding — which would show up as two sprites swapping places between frames, and
-would be very hard to recognise as a precision problem.
+Every value is an integer below `2**42`. The draw queue sorts on a `double`, which
+is exact below `2**53`. Two different slots therefore never round to the same
+key. If they did, two sprites would swap places between frames, and nobody would
+suspect a precision problem.
+
+## `RGame::Util::SaveFile`
+
+`SaveFile` stores a game's saved state as one JSON file.
+
+```ruby
+save = RGame::Util::SaveFile.new('slot1.json', game: 'sheepdog')
+
+save.write(dog: [120, 80], sheep: [[40, 40], [90, 30]])
+save.read      # => { dog: [120, 80], sheep: [[40, 40], [90, 30]] }
+save.exist?    # => true
+save.delete
+```
+
+`SaveFile.new(name, game: 'rgame', dir: nil)` places `name` in
+`SaveFile.directory(game)`, or in `dir:` when given. `path` returns the full path.
+`delete` does nothing when the file is already gone.
+
+Keys come back as Symbols, so a game writes and reads one shape. JSON comes from
+the standard library, so `SaveFile` adds no runtime dependency.
+
+### Reading never raises
+
+**`read` returns its default for any file it cannot use.** The default is `{}`,
+or whatever you pass. That covers a file that is missing, empty, truncated, not
+JSON, or JSON that is not an object. A directory in the way and an unreadable
+file get the same answer.
+
+This is why to prefer `SaveFile` over `JSON.parse(File.read(path))`. A save file
+is the one input a game did not produce this run. It survives crashes, full
+disks, killed processes, text editors, and copies from other machines. A game
+that raises on any of those cannot start again. The player's only remedy is to
+find and delete a file nobody told them about. Losing a save is bad; refusing to
+launch is worse.
+
+**Writing still raises.** A failed read has a sensible answer: "there is no
+save". A failed write has none. Discarding progress without a word gets noticed
+hours later, when the progress is gone.
+
+### Writing is atomic
+
+**`write` never leaves half a save.** It writes a temporary file beside the
+target and renames it over the top. `File.rename` within one directory is atomic
+on every platform the engine supports. A save is either the old one or the new
+one.
+
+A game most wants to save on the way out, which is also when it is most likely
+to be killed. A plain `File.write` truncates first and fills in after. A crash in
+between leaves a zero-byte file where the afternoon's progress was.
+
+### Where saves go
+
+`SaveFile.directory(game)` follows each platform's convention instead of
+dropping a dotfile in the home directory:
+
+| | |
+|---|---|
+| Linux | `$XDG_DATA_HOME/<game>`, or `~/.local/share/<game>` |
+| macOS | `~/Library/Application Support/<game>` |
+| Windows | `%APPDATA%\<game>` |
+
+Pass `dir:` to store the file somewhere else. Specs do this.
+
+### What it does not do
+
+**`SaveFile` does not serialize a scene tree, and a game should not either.** A
+scene is a recipe; a save file is state. The scene rebuilds itself identically
+every run, and the save supplies the few facts that differ. `examples/save_load`
+shows the pattern, matching objects back up without naming any node.
+`examples/save_load_ids` shows the case that needs names, using
+[`Components::Identity`](components.md#identity).

data/examples/assets/README.md

@@ -0,0 +1,322 @@
+# Example assets
+
+Everything the examples draw and play. Fifteen files besides this one, about
+124 KB in total — of which the music is 93 KB, and the reason for `tools/shrink_ogg.c`.
+
+## Why these files and not the ones in `media/`
+
+`media/` is gitignored because its contents cannot be redistributed. These can:
+**this directory ships inside the gem**, so every `gem install rgame`
+redistributes each file below to somebody else. That is the test any asset here
+has to pass — not "may I use it in my game" but *"may I hand copies of it to
+everyone who installs this library"* — and it is why the rule is CC0 or
+authored here, with nothing in between. A licence that merely permits use, or
+asks for a credit line, would attach an obligation to rgame and to everyone
+downstream of it.
+
+CC0 waives copyright entirely, so none of the sources below require a licence
+file to be shipped alongside them or a credit to be given. This README is
+recorded anyway: provenance is the thing that becomes impossible to reconstruct
+later, and "where did this PNG come from" is not a question anyone should have
+to answer from memory.
+
+## The files
+
+### `tileset.png` — Kenney, *Tiny Town*
+
+- Source: <https://kenney.nl/assets/tiny-town>
+- Licence: CC0 1.0 (stated on the page and in the `License.txt` inside the
+  download)
+- Modification: none. This is `Tilemap/tilemap_packed.png` from the pack,
+  copied unchanged.
+
+16x16 tiles, 12 columns x 11 rows = 132 tiles, 192x176 pixels. Kenney asks for
+a credit but does not require one; the licence is CC0 either way.
+
+### `tileset.tsx` — ours
+
+A Tiled tileset over `tileset.png`. Written here rather than taken from the
+pack, because the pack has no Tiled metadata and because **collision lives in
+this file**: `RGame::Engine::Tileset` treats a tile as solid when it carries an
+`<objectgroup>` with at least one object, which is what Tiled's per-tile
+collision editor writes. There is no solid-tile list in code to fall back on, so
+a tile with no shape here is walkable no matter what it looks like.
+
+Solid tiles are the trees and the fence pieces: **3, 4, 5, 15, 16, 27, 28** and
+**44, 45, 46, 47**. Everything else — grass, sand, mushrooms, plants, buildings,
+items — is walkable. That is a deliberate floor rather than an inventory: the
+examples only need vegetation and fences to be obstacles, and marking a tile
+solid that no example places is a claim nothing checks. Add shapes in Tiled as
+new examples need them.
+
+### `town.tmx` — ours
+
+60x40 tiles = 960x640 pixels, deliberately larger than the 640x480 window on
+both axes so a camera has somewhere to scroll. Two layers, `ground` (entirely
+walkable) and `obstacles` (a tree border, a fence across the middle, scattered
+trees).
+
+Layer data is **base64 + zlib**, which is what `RGame::Engine::TileMap.parse`
+reads — it inflates the layer and unpacks little-endian `uint32` gids. CSV will
+not load. Tiled writes this format when the layer format is set to "Base64
+(zlib compressed)"; keep it that way when editing.
+
+The fence has exactly one gap, at x=12..14, far west of both clearings. The
+placement is the point, and it took two tries to get right:
+
+- **A gap between the start and the goal is not an obstacle.** With the gap at
+  x=29..31 the shortest route cost exactly the straight-line distance — 55 steps
+  against a 55-step Manhattan distance — so a pathfinder would have drawn what
+  looks like a straight line. Out west, the same trip is 84 steps against 22,
+  and the walker has to head *away* from its goal to get through.
+- **A fence has to span the whole interior.** Stopping it a tile short of the
+  border left a second gap nobody planned, at x=58, and the route quietly used
+  that one instead. It now runs x=1..58, and the fence row is solid everywhere
+  except the three gap tiles.
+
+### `ui.png` + `ui.json` — Kenney, *UI Pack - Pixel Adventure*
+
+- Source: <https://kenney.nl/assets/ui-pack-pixel-adventure>
+- Licence: CC0 1.0 (stated on the page and in the `License.txt` inside the
+  download)
+- Modification: five 32x32 tiles were cut out of
+  `Tilesheets/Large tiles/Thick outline/tilemap_packed.png` and laid side by
+  side. The pixels are untouched; only the sheet is ours.
+
+The pack is 91 tiles and we use five, so shipping the strip rather than the
+sheet keeps this to 1 KB and makes the descriptor readable — each element is at
+a round multiple of 32.
+
+**This is not optional chrome.** `RGame::Engine::UI::PanelButton` draws its
+background with `renderer.nine_slice`, and a nine-slice id is resolved by
+*registration* only — it names an element of an atlas, never a file — so
+`UI::Menu` cannot draw at all without one of these registered. Which elements
+are needed is not our choice either: `PanelButton::STYLE` names `button_idle`,
+`button_focus`, `button_pressed` and `button_disabled`, and a menu draws each of
+them when an item reaches that state.
+
+Two things constrained which tiles could be used, both discovered by looking:
+
+- **Several of the pack's panels are frames with transparent middles.** They
+  read as solid panels on the sheet's dark background and then show the world
+  through them. The five here are all filled.
+- **`PanelButton`'s label colour defaults to** a dark brown, with a muted grey
+  for a disabled item, so with the default the buttons have to be *light* or the
+  label disappears into them. `label_color:` changes it.
+
+`border` is 8 for every element: the largest decorated frame in the set is 8
+pixels, the interiors are flat, and a uniform value keeps a button's inner
+geometry from shifting as it changes state.
+
+### `hero.png` + `hero.json` — sodri's *Character 4 directional walking*, repacked
+
+- Source: <https://opengameart.org/content/character-4-directional-walking>
+- Author: sodri
+- Licence: CC0
+- Modifications, both ours: the white background was keyed out, and the four
+  separate strips were repacked into one uniform sheet.
+
+The original is four PNGs — `walk_down`/`walk_up` at 14x22 per frame,
+`walk_left`/`walk_right` at 13x22 — fully opaque, with a pure white background.
+Two things had to change before `RGame::Core::SpriteSheet` could read it:
+
+- **Transparency.** Pure white was replaced with alpha 0. Checked first rather
+  than assumed: flood-filling from the borders showed white is only ever
+  background — the handful of enclosed white pixels are the gaps between arm and
+  torso — and the art uses 7 to 9 colours with no near-white among them, so a
+  flat colour key cannot eat anything intended.
+- **A uniform grid.** A sheet is one fixed cell size, so each frame was centred
+  horizontally in a 16x22 cell (`(16 - w) // 2`, so the 13px-wide side frames
+  sit one pixel left of true centre — half a pixel of asymmetry between facings,
+  which nothing can see).
+
+`walk_left` is not in the sheet. Every left frame is a pixel-exact mirror of its
+right counterpart — verified frame by frame, not assumed — so the descriptor
+reuses row 2 with `"flip_x": true` and the sheet is three rows instead of four.
+
+Layout, 6 columns x 3 rows of 16x22:
+
+| Row | Animation |
+|---|---|
+| 0 | `walk_down`, and `stand` is its first column |
+| 1 | `walk_up` |
+| 2 | `walk_right`, and `walk_left` mirrored |
+
+There is no idle art in the original, so `stand` is a single frame off the walk
+cycle rather than an animation of its own.
+
+### `glyphs.png` + `glyphs.json` — Kenney, *Input Prompts*, repacked
+
+- Source: <https://kenney.nl/assets/input-prompts>
+- Licence: CC0 1.0 (stated on the page and in the `License.txt` inside the
+  download)
+- Modification: five 64x64 PNGs were laid side by side into one strip. The
+  pixels are untouched; only the sheet and the descriptor are ours.
+
+The pack is thousands of files across seventeen controller families, and
+`examples/input_glyphs` names five buttons, so the strip is 3 KB where the
+download is 5 MB.
+
+Layout, 5 columns x 1 row of 64x64, and **the order is the example's table**:
+`GLYPH_COLUMN` in `examples/input_glyphs/main.rb` maps a `Controls` button id to
+a column here.
+
+| Column | Button id | From the pack |
+|---|---|---|
+| 0 | `KEY_SPACE` | `Keyboard & Mouse/Default/keyboard_space.png` |
+| 1 | `KEY_RETURN` | `Keyboard & Mouse/Default/keyboard_enter.png` |
+| 2 | `KEY_ESCAPE` | `Keyboard & Mouse/Default/keyboard_escape.png` |
+| 3 | `PAD_A` | `Xbox Series/Default/xbox_button_color_a.png` |
+| 4 | `PAD_B` | `Xbox Series/Default/xbox_button_color_b.png` |
+
+**Xbox rather than PlayStation or Switch**, because SDL's button names are
+Xbox's — `PAD_A` is SDL's A — and a sheet whose faces disagree with the ids
+would make every prompt a translation. A game that wants the pad in the player's
+actual hands ships a second sheet per family and picks a table; the ids do not
+change, only the pictures.
+
+The keyboard glyphs are light and the pad glyphs are the pack's colour versions,
+so both need a dark panel under them — which is what `examples/input_glyphs`
+draws.
+
+### `icons.png` + `icons.json` — Kenney, *Game Icons*, repacked
+
+- Source: <https://kenney.nl/assets/game-icons>, mirrored with the same licence
+  at <https://opengameart.org/content/game-icons>
+- Licence: CC0 1.0 (stated on the page and in the `license.txt` inside the
+  download)
+- Modification: eight 50x50 PNGs were laid side by side into one strip. The
+  pixels are untouched; only the sheet and the descriptor are ours.
+
+Layout, 8 columns x 1 row of 50x50, named in the descriptor's `images` section
+in `snake_case`:
+
+| Column | Name | From the pack |
+|---|---|---|
+| 0 | `home` | `PNG/White/1x/home.png` |
+| 1 | `gear` | `PNG/White/1x/gear.png` |
+| 2 | `save` | `PNG/White/1x/save.png` |
+| 3 | `star` | `PNG/White/1x/star.png` |
+| 4 | `trophy` | `PNG/White/1x/trophy.png` |
+| 5 | `audio_on` | `PNG/White/1x/audioOn.png` |
+| 6 | `music_on` | `PNG/White/1x/musicOn.png` |
+| 7 | `locked` | `PNG/White/1x/locked.png` |
+
+**White, because a tint is a multiply.** The white variant is RGB 255 with the
+shape in alpha only, so `renderer.image(..., color:)` — and `UI::IconButton`'s
+per-state tints — colour it exactly; the black variant would stay black under
+any tint.
+
+**1x, because images sample nearest-neighbour.** A 50-pixel icon in
+`examples/radial_menu`'s 64-pixel slots draws at scale 1 and the chosen one in
+the middle at scale 2, both whole numbers; a 2x icon would need scale 0.5 or
+thereabouts, which drops pixel rows unevenly.
+
+**A strip, because the separate files carry metadata.** Each PNG in the pack
+holds Adobe XMP, so the eight files are 121 KB; the strip is 2 KB. It is a UI
+atlas rather than a sprite sheet so the icons are cut and registered by name —
+`renderer.register_ui_atlas(game.assets.ui_atlas('icons.json'))` makes
+`UI::IconButton.new(image: :home)` draw.
+
+### `skills.png` + `skills.json` — Kenney, *Cursor Pack*, repacked
+
+- Source: <https://kenney.nl/assets/cursor-pack>, version 1.1
+- Licence: CC0 1.0 (the `License.txt` inside the download reads "License:
+  (Creative Commons Zero, CC0)")
+- Modification: five 64x64 PNGs were laid side by side into one strip and saved
+  as RGBA. The pixels are untouched; only the sheet and the descriptor are ours.
+
+Layout, 5 columns x 1 row of 64x64, named in the descriptor's `images` section
+in `snake_case`:
+
+| Column | Name | From the pack |
+|---|---|---|
+| 0 | `wand` | `PNG/Basic/Double/tool_wand.png` |
+| 1 | `wrench` | `PNG/Basic/Double/tool_wrench.png` |
+| 2 | `torch` | `PNG/Basic/Double/tool_torch.png` |
+| 3 | `hammer` | `PNG/Basic/Double/tool_hammer.png` |
+| 4 | `watering_can` | `PNG/Basic/Double/tool_watering_can.png` |
+
+`torch` is the pack's flashlight, named for the British word. The pack has
+`tool_hoe`, `tool_shovel`, `tool_axe` and `tool_pickaxe` in the same styles, if
+the bar ever wants more.
+
+**`Basic`, not `Outline`.** Both were drawn on `examples/skill_bar`'s discs in
+all four states. `Basic` is a light-grey silhouette with no border, so a tint
+colours all of it: grey at rest, white focused, dim disabled, dark on the gold
+pressed disc. `Outline` adds a black border, which a multiply leaves black —
+a disabled tool barely dims, and a pressed one is a dark shape on gold with its
+edges lost.
+
+**`Double` (64 pixels), not `Default` (32).** The glyph sits in about half its
+square, so a 32-pixel cursor on an 80-pixel disc is a thumbnail. Either draws at
+scale 1, which nearest-neighbour sampling needs.
+
+**One pack per atlas.** These are not in `icons.png` so that each file's
+provenance stays one paragraph; one more `register_ui_atlas` call is the whole
+cost.
+
+### `blip.ogg` — Kenney, *Interface Sounds*
+
+- Source: <https://kenney.nl/assets/interface-sounds>
+- Licence: CC0 1.0 (stated on the page and in the `License.txt` inside the
+  download)
+- Modification: none. This is `Audio/click_001.ogg` from the pack, renamed.
+
+4.8 KB. The pack has 100 of these, 4 to 29 KB each, so if an example ever wants
+a second sound it costs nothing to take another.
+
+### `music.ogg` — hernandack's *Short Loops Background Music Pack*, re-encoded
+
+- Source: <https://opengameart.org/content/short-loops-background-music-pack>
+- Author: hernandack
+- Licence: CC0
+- Modification: the track *Just Saying Tho* downmixed to mono and re-encoded at
+  Vorbis quality -0.1, with `tools/shrink_ogg.c`. **The length is unchanged.**
+
+24.05 seconds, 93 KB, down from 388 KB. The original is stereo, 44.1 kHz,
+~128 kbps — encoded for listening rather than for a library gem — and mono at a
+low quality setting is background music in a teaching example.
+
+**Length was deliberately not touched.** A seamless loop is seamless at exactly
+its own length, because the author arranged for the end to lead back into the
+start. Trimming it to save more bytes would put a seam in the middle of the one
+property the file is shipped to demonstrate.
+
+#### Why this is the second track here
+
+The first one shipped was *A Brand New Wisdom* from the same pack, chosen on a
+seam measurement of 2.6% — and it loops audibly badly, because **it ends with
+0.79 seconds of silence.** The wrap has no click. It has a *gap*.
+
+That is a hole in the measurement, not bad luck. A seam figure asks "does the
+last sample join smoothly onto the first", and silence joins onto silence
+perfectly. Fading out to nothing is the ordinary way to end a piece of music and
+the ordinary way to ruin a loop, and the number said 0.7% the whole time.
+
+`tools/shrink_ogg.c` now reports both, and the whole pack looks different under
+the second one:
+
+| track | seam | tail silence | |
+|---|---|---|---|
+| A Brand New Wisdom | 2.6% | **0.79s** | shipped first, wrong |
+| Swinging Sweet | 4.5% | **1.48s** | worse |
+| Winter Dust | 34.9% | 0.00s | no gap, bad seam |
+| **Just Saying Tho** | 2.8% | **0.00s** | shipped now |
+| 8BitBattleLoop (other pack) | 0.0% | 0.01s | cleanest, but 108 KB and chiptune |
+
+Measured back off the shipped file: seam 2.3%, no silence at either end.
+
+**A loop wants both numbers.** A small seam alone is not evidence.
+
+## Adding an asset here
+
+1. CC0, or drawn in this repo. If the licence says anything about redistribution
+   at all, it does not go here — see the top of this file.
+2. Record it above: source URL, author, licence, and every modification made.
+3. **Audio is Ogg Vorbis or WAV, and nothing else.** MP3 and FLAC are compiled
+   out of miniaudio (`ext/rgame_core/vendor/miniaudio_impl.c`), so a file that
+   plays in every desktop player can still fail to load here.
+4. No leading dots in filenames. `Dir.glob` does not match them, so the gemspec
+   would silently leave the file out of the gem while the checkout kept working
+   — `spec/packaging_spec.rb` has an example that catches it.

data/examples/assets/glyphs.json

@@ -0,0 +1,5 @@
+{
+  "image": "glyphs.png",
+  "frame_width": 64,
+  "frame_height": 64
+}

data/examples/assets/hero.json

@@ -0,0 +1,12 @@
+{
+  "image": "hero.png",
+  "frame_width": 16,
+  "frame_height": 22,
+  "animations": {
+    "stand":      { "row": 0, "col": 0, "frames": 1, "fps": 1 },
+    "walk_down":  { "row": 0, "frames": 6, "fps": 8 },
+    "walk_up":    { "row": 1, "frames": 6, "fps": 8 },
+    "walk_right": { "row": 2, "frames": 6, "fps": 8 },
+    "walk_left":  { "row": 2, "frames": 6, "fps": 8, "flip_x": true }
+  }
+}