@raskell/wasm-ad 0.1.0 → 0.3.0

package/README.md

@@ -1,8 +1,9 @@
 # WASM-AD for AssemblyScript
 
 An AssemblyScript SDK for [WASM-AD](https://github.com/raskell-io/wasm-ad) carts: register
-addresses, typed builders for backgrounds, sprites and affine matrices, input, save RAM and
-`trace`, with no runtime allocation and no mutable globals.
+addresses, typed builders for backgrounds (tiled and affine), sprites, affine matrices and
+sound, input for up to four players, save RAM and `trace`, with no runtime allocation and no
+mutable globals.
 
 ## The starter cart
 
@@ -12,8 +13,10 @@ npm run build            # build/starter.wasm
 node ../../tools/wasmad.mjs check build/starter.wasm
 ```
 
-[`examples/starter.ts`](examples/starter.ts) is the same cart as every other SDK's starter
-and renders bit-identical frames. Drop `build/starter.wasm` into the player.
+[`examples/starter.ts`](examples/starter.ts) is the same cart as every other SDK's starter: a
+rotating affine checkerboard, a spinning star, a second star for player 2 when a second
+controller connects, and a little tune on every sound channel, with bit-identical frames and
+sound. Drop `build/starter.wasm` into the player.
 
 ## A new cart
 
@@ -72,7 +75,59 @@ export function start(): void {
 ```
 
 `const` values are fine. Avoid `new`, string concatenation, arrays and anything else that
-allocates; use `memory.data` for static buffers.
+allocates; use `memory.data` for static buffers and tables, e.g.
+`const NOTES = memory.data<u32>([262, 330, 392])` read with `load<u32>(NOTES + (i << 2))`.
+
+## Sound
+
+`sound.enable()` turns sound on with every channel on both sides. A channel plays when its
+start bit is written; the host clears it after the frame (SPEC.md §14):
+
+```ts
+write16(reg.SOUND2CNT_L, sound.DUTY_50 | sound.envelope(12, 2, false));
+write16(reg.SOUND2CNT_H, sound.START | sound.rate(440));
+```
+
+Sample channels play signed 8-bit samples you write to `sound.sampleRam()`:
+`pcm.play(0, offset, length, 16000, 64)`.
+
+## Affine backgrounds
+
+In modes 1 and 2, BG2 (and BG3 in mode 2) is drawn through a matrix. Its tiles are 8bpp
+(`bgTile8`) and its map is one byte per tile (`affineMap`). `setBgAffine(2, m, tx, ty, sx, sy)`
+puts texture pixel (tx, ty) at screen pixel (sx, sy) and rotates and scales around it.
+
+## Players
+
+`KEYS` is player 1; players 2–4 read `KEYS2`–`KEYS4`, and `PADS` says which players have a
+controller (SPEC.md §5). `buttons` keeps edge detection for each player:
+
+```ts
+if (connected(2)) {
+  buttons.update(2);
+  if (buttons.pressed(key.A, 2)) jump(2);
+}
+```
+
+## Icons
+
+A cart can carry a 32×32 icon that hosts show next to its title (SPEC.md §2.5). Draw a PNG
+with at most 15 colors plus transparency and add it after building:
+
+```sh
+npx wasmad icon cart.wasm icon.png
+```
+
+## Replays and save states
+
+A cart is deterministic, so `wasmad` can record a run and play it back, or save and resume it
+(FORMATS.md in the repository):
+
+```sh
+npx wasmad run cart.wasm --frames 600 --keys 0-59:right --record run.wadreplay
+npx wasmad run cart.wasm --replay run.wadreplay --save-state end.wadstate
+npx wasmad run cart.wasm --state end.wadstate --frames 60 --ppm frame.ppm
+```
 
 ## API
 
@@ -83,16 +138,21 @@ All values are plain integers; builders take a value and return a new one.
 | `read16`, `write16`, `read32`, `write32` | Raw register access, e.g. `write16(reg.DISPCNT, dispcnt.MODE0 \| dispcnt.BG0)` |
 | `reg.*`, `reg.BGCNT(i)`, `reg.BGHOFS(i)`, `reg.BGVOFS(i)` | Register addresses by their SPEC.md names |
 | `dispcnt`, `layer`, `blend`, `key` | Bit constants; `blend.cnt(effect, first, second)`, `blend.alpha(eva, evb)` |
-| `bgcnt.priority/charBlock/screenBlock/size/bpp8/mosaic` | `BGxCNT` builders |
+| `bgcnt.priority/charBlock/screenBlock/size/bpp8/mosaic/affineSize/wrap` | `BGxCNT` builders |
 | `rgb(r, g, b)` | 8-bit channels to RGB555 |
 | `setBgColor(i, c)`, `setObjColor(i, c)` | Palette RAM |
 | `bgTile(block, i)`, `objTile(i)`, `fillTile(addr, byte)` | Addresses of 32-byte 4bpp tiles |
 | `screenBlock(b)`, `setScreenEntry(b, i, e)`, `screenEntry.make/hflip/vflip` | Background maps |
+| `bgTile8(block, i)`, `affineMap(b)`, `setBgAffine(bg, m, tx, ty, sx, sy)` | Affine backgrounds (modes 1 and 2) |
 | `sprite.make(x, y, SpriteSize.S16x16, tile)` then `.bank/.priority/.hflip/.vflip/.semiTransparent/.window/.mosaic/.bpp8/.affine` | Sprites, packed in a `u64` |
 | `oam.set(i, s)`, `oam.hide(i)`, `oam.hideAll()`, `oam.setAffine(slot, m)` | OAM |
 | `affine.rotateScaleFixed(angle, sx, sy)`, `affine.IDENTITY`, `affine.make` | Affine matrices; angle in 1/256 turns, scale in 8.8 |
 | `fixed.sin(a)`, `fixed.cos(a)` | Q14 trigonometry, identical in every SDK |
-| `buttons.update()`, `buttons.held(k)`, `buttons.pressed(k)`, `keys()` | Input |
+| `buttons.update(player?)`, `buttons.held(k, player?)`, `buttons.pressed(k, player?)`, `keys()` | Input; `player` 1–4, default 1 |
+| `keysOf(player)`, `pads()`, `connected(player)` | Players 1–4 (SPEC.md §5) |
 | `frame()`, `seed()` | Time and the only entropy source |
 | `saveRam()`, `saveRestored()`, `requestSave()` | 32 KB of save RAM at 0x19000 |
+| `sound.enable/disable`, `sound.rate(hz)`, `sound.sweep/envelope/length/noise`, `sound.START/LENGTH/DUTY_*/WAVE_*` | Sound channels 1–4, through `reg.SOUND*` |
+| `sound.waveRam()`, `sound.sampleRam()`, `sound.status()` | Wave RAM, sample RAM, which channels are playing |
+| `pcm.play(ch, start, len, rate, vol)`, `pcm.playLooped`, `pcm.stop`, `pcm.position`, `pcm.playing` | Sample channels A (0) and B (1) |
 | `trace(msg)` | UTF-8 to the host's debug log (at most 1 KB) |

package/assembly/index.ts

@@ -27,13 +27,18 @@ export const VRAM_SIZE: usize = 0x18000;
 export const OBJ_VRAM: usize = VRAM + 0x10000;
 export const SAVE: usize = 0x19000;
 export const SAVE_SIZE: usize = 0x8000;
+/** Sample RAM: signed 8-bit samples for the sample channels (SPEC.md §14.6). */
+export const SAMPLE_RAM: usize = 0x21000;
+export const SAMPLE_RAM_SIZE: usize = 0x7000;
+/** Wave RAM: two banks of 16 bytes (SPEC.md §14.5). */
+export const WAVE_RAM: usize = 0x490;
 /** First address the cart may use for its own data, stack and heap. */
 export const CART: usize = 0x28000;
 /** OAM attribute 0 that hides a sprite. */
 export const OBJ_HIDDEN: u16 = 0x0200;
-export const SPEC_VERSION: u16 = 0x0001;
+export const SPEC_VERSION: u16 = 0x0003;
 
-// ---- Registers (SPEC.md §5, §6) ---------------------------------------------
+// ---- Registers (SPEC.md §5, §6, §14) ----------------------------------------
 
 /** Every register address, by its SPEC.md name. Use with `read16`/`write16`. */
 export namespace reg {
@@ -55,6 +60,51 @@ export namespace reg {
   export const SAVECNT: usize = 0x70c;
   export const SAVESTAT: usize = 0x70e;
   export const SPEC: usize = 0x710;
+  export const KEYS2: usize = 0x712;
+  export const KEYS3: usize = 0x714;
+  export const KEYS4: usize = 0x716;
+  /** Bits 0–3: players 1–4 have a controller. */
+  export const PADS: usize = 0x718;
+
+  export const BG2PA: usize = 0x420;
+  export const BG2PB: usize = 0x422;
+  export const BG2PC: usize = 0x424;
+  export const BG2PD: usize = 0x426;
+  export const BG2X: usize = 0x428; // u32
+  export const BG2Y: usize = 0x42c; // u32
+  export const BG3PA: usize = 0x430;
+  export const BG3PB: usize = 0x432;
+  export const BG3PC: usize = 0x434;
+  export const BG3PD: usize = 0x436;
+  export const BG3X: usize = 0x438; // u32
+  export const BG3Y: usize = 0x43c; // u32
+
+  export const SOUND1CNT_L: usize = 0x460;
+  export const SOUND1CNT_H: usize = 0x462;
+  export const SOUND1CNT_X: usize = 0x464;
+  export const SOUND2CNT_L: usize = 0x468;
+  export const SOUND2CNT_H: usize = 0x46c;
+  export const SOUND3CNT_L: usize = 0x470;
+  export const SOUND3CNT_H: usize = 0x472;
+  export const SOUND3CNT_X: usize = 0x474;
+  export const SOUND4CNT_L: usize = 0x478;
+  export const SOUND4CNT_H: usize = 0x47c;
+  export const SOUNDCNT_L: usize = 0x480;
+  export const SOUNDCNT_H: usize = 0x482;
+  export const SOUNDCNT_X: usize = 0x484;
+
+  export const PCMA_SAD: usize = 0x4b0;
+  export const PCMA_LEN: usize = 0x4b2;
+  export const PCMA_LOOP: usize = 0x4b4;
+  export const PCMA_RATE: usize = 0x4b6;
+  export const PCMA_CNT: usize = 0x4b8;
+  export const PCMA_POS: usize = 0x4ba;
+  export const PCMB_SAD: usize = 0x4c0;
+  export const PCMB_LEN: usize = 0x4c2;
+  export const PCMB_LOOP: usize = 0x4c4;
+  export const PCMB_RATE: usize = 0x4c6;
+  export const PCMB_CNT: usize = 0x4c8;
+  export const PCMB_POS: usize = 0x4ca;
 
   /** `BGxCNT` for background 0–3. */
   // @ts-ignore: decorator
@@ -93,6 +143,10 @@ export namespace reg {
 /** `DISPCNT` bits (SPEC.md §6.1). */
 export namespace dispcnt {
   export const MODE0: u16 = 0;
+  /** BG0 and BG1 tiled, BG2 affine. */
+  export const MODE1: u16 = 1;
+  /** BG2 and BG3 affine. */
+  export const MODE2: u16 = 2;
   export const MODE3: u16 = 3;
   export const MODE4: u16 = 4;
   export const MODE5: u16 = 5;
@@ -165,6 +219,14 @@ export enum MapSize {
   S64x64 = 3,
 }
 
+/** Affine background map sizes, in tiles (SPEC.md §8.4). */
+export enum AffineSize {
+  S16x16 = 0,
+  S32x32 = 1,
+  S64x64 = 2,
+  S128x128 = 3,
+}
+
 /** Builders for a `BGxCNT` value (SPEC.md §6.2), e.g. `bgcnt.priority(bgcnt.screenBlock(0, 31), 1)`. */
 export namespace bgcnt {
   // @ts-ignore: decorator
@@ -191,6 +253,16 @@ export namespace bgcnt {
   @inline export function mosaic(c: u16): u16 {
     return c | 0x40;
   }
+  /** Map size of an affine background. */
+  // @ts-ignore: decorator
+  @inline export function affineSize(c: u16, s: AffineSize): u16 {
+    return (c & 0x3fff) | (<u16>s << 14);
+  }
+  /** An affine background repeats instead of being transparent outside its map. */
+  // @ts-ignore: decorator
+  @inline export function wrap(c: u16): u16 {
+    return c | 0x2000;
+  }
 }
 
 /** Packs 8-bit channels into RGB555. */
@@ -215,6 +287,19 @@ export namespace bgcnt {
 @inline export function bgTile(block: i32, index: i32): usize {
   return VRAM + <usize>block * 0x4000 + (<usize>index << 5);
 }
+/** Address of 8bpp background tile `index` counted from character block `block` (0–3). Tiles are 64 bytes;
+ *  affine backgrounds always use these. */
+// @ts-ignore: decorator
+@inline export function bgTile8(block: i32, index: i32): usize {
+  return VRAM + <usize>block * 0x4000 + (<usize>index << 6);
+}
+/** Address of an affine background's map at screen block `block` (0–31): one tile index per byte,
+ *  row-major (SPEC.md §8.4). */
+// @ts-ignore: decorator
+@inline export function affineMap(block: i32): usize {
+  return VRAM + <usize>block * 0x800;
+}
+
 /** Address of 4bpp sprite tile `index` (0–1023). */
 // @ts-ignore: decorator
 @inline export function objTile(index: i32): usize {
@@ -412,6 +497,146 @@ export namespace oam {
   }
 }
 
+/** Sets affine background `bg` (2 or 3) to matrix `m`, placed so that texture
+ *  pixel (texX, texY) appears at screen pixel (scrX, scrY). Rotation and
+ *  scaling then happen around that point. */
+export function setBgAffine(bg: i32, m: AffineMatrix, texX: i32, texY: i32, scrX: i32, scrY: i32): void {
+  const at = reg.BG2PA + <usize>(bg - 2) * 0x10;
+  const pa = <i32>affine.pa(m), pb = <i32>affine.pb(m), pc = <i32>affine.pc(m), pd = <i32>affine.pd(m);
+  store<u16>(at, <u16>pa);
+  store<u16>(at + 2, <u16>pb);
+  store<u16>(at + 4, <u16>pc);
+  store<u16>(at + 6, <u16>pd);
+  store<u32>(at + 8, <u32>((texX << 8) - pa * scrX - pb * scrY));
+  store<u32>(at + 12, <u32>((texY << 8) - pc * scrX - pd * scrY));
+}
+
+// ---- Sound (SPEC.md §14) -------------------------------------------------------
+
+/** Sound: four GBA-style channels written through `reg.SOUND*`, with
+ *  builders for their fields, and setup:
+ *
+ *    sound.enable();
+ *    write16(reg.SOUND2CNT_L, sound.DUTY_50 | sound.envelope(12, 2, false));
+ *    write16(reg.SOUND2CNT_H, sound.START | sound.rate(440));
+ */
+export namespace sound {
+  /** Starts (or restarts) a channel; the host clears it. */
+  export const START: u16 = 1 << 15;
+  /** Stops the channel when its length runs out. */
+  export const LENGTH: u16 = 1 << 14;
+
+  export const DUTY_12: u16 = 0 << 6;
+  export const DUTY_25: u16 = 1 << 6;
+  export const DUTY_50: u16 = 2 << 6;
+  export const DUTY_75: u16 = 3 << 6;
+
+  /** `SOUND3CNT_L`: the wave channel is on. */
+  export const WAVE_ON: u16 = 1 << 7;
+  /** `SOUND3CNT_L`: play bank 1 (or start with it, with `WAVE_64`). */
+  export const WAVE_BANK1: u16 = 1 << 6;
+  /** `SOUND3CNT_L`: play both banks as one 64-sample wave. */
+  export const WAVE_64: u16 = 1 << 5;
+  /** `SOUND3CNT_H` volumes. */
+  export const WAVE_100: u16 = 1 << 13;
+  export const WAVE_50: u16 = 2 << 13;
+  export const WAVE_25: u16 = 3 << 13;
+  export const WAVE_75: u16 = 1 << 15;
+
+  /** Turns sound on with every channel on both sides at full volume. */
+  export function enable(): void {
+    store<u16>(reg.SOUNDCNT_X, 0x80);
+    store<u16>(reg.SOUNDCNT_L, 0xff77);
+    store<u16>(reg.SOUNDCNT_H, 0x330e);
+  }
+  /** Turns sound off; every channel stops. */
+  export function disable(): void {
+    store<u16>(reg.SOUNDCNT_X, 0);
+  }
+
+  /** The rate field for a square channel playing `hz` (64 Hz and up); the
+   *  wave channel plays an octave lower at the same rate. */
+  // @ts-ignore: decorator
+  @inline export function rate(hz: u32): u16 {
+    return hz < 64 ? 0 : <u16>(2048 - 131072 / hz);
+  }
+  /** `SOUND1CNT_L`: every `time` 128ths of a second (1–7, 0 = off), the
+   *  rate changes by rate >> `shift` (1–7), down if `decrease`. */
+  // @ts-ignore: decorator
+  @inline export function sweep(time: u16, shift: u16, decrease: bool): u16 {
+    return ((time & 7) << 4) | (shift & 7) | (decrease ? 8 : 0);
+  }
+  /** The envelope fields: start at `volume` (0–15), stepping by one every
+   *  `step` 64ths of a second (0 = constant), up if `increase`. */
+  // @ts-ignore: decorator
+  @inline export function envelope(volume: u16, step: u16, increase: bool): u16 {
+    return ((volume & 15) << 12) | ((step & 7) << 8) | (increase ? 1 << 11 : 0);
+  }
+  /** The length field of channels 1, 2 and 4 for `n` 256ths of a second
+   *  (1–64); it only counts with `LENGTH` set. Channel 3 takes 256 − n. */
+  // @ts-ignore: decorator
+  @inline export function length(n: u16): u16 {
+    return (64 - n) & 63;
+  }
+  /** `SOUND4CNT_H`: noise from a divider (0–7) and shift (0–13), with the
+   *  7-bit register if `short` (more tonal). */
+  // @ts-ignore: decorator
+  @inline export function noise(divider: u16, shift: u16, short: bool): u16 {
+    return (divider & 7) | ((shift & 15) << 4) | (short ? 8 : 0);
+  }
+
+  /** Address of wave RAM: two banks of 16 bytes, each 32 4-bit samples, high nibble first. */
+  // @ts-ignore: decorator
+  @inline export function waveRam(): usize {
+    return WAVE_RAM;
+  }
+  /** Address of the 28 KB of sample RAM (signed 8-bit) that the sample channels play from. */
+  // @ts-ignore: decorator
+  @inline export function sampleRam(): usize {
+    return SAMPLE_RAM;
+  }
+  /** Which channels are playing: bits 0–3 channels 1–4, bits 4 and 5 sample
+   *  channels A and B, as of the end of the last frame. */
+  // @ts-ignore: decorator
+  @inline export function status(): u16 {
+    return load<u16>(reg.SOUNDCNT_X) & 0x3f;
+  }
+}
+
+/** The two sample channels, A (0) and B (1), playing signed 8-bit samples
+ *  from sample RAM (SPEC.md §14.6). */
+export namespace pcm {
+  // @ts-ignore: decorator
+  @inline function base(ch: i32): usize {
+    return ch == 0 ? reg.PCMA_SAD : reg.PCMB_SAD;
+  }
+
+  /** Plays `len` samples from sample RAM offset `start` at `rate` Hz and `volume` 0–64, once. */
+  export function play(ch: i32, start: u16, len: u16, rate: u16, volume: u16): void {
+    const b = base(ch);
+    store<u16>(b, start);
+    store<u16>(b + 2, len);
+    store<u16>(b + 6, rate);
+    store<u16>(b + 8, sound.START | (volume < 64 ? volume : 64));
+  }
+  /** Like `play`, then repeats from sample `loopAt` until stopped. */
+  export function playLooped(ch: i32, start: u16, len: u16, loopAt: u16, rate: u16, volume: u16): void {
+    store<u16>(base(ch) + 4, loopAt);
+    play(ch, start, len, rate, volume);
+    store<u16>(base(ch) + 8, load<u16>(base(ch) + 8) | (1 << 13));
+  }
+  export function stop(ch: i32): void {
+    store<u16>(base(ch) + 8, 1 << 14);
+  }
+  /** The playback position, in samples from the start, as of the end of the last frame. */
+  export function position(ch: i32): u16 {
+    return load<u16>(base(ch) + 10);
+  }
+  export function playing(ch: i32): bool {
+    return (sound.status() & (1 << (4 + ch))) != 0;
+  }
+}
+
 // ---- Fixed-point trigonometry --------------------------------------------------
 
 /** Fixed-point trigonometry shared by all WASM-AD SDKs, so carts in any
@@ -447,27 +672,54 @@ export namespace fixed {
 
 // ---- Input, time, save RAM -------------------------------------------------------
 
-/** Buttons held this frame. */
+/** Buttons held this frame by player 1. */
 // @ts-ignore: decorator
 @inline export function keys(): u16 {
   return load<u16>(reg.KEYS);
 }
 
+/** Buttons held this frame by `player`, 1–4 (SPEC.md §5). */
+export function keysOf(player: i32): u16 {
+  assert(player >= 1 && player <= 4);
+  return player == 1 ? load<u16>(reg.KEYS) : load<u16>(reg.KEYS2 + <usize>(player - 2) * 2);
+}
+
+/** Bits 0–3: which of players 1–4 have a controller. */
+// @ts-ignore: decorator
+@inline export function pads(): u16 {
+  return load<u16>(reg.PADS);
+}
+
+/** Whether `player` (1–4) has a controller. Player 1 always does. */
+export function connected(player: i32): bool {
+  assert(player >= 1 && player <= 4);
+  return (<i32>pads() & (1 << (player - 1))) != 0;
+}
+
 /** Edge detection over `KEYS`: call `buttons.update()` at the start of every
  *  frame. Its two words of state live in linear memory. */
 export namespace buttons {
-  const STATE: usize = memory.data(4); // held: u16, prev: u16
+  // Per player 1–4: held: u16, prev: u16.
+  const STATE: usize = memory.data(16);
+
+  // @ts-ignore: decorator
+  @inline function at(player: i32): usize {
+    return STATE + <usize>(player - 1) * 4;
+  }
 
-  export function update(): void {
-    store<u16>(STATE + 2, load<u16>(STATE));
-    store<u16>(STATE, keys());
+  /** Reads `player`'s buttons (default player 1) for this frame. */
+  export function update(player: i32 = 1): void {
+    const s = at(player);
+    store<u16>(s + 2, load<u16>(s));
+    store<u16>(s, keysOf(player));
   }
-  export function held(k: u16): bool {
-    return (load<u16>(STATE) & k) != 0;
+  export function held(k: u16, player: i32 = 1): bool {
+    return (load<u16>(at(player)) & k) != 0;
   }
   /** True only on the frame the button went down. */
-  export function pressed(k: u16): bool {
-    return (load<u16>(STATE) & ~load<u16>(STATE + 2) & k) != 0;
+  export function pressed(k: u16, player: i32 = 1): bool {
+    const s = at(player);
+    return (load<u16>(s) & ~load<u16>(s + 2) & k) != 0;
   }
 }
 

package/bin/wasmad.mjs

@@ -4,32 +4,51 @@
 //
 //   wasmad check <cart.wasm>                  validate a cart against SPEC.md
 //   wasmad meta <cart.wasm> key=value...      set the `wasm-ad` metadata section
+//   wasmad icon <cart.wasm> <icon.png>        set the icon (SPEC.md §2.5)
+//   wasmad icon <cart.wasm> --png <out.png>   export the icon as a PNG
 //   wasmad run <cart.wasm> [options]          run frames headlessly
 //
 // `meta` replaces the metadata section in place (or writes `-o <file>`); `spec`
 // defaults to the version this tool implements. It is for toolchains that
 // cannot emit custom sections themselves (AssemblyScript, TinyGo).
 //
-// `run` boots the cart like a host does (SPEC.md §3) and renders with the
-// reference renderer, player/web/core.wasm (`make player`). Options:
-//   --frames N        frames to run (default 1)
-//   --keys SCRIPT     held buttons per frame, e.g. "0-29:right,30-59:down+b,60:a"
+// `icon` takes a 32×32 PNG with at most 15 colors plus transparency.
+//
+// `run` boots the cart like a host does (SPEC.md §3) and renders and makes
+// sound with the reference core, player/web/core.wasm (`make player`). Options:
+//   --frames N        frames to run (default 1, or the replay's length)
+//   --keys SCRIPT     held buttons per frame, e.g. "0-29:right,30-59:down+b,60:a";
+//                     "a@2" is player 2's A button
 //   --seed N          value for SEED (default 1)
-//   --hash F,F,...    print a hash of the frame rendered at each listed frame
+//   --save FILE       boot with this 32 KB save RAM
+//   --replay FILE     play a .wadreplay (FORMATS.md) instead of --keys
+//   --record FILE     write the run as a .wadreplay (--unbound: not tied to the cart)
+//   --state FILE      start from a .wadstate instead of booting
+//   --save-state FILE write a .wadstate after the last frame
+//   --force           use a replay or state made for a different cart
+//   --hash F,F,...    print a hash of the frame rendered at each listed frame,
+//                     and one of all the sound
 //   --ppm FILE        write the last rendered frame as a PPM image
+//   --wav FILE        write the sound of every frame as a 48 kHz stereo WAV
 //   --core FILE       a different core.wasm
 
 import { readFileSync, realpathSync, writeFileSync } from 'node:fs';
 import { createHash } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
+import { deflateRawSync, deflateSync, inflateRawSync, inflateSync } from 'node:zlib';
 
-const SPEC = '0.1';
-const SPEC_VERSION = 0x0001;
+const SPEC = '0.3';
+const SPEC_VERSION = 0x0003;
 const W = 240, H = 160;
 const A = {
   IO: 0x400, PAL_END: 0xC00, OAM: 0xC00, VIDEO_END: 0x19000, SAVE: 0x19000, SAVE_SIZE: 0x8000, CART: 0x28000,
   VCOUNT: 0x406, KEYS: 0x700, FRAME: 0x704, SEED: 0x708, SAVECNT: 0x70C, SAVESTAT: 0x70E, SPEC: 0x710,
+  KEYS2: 0x712, KEYS3: 0x714, KEYS4: 0x716, PADS: 0x718,
+  BG2PA: 0x420, BG2PD: 0x426, BG3PA: 0x430, BG3PD: 0x436,
+  SOUND_REGS: 0x460, SOUND_REGS_END: 0x4D0, SOUND_STATE: 0x780, SOUND_STATE_END: 0x800,
 };
+const SOUND_SAMPLES = 800;
+const ICON_SIZE = 544;
 const KEY = { a: 1, b: 2, select: 4, start: 8, right: 16, left: 32, up: 64, down: 128, r: 256, l: 512 };
 const MAX_CART = 32 * 1024 * 1024;
 
@@ -245,6 +264,17 @@ export function check(bytes) {
     else if (!/^\d+\.\d+$/.test(meta.spec)) errors.push(`metadata spec "${meta.spec}" is not major.minor (§2.3)`);
     if (!meta.title) errors.push('metadata has no title (§2.3)');
   }
+  // §2.5 icon
+  const icons = m.custom.filter((c) => c.name === 'wasm-ad-icon');
+  if (icons.length) {
+    if (icons[0].data.length !== ICON_SIZE) errors.push(`the icon section is ${icons[0].data.length} bytes; it must be ${ICON_SIZE} (§2.5)`);
+    else {
+      const used = new Set();
+      for (const b of icons[0].data.subarray(32)) used.add(b & 15).add(b >> 4);
+      used.delete(0);
+      info.push(`icon: 32×32, ${used.size} colors`);
+    }
+  }
   return { errors, warnings, meta, info };
 }
 
@@ -268,43 +298,267 @@ function leb(n) {
   return out;
 }
 
-/** Returns `bytes` with its `wasm-ad` sections replaced by one holding `meta`. */
-export function setMeta(bytes, meta) {
-  const text = Object.entries(meta).map(([k, v]) => `${k}=${v}\n`).join('');
-  const name = new TextEncoder().encode('wasm-ad');
-  const payload = [...leb(name.length), ...name, ...new TextEncoder().encode(text)];
-  const section = Uint8Array.from([0, ...leb(payload.length), ...payload]);
+function concat(parts) {
+  const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+  let at = 0;
+  for (const p of parts) { out.set(p, at); at += p.length; }
+  return out;
+}
+
+/** Returns `bytes` with its custom sections called `name` replaced by one holding `data`. */
+export function setSection(bytes, name, data) {
+  const n = new TextEncoder().encode(name);
+  const payload = concat([Uint8Array.from([...leb(n.length), ...n]), data]);
   const parts = [bytes.subarray(0, 8)];
   for (const s of sections(bytes)) {
-    if (s.id === 0 && new Reader(bytes, s.body, s.end).name() === 'wasm-ad') continue;
+    if (s.id === 0 && new Reader(bytes, s.body, s.end).name() === name) continue;
     parts.push(bytes.subarray(s.start, s.end));
   }
-  parts.push(section);
-  const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
-  let at = 0;
-  for (const p of parts) { out.set(p, at); at += p.length; }
+  parts.push(Uint8Array.from([0, ...leb(payload.length)]), payload);
+  return concat(parts);
+}
+
+/** Returns `bytes` with its `wasm-ad` sections replaced by one holding `meta`. */
+export function setMeta(bytes, meta) {
+  const text = Object.entries(meta).map(([k, v]) => `${k}=${v}\n`).join('');
+  return setSection(bytes, 'wasm-ad', new TextEncoder().encode(text));
+}
+
+// ---- Icons (SPEC.md §2.5) --------------------------------------------------------
+
+/** Decodes a non-interlaced 8-bit-or-less PNG into { width, height, rgba }. */
+export function decodePng(bytes) {
+  const sig = [137, 80, 78, 71, 13, 10, 26, 10];
+  if (sig.some((b, i) => bytes[i] !== b)) throw new Error('not a PNG file');
+  const dv = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  let width, height, depth, type, palette = [], alpha = [], idat = [];
+  for (let at = 8; at < bytes.length;) {
+    const len = dv.getUint32(at);
+    const kind = String.fromCharCode(...bytes.subarray(at + 4, at + 8));
+    const data = bytes.subarray(at + 8, at + 8 + len);
+    if (kind === 'IHDR') {
+      const h = new DataView(data.buffer, data.byteOffset, len);
+      [width, height, depth, type] = [h.getUint32(0), h.getUint32(4), data[8], data[9]];
+      if (data[12]) throw new Error('interlaced PNGs are not supported');
+      if (depth > 8) throw new Error('16-bit PNGs are not supported');
+    } else if (kind === 'PLTE') for (let i = 0; i < len; i += 3) palette.push([data[i], data[i + 1], data[i + 2]]);
+    else if (kind === 'tRNS') alpha = [...data];
+    else if (kind === 'IDAT') idat.push(data);
+    at += 12 + len;
+  }
+  const channels = { 0: 1, 2: 3, 3: 1, 4: 2, 6: 4 }[type];
+  if (!channels) throw new Error(`unsupported PNG color type ${type}`);
+  const raw = inflateSync(concat(idat));
+  const stride = Math.ceil((width * channels * depth) / 8), bpp = Math.max(1, (channels * depth) / 8);
+  const rows = [];
+  let prev = new Uint8Array(stride);
+  for (let y = 0; y < height; y++) {
+    const f = raw[y * (stride + 1)], line = raw.slice(y * (stride + 1) + 1, (y + 1) * (stride + 1));
+    for (let i = 0; i < stride; i++) {
+      const a = i >= bpp ? line[i - bpp] : 0, b = prev[i], c = i >= bpp ? prev[i - bpp] : 0;
+      const p = a + b - c, pa = Math.abs(p - a), pb = Math.abs(p - b), pc = Math.abs(p - c);
+      line[i] += [0, a, b, (a + b) >> 1, pa <= pb && pa <= pc ? a : pb <= pc ? b : c][f];
+    }
+    rows.push(prev = line);
+  }
+  const rgba = new Uint8Array(width * height * 4);
+  const sample = (row, i) => (depth === 8 ? row[i] : (row[(i * depth) >> 3] >> (8 - depth - ((i * depth) & 7))) & ((1 << depth) - 1));
+  for (let y = 0; y < height; y++) {
+    for (let x = 0; x < width; x++) {
+      const o = (y * width + x) * 4, r = rows[y];
+      let px;
+      if (type === 3) { const i = sample(r, x); px = [...(palette[i] ?? [0, 0, 0]), alpha[i] ?? 255]; }
+      else if (type === 0 || type === 4) {
+        const g = sample(r, x * channels) * (255 / ((1 << depth) - 1));
+        px = [g, g, g, type === 4 ? r[x * 2 + 1] : 255];
+      } else px = [r[x * channels], r[x * channels + 1], r[x * channels + 2], type === 6 ? r[x * 4 + 3] : 255];
+      rgba.set(px, o);
+    }
+  }
+  return { width, height, rgba };
+}
+
+/** Encodes RGBA8 pixels as a PNG. */
+export function encodePng(width, height, rgba) {
+  const crcTable = Array.from({ length: 256 }, (_, n) => {
+    for (let k = 0; k < 8; k++) n = n & 1 ? 0xEDB88320 ^ (n >>> 1) : n >>> 1;
+    return n >>> 0;
+  });
+  const crc = (b) => { let c = 0xFFFFFFFF; for (const x of b) c = crcTable[(c ^ x) & 255] ^ (c >>> 8); return (c ^ 0xFFFFFFFF) >>> 0; };
+  const chunk = (kind, data) => {
+    const out = new Uint8Array(12 + data.length), dv = new DataView(out.buffer);
+    dv.setUint32(0, data.length);
+    out.set(new TextEncoder().encode(kind), 4);
+    out.set(data, 8);
+    dv.setUint32(8 + data.length, crc(out.subarray(4, 8 + data.length)));
+    return out;
+  };
+  const ihdr = new Uint8Array(13), h = new DataView(ihdr.buffer);
+  h.setUint32(0, width); h.setUint32(4, height); ihdr.set([8, 6, 0, 0, 0], 8);
+  const raw = new Uint8Array(height * (width * 4 + 1));
+  for (let y = 0; y < height; y++) raw.set(rgba.subarray(y * width * 4, (y + 1) * width * 4), y * (width * 4 + 1) + 1);
+  return concat([Uint8Array.from([137, 80, 78, 71, 13, 10, 26, 10]), chunk('IHDR', ihdr), chunk('IDAT', deflateSync(raw)), chunk('IEND', new Uint8Array())]);
+}
+
+/** Converts a 32×32 PNG with at most 15 colors plus transparency to an icon section's 544 bytes. */
+export function iconFromPng(png) {
+  const { width, height, rgba } = decodePng(png);
+  if (width !== 32 || height !== 32) throw new Error(`the icon is ${width}×${height}; it must be 32×32`);
+  const colors = [0], out = new Uint8Array(ICON_SIZE), dv = new DataView(out.buffer);
+  for (let i = 0; i < 1024; i++) {
+    let index = 0;
+    if (rgba[i * 4 + 3] >= 128) {
+      const c = (rgba[i * 4] >> 3) | ((rgba[i * 4 + 1] >> 3) << 5) | ((rgba[i * 4 + 2] >> 3) << 10);
+      index = colors.indexOf(c, 1);
+      if (index < 0) index = colors.push(c) - 1;
+    }
+    out[32 + (i >> 1)] |= index << ((i & 1) * 4);
+  }
+  if (colors.length > 16) throw new Error(`the icon has ${colors.length - 1} colors; at most 15 plus transparency fit (§2.5)`);
+  colors.forEach((c, i) => dv.setUint16(i * 2, c, true));
   return out;
 }
 
+/** The cart's icon as 32×32 RGBA8 pixels, or null. */
+export function readIcon(bytes) {
+  const icon = inspect(bytes).custom.find((c) => c.name === 'wasm-ad-icon');
+  if (!icon || icon.data.length !== ICON_SIZE) return null;
+  const d = icon.data, rgba = new Uint8Array(1024 * 4);
+  for (let i = 0; i < 1024; i++) {
+    const index = (d[32 + (i >> 1)] >> ((i & 1) * 4)) & 15;
+    if (!index) continue;
+    const c = d[index * 2] | (d[index * 2 + 1] << 8);
+    const x = (v) => (v << 3) | (v >> 2);
+    rgba.set([x(c & 31), x((c >> 5) & 31), x((c >> 10) & 31), 255], i * 4);
+  }
+  return rgba;
+}
+
+// ---- Replays and save states (FORMATS.md) -------------------------------------
+
+const FORMAT_VERSION = 1;
+
+export function sha256(bytes) {
+  return new Uint8Array(createHash('sha256').update(bytes).digest());
+}
+
+function header(magic, cartHash, frames, seed) {
+  const out = new Uint8Array(48), dv = new DataView(out.buffer);
+  out.set(new TextEncoder().encode(magic));
+  dv.setUint16(4, FORMAT_VERSION, true);
+  dv.setUint16(6, SPEC_VERSION, true);
+  if (cartHash) out.set(cartHash, 8);
+  dv.setUint32(40, frames >>> 0, true);
+  dv.setUint32(44, seed >>> 0, true);
+  return out;
+}
+
+function readHeader(bytes, magic, what) {
+  if (bytes.length < 48 || new TextDecoder().decode(bytes.subarray(0, 4)) !== magic) throw new Error(`not a ${what} file`);
+  const dv = new DataView(bytes.buffer, bytes.byteOffset, 48);
+  const version = dv.getUint16(4, true);
+  if (version > FORMAT_VERSION) throw new Error(`${what} format ${version} is newer than this tool's (${FORMAT_VERSION})`);
+  const cart = bytes.slice(8, 40);
+  return {
+    version, spec: dv.getUint16(6, true), cart: cart.some((b) => b) ? cart : null,
+    frames: dv.getUint32(40, true), seed: dv.getUint32(44, true), body: inflateRawSync(bytes.subarray(48)),
+  };
+}
+
+/** Throws unless a replay or state made for `hash` (null: any cart) fits `cart`. */
+export function checkCart(hash, cart, force = false) {
+  if (!hash || force) return;
+  if (!sha256(cart).every((b, i) => b === hash[i])) throw new Error('this file was made for a different cart (--force to use it anyway)');
+}
+
+/**
+ * A .wadreplay: `inputs` holds [KEYS, KEYS2, KEYS3, KEYS4, PADS] per frame;
+ * `cart` null makes it an input script for any cart.
+ */
+export function encodeReplay({ cart = null, seed, save = null, inputs }) {
+  const runs = [];
+  for (const input of inputs) {
+    const last = runs.at(-1);
+    if (last && last.input.every((v, i) => v === input[i])) last.n++;
+    else runs.push({ n: 1, input });
+  }
+  const body = new Uint8Array(2 + (save ? A.SAVE_SIZE : 0) + runs.length * 14), dv = new DataView(body.buffer);
+  let at = 2;
+  if (save) { dv.setUint16(0, 1, true); body.set(save, 2); at += A.SAVE_SIZE; }
+  for (const { n, input } of runs) {
+    dv.setUint32(at, n, true);
+    for (let i = 0; i < 5; i++) dv.setUint16(at + 4 + i * 2, input[i] ?? 0, true);
+    at += 14;
+  }
+  return concat([header('WADR', cart && sha256(cart), inputs.length, seed), deflateRawSync(body)]);
+}
+
+export function decodeReplay(bytes) {
+  const { body, ...h } = readHeader(bytes, 'WADR', 'replay');
+  const dv = new DataView(body.buffer, body.byteOffset, body.byteLength);
+  let at = 2, save = null;
+  if (dv.getUint16(0, true) & 1) { save = body.slice(2, 2 + A.SAVE_SIZE); at += A.SAVE_SIZE; }
+  const inputs = [];
+  for (; at + 14 <= body.length; at += 14) {
+    const input = [0, 1, 2, 3, 4].map((i) => dv.getUint16(at + 4 + i * 2, true));
+    for (let n = dv.getUint32(at, true); n--;) inputs.push(input);
+  }
+  if (inputs.length !== h.frames) throw new Error('the replay is damaged: its runs do not add up to its frame count');
+  return { ...h, save, inputs };
+}
+
+/** A .wadstate of `memory` after `frame` frames. */
+export function encodeState({ cart, frame, seed, memory }) {
+  const body = new Uint8Array(4 + memory.length);
+  new DataView(body.buffer).setUint32(0, memory.length, true);
+  body.set(memory, 4);
+  return concat([header('WADS', sha256(cart), frame, seed), deflateRawSync(body)]);
+}
+
+export function decodeState(bytes) {
+  const { body, ...h } = readHeader(bytes, 'WADS', 'save state');
+  const length = new DataView(body.buffer, body.byteOffset, 4).getUint32(0, true);
+  if (length % 65536 || body.length !== 4 + length) throw new Error('the save state is damaged');
+  if (!h.cart) throw new Error('the save state names no cart');
+  return { ...h, memory: body.subarray(4) };
+}
+
 // ---- Headless host ----------------------------------------------------------
 
-/** Parses "0-29:right,30-59:down+b,60:a" into a frame -> KEYS function. */
+/**
+ * Parses "0-29:right,30-59:down+b+a@2" into a function from a frame number to
+ * [KEYS, KEYS2, KEYS3, KEYS4, PADS]. "b@2" is player 2's B; every player the
+ * script mentions has a controller for the whole run.
+ */
 export function parseKeys(script) {
+  let pads = 1;
   const spans = (script ?? '').split(',').filter(Boolean).map((part) => {
     const [range, buttons] = part.split(':');
     const [from, to = from] = range.split('-').map(Number);
-    let mask = 0;
+    const masks = [0, 0, 0, 0];
     for (const b of (buttons ?? '').split('+').filter(Boolean)) {
-      if (!(b in KEY)) throw new Error(`unknown button "${b}"; use ${Object.keys(KEY).join(', ')}`);
-      mask |= KEY[b];
+      const [name, player = '1'] = b.split('@');
+      const p = Number(player) - 1;
+      if (!(name in KEY)) throw new Error(`unknown button "${name}"; use ${Object.keys(KEY).join(', ')}`);
+      if (!(p >= 0 && p < 4)) throw new Error(`unknown player "${player}"; use 1 to 4`);
+      masks[p] |= KEY[name];
+      pads |= 1 << p;
     }
-    return { from, to, mask };
+    return { from, to, masks };
   });
-  return (frame) => spans.reduce((k, s) => (frame >= s.from && frame <= s.to ? k | s.mask : k), 0);
+  return (frame) => {
+    const out = [0, 0, 0, 0, pads];
+    for (const s of spans) if (frame >= s.from && frame <= s.to) s.masks.forEach((m, i) => { out[i] |= m; });
+    return out;
+  };
 }
 
-/** Boots a cart and returns a host that runs frames (SPEC.md §3). */
-export async function boot(bytes, { core: corePath, seed = 1, onTrace = () => {} } = {}) {
+/**
+ * Boots a cart and returns a host that runs frames (SPEC.md §3). `save` is
+ * the save RAM to restore at boot; `state` a decoded save state to start
+ * from instead of booting (FORMATS.md §3).
+ */
+export async function boot(bytes, { core: corePath, seed = 1, save = null, state = null, onTrace = () => {} } = {}) {
   const core = (await WebAssembly.instantiate(readFileSync(corePath))).instance.exports;
   let instance;
   const decoder = new TextDecoder();
@@ -313,23 +567,55 @@ export async function boot(bytes, { core: corePath, seed = 1, onTrace = () => {}
   const ex = instance.exports;
   const mem = () => new Uint8Array(ex.memory.buffer);
   const dv = () => new DataView(ex.memory.buffer);
-  mem().fill(0, 0, A.CART);
-  for (let i = 0; i < 128; i++) dv().setUint16(A.OAM + i * 8, 0x0200, true);
-  dv().setUint32(A.SEED, seed >>> 0, true);
-  dv().setUint16(A.SPEC, SPEC_VERSION, true);
-  ex.start?.();
+  let frame = 0, sound = new Int16Array(SOUND_SAMPLES * 2);
+  if (state) {
+    const grow = (state.memory.length - ex.memory.buffer.byteLength) / 65536;
+    if (grow < 0) throw new Error('the save state has less memory than the cart starts with');
+    if (grow) ex.memory.grow(grow);
+    mem().set(state.memory);
+    frame = state.frames;
+  } else {
+    mem().fill(0, 0, A.CART);
+    for (let i = 0; i < 128; i++) dv().setUint16(A.OAM + i * 8, 0x0200, true);
+    for (const a of [A.BG2PA, A.BG2PD, A.BG3PA, A.BG3PD]) dv().setUint16(a, 0x100, true);
+    dv().setUint32(A.SEED, seed >>> 0, true);
+    dv().setUint16(A.SPEC, SPEC_VERSION, true);
+    if (save) {
+      mem().set(save, A.SAVE);
+      dv().setUint16(A.SAVESTAT, 1, true);
+    }
+    ex.start?.();
+  }
 
-  let frame = 0;
   return {
     exports: ex,
-    /** Runs one frame with `keys` held and returns the rendered RGBA8 pixels. */
-    frame(keys = 0) {
+    /** The last frame's sound: 800 stereo pairs of i16, left first. */
+    get sound() { return sound; },
+    /** Frames run since boot. */
+    get frames() { return frame; },
+    /** A copy of the cart's whole linear memory, between frames. */
+    memory() { return mem().slice(); },
+    /**
+     * Runs one frame and returns the rendered RGBA8 pixels. `input` is KEYS,
+     * or [KEYS, KEYS2, KEYS3, KEYS4, PADS].
+     */
+    frame(input = 0) {
+      const [keys, k2 = 0, k3 = 0, k4 = 0, pads = 1] = typeof input === 'number' ? [input] : input;
       dv().setUint16(A.KEYS, keys & 0x3FF, true);
+      dv().setUint16(A.KEYS2, k2 & 0x3FF, true);
+      dv().setUint16(A.KEYS3, k3 & 0x3FF, true);
+      dv().setUint16(A.KEYS4, k4 & 0x3FF, true);
+      dv().setUint16(A.PADS, (pads & 0xF) | 1, true);
       dv().setUint32(A.FRAME, frame >>> 0, true);
       dv().setUint16(A.VCOUNT, 160, true);
       ex.update();
       const coreMem = new Uint8Array(core.memory.buffer, core.ad_mem(), core.ad_mem_len());
-      coreMem.set(mem().subarray(0, A.VIDEO_END));
+      coreMem.set(mem().subarray(0, A.CART));
+      core.ad_sound_frame();
+      for (const [from, to] of [[A.SOUND_REGS, A.SOUND_REGS_END], [A.SOUND_STATE, A.SOUND_STATE_END]]) {
+        mem().set(coreMem.subarray(from, to), from);
+      }
+      sound = new Int16Array(core.memory.buffer, core.ad_sound_buffer(), SOUND_SAMPLES * 2).slice();
       for (let y = 0; y < H; y++) {
         if (ex.scanline) {
           dv().setUint16(A.VCOUNT, y, true);
@@ -345,8 +631,24 @@ export async function boot(bytes, { core: corePath, seed = 1, onTrace = () => {}
   };
 }
 
-export function hash(pixels) {
-  return createHash('sha256').update(pixels).digest('hex').slice(0, 16);
+export function hash(...chunks) {
+  const h = createHash('sha256');
+  for (const c of chunks) h.update(new Uint8Array(c.buffer, c.byteOffset, c.byteLength));
+  return h.digest('hex').slice(0, 16);
+}
+
+/** A 48 kHz 16-bit stereo WAV file of `frames` (Int16Arrays from `sound`). */
+export function wav(frames) {
+  const bytes = frames.reduce((n, f) => n + f.byteLength, 0);
+  const out = new DataView(new ArrayBuffer(44 + bytes));
+  const tag = (at, s) => [...s].forEach((c, i) => out.setUint8(at + i, c.charCodeAt(0)));
+  tag(0, 'RIFF'); out.setUint32(4, 36 + bytes, true); tag(8, 'WAVEfmt ');
+  out.setUint32(16, 16, true); out.setUint16(20, 1, true); out.setUint16(22, 2, true);
+  out.setUint32(24, 48000, true); out.setUint32(28, 48000 * 4, true); out.setUint16(32, 4, true);
+  out.setUint16(34, 16, true); tag(36, 'data'); out.setUint32(40, bytes, true);
+  let at = 44;
+  for (const f of frames) for (const s of f) { out.setInt16(at, s, true); at += 2; }
+  return new Uint8Array(out.buffer);
 }
 
 function ppm(pixels) {
@@ -359,12 +661,16 @@ function ppm(pixels) {
 
 // ---- CLI ----------------------------------------------------------------------
 
+const FLAGS = new Set(['force', 'unbound']);
+
 function options(args) {
   const opts = { _: [] };
   for (let i = 0; i < args.length; i++) {
     if (args[i] === '-o') opts.o = args[++i];
-    else if (args[i].startsWith('--')) opts[args[i].slice(2)] = args[++i];
-    else opts._.push(args[i]);
+    else if (args[i].startsWith('--')) {
+      const name = args[i].slice(2);
+      opts[name] = FLAGS.has(name) ? true : args[++i];
+    } else opts._.push(args[i]);
   }
   return opts;
 }
@@ -372,8 +678,16 @@ function options(args) {
 async function main([cmd, ...args]) {
   const opts = options(args);
   const [file, ...rest] = opts._;
-  if (!cmd || !file || !['check', 'meta', 'run'].includes(cmd)) {
-    console.error('usage: wasmad check <cart.wasm>\n       wasmad meta <cart.wasm> [-o out.wasm] key=value...\n       wasmad run <cart.wasm> [--frames N] [--keys SCRIPT] [--seed N] [--hash F,F] [--ppm FILE]');
+  if (!cmd || !file || !['check', 'meta', 'icon', 'run'].includes(cmd)) {
+    console.error([
+      'usage: wasmad check <cart.wasm>',
+      '       wasmad meta <cart.wasm> [-o out.wasm] key=value...',
+      '       wasmad icon <cart.wasm> <icon.png> [-o out.wasm]',
+      '       wasmad icon <cart.wasm> --png <out.png>',
+      '       wasmad run <cart.wasm> [--frames N] [--keys SCRIPT | --replay FILE] [--seed N] [--save FILE]',
+      '                  [--state FILE] [--hash F,F] [--ppm FILE] [--wav FILE] [--record FILE [--unbound]]',
+      '                  [--save-state FILE] [--force]',
+    ].join('\n'));
     return 2;
   }
   const bytes = new Uint8Array(readFileSync(file));
@@ -390,6 +704,18 @@ async function main([cmd, ...args]) {
     return 0;
   }
 
+  if (cmd === 'icon') {
+    if (opts.png) {
+      const rgba = readIcon(bytes);
+      if (!rgba) throw new Error('the cart has no icon');
+      writeFileSync(opts.png, encodePng(32, 32, rgba));
+    } else {
+      if (!rest[0]) throw new Error('give a 32×32 PNG');
+      writeFileSync(opts.o ?? file, setSection(bytes, 'wasm-ad-icon', iconFromPng(new Uint8Array(readFileSync(rest[0])))));
+    }
+    return 0;
+  }
+
   if (cmd === 'check') {
     const { errors, warnings, meta, info } = check(bytes);
     if (meta) console.log(`${meta.title}${meta.author ? ` by ${meta.author}` : ''} (spec ${meta.spec}), ${bytes.length} bytes`);
@@ -406,16 +732,32 @@ async function main([cmd, ...args]) {
     return 1;
   }
   const core = opts.core ?? fileURLToPath(new URL('../player/web/core.wasm', import.meta.url));
-  const host = await boot(bytes, { core, seed: Number(opts.seed ?? 1), onTrace: (m) => console.log(`trace: ${m}`) });
+  const replay = opts.replay ? decodeReplay(new Uint8Array(readFileSync(opts.replay))) : null;
+  const state = opts.state ? decodeState(new Uint8Array(readFileSync(opts.state))) : null;
+  if (replay) checkCart(replay.cart, bytes, opts.force);
+  if (state) checkCart(state.cart, bytes, opts.force);
+  if (state && opts.record) throw new Error('a replay starts at boot, so it cannot be recorded from a save state');
+  let save = replay ? replay.save : opts.save ? new Uint8Array(readFileSync(opts.save)) : null;
+  if (save && save.length !== A.SAVE_SIZE) throw new Error('a save file must be exactly 32 KB');
+  const seed = replay?.seed ?? Number(opts.seed ?? 1);
+  const host = await boot(bytes, { core, seed, save, state, onTrace: (m) => console.log(`trace: ${m}`) });
   const keys = parseKeys(opts.keys);
-  const frames = Number(opts.frames ?? 1);
+  const input = (f) => (replay ? replay.inputs[f] ?? [0, 0, 0, 0, 1] : keys(f));
+  const first = host.frames, frames = Number(opts.frames ?? (replay ? replay.frames - first : 1));
   const marks = new Set((opts.hash ?? '').split(',').filter(Boolean).map(Number));
   let pixels;
-  for (let f = 0; f < frames; f++) {
-    pixels = host.frame(keys(f));
+  const sound = [], recorded = [];
+  for (let f = first; f < first + frames; f++) {
+    recorded.push(input(f));
+    pixels = host.frame(input(f));
+    sound.push(host.sound);
     if (marks.has(f)) console.log(`frame ${f}: ${hash(pixels)}`);
   }
+  if (opts.record) writeFileSync(opts.record, encodeReplay({ cart: opts.unbound ? null : bytes, seed, save, inputs: recorded }));
+  if (opts['save-state']) writeFileSync(opts['save-state'], encodeState({ cart: bytes, frame: host.frames, seed: state?.seed ?? seed, memory: host.memory() }));
+  if (opts.hash) console.log(`sound: ${hash(...sound)}`);
   if (opts.ppm) writeFileSync(opts.ppm, ppm(pixels));
+  if (opts.wav) writeFileSync(opts.wav, wav(sound));
   return 0;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raskell/wasm-ad",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "AssemblyScript SDK for writing WASM-AD carts",
   "license": "MIT",
   "repository": {