feat(assets): #81 namespaced spritesheet/atlas API (Sprite.* / Assets.*)

Sprite loading was a bare png_load — one file per 16x16 sprite, no way to load
one sheet and address a cell by grid coords or name. Adds a Sprite.*/Assets.*
runtime (atlas.ludic) over the variable-size image loader, so a cell is a
sub-rect of the kept image and is NOT restricted to the 16x16 sprite table:
Sprite.sheet(path,cw,ch), Sprite.cell(sheet,col,row),
Sprite.cell_span(sheet,col,row,cols,rows) (a sprite may span >1 cell),
Sprite.define/named (name + lookup), Sprite.draw/draw_scaled (through
camera/zoom/clip like Screen.sprite), Sprite.width/height, and
Assets.image/load/get. Spliced on demand (Sprite.sheet/… or Assets.*), so a
program using neither is byte-identical.

Example examples/library/atlas.ludic (verified against a real 12x11 Kenney
sheet, incl. a 2x3 multi-cell span and named lookup). 14 docs pages. Full
suite 114/0, goldens byte-identical, fixpoint holds.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs/language/assets/_section.md

@@ -0,0 +1,7 @@
+---
+id: assets
+title: Assets
+order: 34
+---
+
+Loading and lookup for whole-file assets, paired with the <a href="sprite-sheet"><code>Sprite.*</code></a> atlas API. <a href="assets-image"><code>Assets.image</code></a> (and its alias <a href="assets-load"><code>Assets.load</code></a>) loads a whole image file as one sprite; <a href="assets-get"><code>Assets.get</code></a> looks a named sprite up.

docs/language/assets/assets-get.md

@@ -0,0 +1,14 @@
+---
+id: assets-get
+name: Assets.get
+category: assets
+kind: namespace-method
+tokens: Assets.get
+sig: Assets.get(name) -> int
+tip: Look up a named sprite's id (alias of Sprite.named).
+order: 3
+ns: Assets
+member: get
+---
+
+Alias of <a href="sprite-named"><code>Sprite.named</code></a>: returns the sprite id registered under <code>name</code>, or <code>-1</code>.

docs/language/assets/assets-image.md

@@ -0,0 +1,14 @@
+---
+id: assets-image
+name: Assets.image
+category: assets
+kind: namespace-method
+tokens: Assets.image
+sig: Assets.image(path) -> int
+tip: Load a whole image file as one sprite; returns its id.
+order: 1
+ns: Assets
+member: image
+---
+
+Loads the image at <code>path</code> as a single atlas sprite the size of the image, returning its id — the namespaced replacement for a bare <code>png_load</code>. Draw it with <a href="sprite-draw"><code>Sprite.draw</code></a>.

docs/language/assets/assets-load.md

@@ -0,0 +1,14 @@
+---
+id: assets-load
+name: Assets.load
+category: assets
+kind: namespace-method
+tokens: Assets.load
+sig: Assets.load(path) -> int
+tip: Alias of Assets.image.
+order: 2
+ns: Assets
+member: load
+---
+
+Alias of <a href="assets-image"><code>Assets.image</code></a>: loads a whole image file as one sprite and returns its id.

docs/language/sprite/_section.md

@@ -0,0 +1,7 @@
+---
+id: sprite
+title: Sprite
+order: 33
+---
+
+A namespaced spritesheet / atlas API. <a href="sprite-sheet"><code>Sprite.sheet</code></a> loads one image and remembers its cell grid; <a href="sprite-cell"><code>Sprite.cell</code></a> addresses a cell by grid coords and <a href="sprite-cell_span"><code>Sprite.cell_span</code></a> a sprite that spans more than one cell; <a href="sprite-define"><code>Sprite.define</code></a> / <a href="sprite-named"><code>Sprite.named</code></a> name and look up a cell; <a href="sprite-draw"><code>Sprite.draw</code></a> / <a href="sprite-draw_scaled"><code>Sprite.draw_scaled</code></a> blit it (through the camera / zoom / clip). It stands on the variable-size image loader, so a cell can be any size — not just 16x16. (Distinct from the <code>Sprite</code> engine component of the sprite-render system.)

docs/language/sprite/sprite-cell.md

@@ -0,0 +1,14 @@
+---
+id: sprite-cell
+name: Sprite.cell
+category: sprite
+kind: namespace-method
+tokens: Sprite.cell
+sig: Sprite.cell(sheet, col, row) -> int
+tip: One cell of a sheet, by grid coords; returns a sprite id.
+order: 2
+ns: Sprite
+member: cell
+---
+
+Returns a sprite id for the cell at column <code>col</code>, row <code>row</code> of <code>sheet</code> (the sub-rect <code>(col*cellw, row*cellh, cellw, cellh)</code>). Draw it with <a href="sprite-draw"><code>Sprite.draw</code></a>.

docs/language/sprite/sprite-cell_span.md

@@ -0,0 +1,14 @@
+---
+id: sprite-cell_span
+name: Sprite.cell_span
+category: sprite
+kind: namespace-method
+tokens: Sprite.cell_span
+sig: Sprite.cell_span(sheet, col, row, cols, rows) -> int
+tip: A sprite spanning cols x rows cells (tall/wide art).
+order: 3
+ns: Sprite
+member: cell_span
+---
+
+Returns a sprite id for a sub-rect spanning <code>cols x rows</code> cells from <code>(col, row)</code> — for a sprite that covers more than one cell (a tall character, a wide object). Same as <a href="sprite-cell"><code>Sprite.cell</code></a> but sized to the span.

docs/language/sprite/sprite-define.md

@@ -0,0 +1,14 @@
+---
+id: sprite-define
+name: Sprite.define
+category: sprite
+kind: namespace-method
+tokens: Sprite.define
+sig: Sprite.define(name, sheet, col, row) -> int
+tip: Name a cell for later lookup; returns its sprite id.
+order: 4
+ns: Sprite
+member: define
+---
+
+Creates the cell at <code>(col, row)</code> of <code>sheet</code> and registers it under <code>name</code>, returning its sprite id. Look it up later with <a href="sprite-named"><code>Sprite.named</code></a> — content data (item/tile names) can drive rendering without hard-coded ids.

docs/language/sprite/sprite-draw.md

@@ -0,0 +1,14 @@
+---
+id: sprite-draw
+name: Sprite.draw
+category: sprite
+kind: namespace-method
+tokens: Sprite.draw
+sig: Sprite.draw(id, x, y)
+tip: Blit an atlas sprite at (x, y) through the camera/zoom/clip.
+order: 6
+ns: Sprite
+member: draw
+---
+
+Draws atlas sprite <code>id</code> with its top-left at <code>(x, y)</code>. Sufficiently-opaque pixels are drawn through <code>rt_put_px</code>, so the camera, zoom and clip apply exactly like <a href="screen-sprite"><code>Screen.sprite</code></a>.

docs/language/sprite/sprite-draw_scaled.md

@@ -0,0 +1,14 @@
+---
+id: sprite-draw_scaled
+name: Sprite.draw_scaled
+category: sprite
+kind: namespace-method
+tokens: Sprite.draw_scaled
+sig: Sprite.draw_scaled(id, x, y, scale)
+tip: Blit an atlas sprite scaled by an integer factor.
+order: 7
+ns: Sprite
+member: draw_scaled
+---
+
+Draws atlas sprite <code>id</code> at <code>(x, y)</code> scaled by the integer <code>scale</code> (each source pixel becomes a <code>scale x scale</code> block). For sub-integer / camera zoom, use <a href="camera-zoom"><code>Camera.zoom</code></a> around a plain <a href="sprite-draw"><code>Sprite.draw</code></a>.

docs/language/sprite/sprite-height.md

@@ -0,0 +1,14 @@
+---
+id: sprite-height
+name: Sprite.height
+category: sprite
+kind: namespace-method
+tokens: Sprite.height
+sig: Sprite.height(id) -> int
+tip: The atlas sprite's height in pixels.
+order: 9
+ns: Sprite
+member: height
+---
+
+Returns the pixel height of atlas sprite <code>id</code> (its sub-rect height).

docs/language/sprite/sprite-named.md

@@ -0,0 +1,14 @@
+---
+id: sprite-named
+name: Sprite.named
+category: sprite
+kind: namespace-method
+tokens: Sprite.named
+sig: Sprite.named(name) -> int
+tip: Look up a named sprite's id, or -1.
+order: 5
+ns: Sprite
+member: named
+---
+
+Returns the sprite id registered under <code>name</code> by <a href="sprite-define"><code>Sprite.define</code></a>, or <code>-1</code> if none. Names compare by content.

docs/language/sprite/sprite-sheet.md

@@ -0,0 +1,14 @@
+---
+id: sprite-sheet
+name: Sprite.sheet
+category: sprite
+kind: namespace-method
+tokens: Sprite.sheet
+sig: Sprite.sheet(path, cellw, cellh) -> int
+tip: Load a spritesheet and remember its cell grid; returns a sheet handle.
+order: 1
+ns: Sprite
+member: sheet
+---
+
+Loads the PNG at <code>path</code> and records that its cells are <code>cellw x cellh</code> px, returning a sheet <em>handle</em>. Address its cells with <a href="sprite-cell"><code>Sprite.cell</code></a> / <a href="sprite-cell_span"><code>Sprite.cell_span</code></a>. The whole image is kept (variable size), so cells are not restricted to the 16x16 sprite table.

docs/language/sprite/sprite-width.md

@@ -0,0 +1,14 @@
+---
+id: sprite-width
+name: Sprite.width
+category: sprite
+kind: namespace-method
+tokens: Sprite.width
+sig: Sprite.width(id) -> int
+tip: The atlas sprite's width in pixels.
+order: 8
+ns: Sprite
+member: width
+---
+
+Returns the pixel width of atlas sprite <code>id</code> (its sub-rect width) — handy for centering and layout.