@lewismoten/gamemaker-sandbox-tools 3.1.0 → 3.4.0

package/CHANGELOG.md

@@ -0,0 +1,44 @@
+# Changelog
+
+Changes to `@lewismoten/gamemaker-sandbox-tools`, released as `tools-v*` tags. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+## [3.4.0] - 2026-11-07
+
+Most of the game-building kit moves into the package: a seeded level generator for dungeons, forests, towns, castles
+and side views, block roles, nonsense-talk voices, and tools for FLI shrinking, palettes, disk diffs, embroidery, and
+3D-printable and laser models.
+
+### Added
+
+- `kit/levelGen`, a seeded level generator with no DOM: dungeons, forests, homes, shops, castles, towns, overworlds and platform side views, with each key reachable before its lock.
+- Shared game-building APIs move into the package: DOS disk writing, native character and text-screen builders, route checks, the engine-backed simulator and more.
+- `kit/blockRoles`, `kit/mumble` (nonsense talk as a .VOC), `kit/levelGrid` and `image/animatedGif`.
+- Mesh, embroidery and laser-kit tools: surface nets and STL files, a stitch generator with DST, EXP and PES files, finger-joint panels and a wooden-nickel builder.
+- `diskDiff` and `kit/fliShrink`.
+
+### Changed
+
+- Game builds replace `disk/` files in place, and `kit/tar` is browser-safe.
+
+### Fixed
+
+- `kit/gameSim`: a scene with a blank character or character-blocks slot keeps the last scene's, as PLAYGAME's loadscene does.
+
+Full list: [changes/release/tools/3.4.0.md](https://github.com/lewismoten/GameMaker-SandboxEdition/blob/tools-v3.4.0/changes/release/tools/3.4.0.md)
+
+## [3.1.0] - 2026-10-29
+
+The first release of the development tools as an npm package: drawing, palettes, fonts, music and PNG builders.
+
+### Added
+
+- The tools package, scoped as `@lewismoten/gamemaker-sandbox-tools` and published to GitHub Packages from version tags.
+- CP437 and micro text drawn as indexed game pixels, with documented font, text-effect and lighting APIs.
+- Reusable color ramps and time-of-day VGA lighting.
+
+[Unreleased]: https://github.com/lewismoten/GameMaker-SandboxEdition/compare/tools-v3.4.0...HEAD
+[3.4.0]: https://github.com/lewismoten/GameMaker-SandboxEdition/compare/tools-v3.1.0...tools-v3.4.0
+[3.1.0]: https://github.com/lewismoten/GameMaker-SandboxEdition/releases/tag/tools-v3.1.0

package/NOTICE.md

@@ -1,13 +1,13 @@
 # Notices
 
-This development toolkit is extracted from Game-Maker: Sandbox Edition by Lewis Moten, released under the MIT License. It includes the fork's native format codecs, drawing and audio builders, and headless reference simulation.
+This development toolkit is extracted from Game-Maker: Sandbox Edition by Lewis Moten, released under the MIT License. It owns the drawing and audio builders and headless reference simulation; shared native format codecs, runtime types and CP437 font data come through its declared engine dependency, and archive support through its declared archives dependency.
 
 The reference engine is a TypeScript port of RSD Game-Maker 3.0 by Recreational Software Designs: G. Andrew Stone, G. Oliver Stone, Oliver Stone Jr. and Joan Stone. Andy Stone released the original source under the MIT License in 2014. The original copyright notice is retained in LICENSE. Peter Savage wrote the original Sound Blaster voice-file and joystick routines.
 
 ## Fonts
 
-- **8×8 ASCII and selected CP437 glyphs:** Daniel Hepper's [font8x8](https://github.com/dhepper/font8x8), specifically `font8x8_basic`, `font8x8_ext_latin`, `font8x8_greek`, and `font8x8_misc`. Each upstream header declares **Public Domain** and credits **Marcel Sondaar** and **International Business Machines (public domain VGA fonts)** as its basis. See the [upstream source header](https://github.com/dhepper/font8x8/blob/master/font8x8_basic.h). This data is used in `web/src/gfx/font8x8.ts` and the marked entries of `web/src/gfx/cp437Glyphs.ts`, exposed here through `FONT8X8` and `FONT_CP437`.
-- **Additional CP437 glyphs:** the other symbols and box-drawing glyphs in `web/src/gfx/cp437Glyphs.ts` were drawn for Game-Maker: Sandbox Edition using **Anthropic Claude Opus 5.5**, under **Lewis Moten's** direction, and are distributed under the project's **MIT License**. These additions were not copied from IBM's ROM; the full 256-glyph table combines them with the public-domain data above.
+- **8×8 ASCII and selected CP437 glyphs:** Daniel Hepper's [font8x8](https://github.com/dhepper/font8x8), specifically `font8x8_basic`, `font8x8_ext_latin`, `font8x8_greek`, and `font8x8_misc`. Each upstream header declares **Public Domain** and credits **Marcel Sondaar** and **International Business Machines (public domain VGA fonts)** as its basis. See the [upstream source header](https://github.com/dhepper/font8x8/blob/master/font8x8_basic.h). This data is used in `web/packages/engine/src/gfx/font8x8.ts` and the marked entries of `web/packages/engine/src/gfx/cp437Glyphs.ts`, exposed here through `FONT8X8` and `FONT_CP437`.
+- **Additional CP437 glyphs:** the other symbols and box-drawing glyphs in `web/packages/engine/src/gfx/cp437Glyphs.ts` were drawn for Game-Maker: Sandbox Edition using **Anthropic Claude Opus 5.5**, under **Lewis Moten's** direction, and are distributed under the project's **MIT License**. These additions were not copied from IBM's ROM; the full 256-glyph table combines them with the public-domain data above.
 - **3×5 micro font (`MICRO_GLYPHS`):** the project's small sign font, introduced in `games/teddy/draw.ts` by **Lewis Moten using Anthropic Claude Opus 5.5**, then maintained in `games/teddy/src/art/draw.ts`. Its provenance is recorded in [commit 7241036f49cab9dea52f58541e30ce6c9ce86052](https://github.com/lewismoten/GameMaker-SandboxEdition/commit/7241036f49cab9dea52f58541e30ce6c9ce86052). It is distributed under the project's **MIT License**, not the public-domain dedication of Hepper's font. **OpenAI Codex (GPT-6/6.1)** extracted the table into this toolkit's `src/microFont.ts` and added the reusable rendering APIs under Lewis's direction.
 
 ## Other formats and tooling
@@ -17,3 +17,105 @@ The lighting presets were written for this project. GIF, FLI, Creative Voice Fil
 The underlying web port and game-building tools were written with Anthropic Claude Opus 5.5 under Lewis Moten's direction. OpenAI Codex (GPT-6/6.1) prepared the toolkit packaging, consumer migration, documentation, and verification under his direction.
 
 No game-specific artwork, palettes, characters, recordings, or complete games are included. Consumers supply and credit their own content.
+
+## Optional source audio conversion
+
+`audio-files` invokes an independently installed [FFmpeg](https://ffmpeg.org/) executable
+by the FFmpeg developers; no FFmpeg code or binary is included in this package. FFmpeg is
+LGPL-2.1-or-later, or GPL-2.0-or-later when its GPL components are enabled; see its
+[licensing information](https://ffmpeg.org/legal.html). FLAC is the lossless audio format
+maintained by Xiph.Org; its [FAQ](https://xiph.org/flac/faq.html) describes sample-exact
+compression. The process wrapper and VOC conversion APIs were implemented with OpenAI
+Codex under Lewis Moten's direction, using this project's existing native VOC encoder.
+
+The native mono 8-bit PCM WAV reader uses RIFF/WAVE chunk layout and PCM format fields
+from [Microsoft's WAVEFORMATEX documentation](https://learn.microsoft.com/en-us/windows/win32/api/mmeapi/ns-mmeapi-waveformatex).
+No Microsoft implementation code is included. The reader was implemented with OpenAI
+Codex under Lewis Moten's direction and is distributed under this project's MIT License.
+
+## Additional micro-font glyphs and variants
+
+The extended rounded repertoire and square technical-label variant are project-owned
+font data by Lewis Moten using Anthropic Claude Opus 5.5, under this project's MIT License.
+They consolidate the existing tables in the public games' art helpers (including the
+expanded punctuation in `games/brief/src/art/draw.ts` and `games/blaster/src/art/draw.ts`,
+and the cent sign in `games/year2000/src/art/font.ts`). The square face originated in
+[the original Ohm Sweet Ohm drawing helpers](https://github.com/lewismoten/GameMaker-SandboxEdition/commit/1a746bffa).
+OpenAI Codex consolidated the data and APIs under Lewis Moten's direction.
+These fonts are distinct from the separately credited public-domain CP437 glyphs above.
+
+## Shared rendering methods and stroke lettering
+
+The rounded stroke lettering in `kit/sdftext` is project font data by Lewis Moten using
+Anthropic Claude Opus 5.5, introduced with the original software-rendered logo helpers
+([source commit](https://github.com/lewismoten/GameMaker-SandboxEdition/commit/7bb0e7b7c)).
+It is distributed under the project's MIT License, alongside the project-owned rendering,
+quantization, synthesis and object-building code extracted from `games/kit`. OpenAI Codex
+consolidated these modules and their consumers under Lewis Moten's direction.
+
+Method references: Paul S. Heckbert, *Color Image Quantization for Frame Buffer Display*
+([author's publication list](https://www.cs.cmu.edu/~ph/)), for median-cut quantization;
+John C. Hart, *Sphere Tracing: A Geometric Method for the Antialiased Ray Tracing of
+Implicit Surfaces* ([paper](https://graphics.stanford.edu/courses/cs348b-20-spring-content/uploads/hart.pdf)),
+for distance-based sphere tracing. The implementations and project font data here use
+the project's MIT License.
+
+## Original CD Library palette
+
+`src/palettes.ts` embeds a byte-for-byte copy of `cd/gameware/library/default.pal`
+from the original RSD Game-Maker CD, by Recreational Software Designs (G. Andrew
+Stone, G. Oliver Stone, Oliver Stone Jr. and Joan Stone). It is distributed under
+the original project's MIT License; this package retains that license in `LICENSE`.
+[Source palette](https://github.com/lewismoten/GameMaker-SandboxEdition/blob/master/cd/gameware/library/default.pal).
+OpenAI Codex packaged this data and the fresh-copy API under Lewis Moten's direction.
+
+## Ready-made palette reference data
+
+`src/palettePresetData.ts` contains RGB swatches adapted to six-bit VGA by OpenAI Codex
+under Lewis Moten's direction. Analog console colors are reference approximations, not
+a claim that every television or hardware revision produces identical RGB. No third-party
+font, image, emulator or generator executable is bundled with these swatches.
+
+- Atari 2600 NTSC and PAL: Ricardo Cancho Niemietz, 2008, released by the author into the
+  public domain (with unrestricted-use fallback). Swatches sampled at the centers of the
+  16×8 color charts; NTSC retains 128 hardware slots, including one duplicated RGB value;
+  PAL's repeated gray columns are removed to give 104 slots. Sources and release statements:
+  [NTSC](https://commons.wikimedia.org/wiki/File:Atari2600_NTSC_palette.png),
+  [PAL](https://commons.wikimedia.org/wiki/File:Atari2600_PAL_palette.png).
+- NES: Persune, Pally, MIT No Attribution (MIT-0), copyright 2024 Persune. The first 64 RGB
+  entries (no emphasis) of `docs/NESDev/2C02G_U_wiki.pal` are reduced to 54 distinct swatches.
+  [Source at commit 9635e9b71505f969014c7efa15dca3ba35ade871](https://github.com/Gumball2415/pally/blob/9635e9b71505f969014c7efa15dca3ba35ade871/docs/NESDev/2C02G_U_wiki.pal),
+  [license](https://github.com/Gumball2415/pally/blob/9635e9b71505f969014c7efa15dca3ba35ade871/LICENSE).
+- Commodore 64 NTSC CXA2025 reference: Groepaz, unrestricted free use, including
+  redistribution, commercial use and modification; attribution appreciated. Sixteen
+  color-bar centers sampled from the reference, with color 0 normalized to menu black.
+  [Author's reference](https://hitmen.c02.at/linked/c64_ntsc_cxa2025.bmp.png),
+  [permission and provenance](https://commons.wikimedia.org/wiki/File:C64_ntsc_cxa2025.bmp.png).
+
+The RGBI and SMS bit mappings are project-owned MIT implementations of hardware facts,
+referencing IBM's *Technical Reference: Options and Adapters*, volume 2, April 1984
+([manufacturer's manual](https://bitsavers.org/pdf/ibm/pc/cards/Technical_Reference_Options_and_Adapters_Volume_2_Apr84.pdf)),
+and Maxim / SMS Power contributors' [palette documentation](https://www.smspower.org/Development/Palette).
+Monochrome ramps, the EGA skin/hair additions and LCD-green approximations were designed
+for this project by Lewis Moten using OpenAI Codex, under the project's MIT License.
+
+Pally's MIT-0 license:
+
+```text
+MIT No Attribution
+
+Copyright 2024 Persune
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this
+software and associated documentation files (the "Software"), to deal in the Software
+without restriction, including without limitation the rights to use, copy, modify,
+merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+```

package/README.md

@@ -1,17 +1,33 @@
 # @lewismoten/gamemaker-sandbox-tools
 
-Development-only tools for creating and checking native RSD Game-Maker data. Browser playback belongs to `@lewismoten/gamemaker-sandbox-engine`; this package has no game artwork, recordings, characters, or palettes.
+Tools for creating and checking native RSD Game-Maker data. Browser playback belongs to `@lewismoten/gamemaker-sandbox-engine`; this package has no game artwork, recordings, characters, or game-specific palettes.
 
-Requires Node.js 22.12 or newer. Install with `npm install --save-dev @lewismoten/gamemaker-sandbox-tools` once published. Until publication, `npm pack` produces a self-contained installation candidate.
+Requires Node.js 22.12 or newer. Install as a development dependency from your configured npm registry:
+
+```sh
+npm install --save-dev @lewismoten/gamemaker-sandbox-tools
+```
+
+If your registry requires authentication or a scope mapping, configure npm using that registry's instructions.
 
 ## APIs
 
 - `formats/blocks`, `character`, `game`, `map`, `monster`, `palette`, `gif`, `graphicScripts`, `sound`, `fli`, `fliLimits`, `voc`, `recording`, and `cmf`: native readers, writers, types, and limits. Each is a separate `formats/<name>` subpath.
+- `gif-shrink`: `shrinkGif(bytes)` returns a smaller GIF with a trimmed color table, or `undefined` when it can't shrink without changing what PLAYGAME shows.
 - `drawing`: indexed pixels, VGA palette builders, font drawing, shading, compositing, and cartoon reels.
 - `audio`: original FM instrument presets, CMF composition, PC speaker effects, and VOC synthesis.
-- `images`: indexed PNG encoding and CRC-32.
+- `images`: indexed PNG encoding, CRC-32, color reduction, indexed drawing and picture transforms.
 - `simulation`: headless `Sim`, `GameSim`, `readDisk`, `diskSim`, and `newCharInfo` for fixture checks. This includes the reference simulation; it does not replace testing the browser engine package.
 
+The browser-safe `images` entry also exports `Pixels`, `flipX`, `flipY`, `turn90`,
+`turn180`, and `shiftPixels` for indexed pictures of any size. Quarter turns return a
+picture with exchanged dimensions. `mirrorAll`, `line`, `box`, and `floodFill` support
+painting across tile boundaries. Fill accepts optional mask and writer callbacks for
+missing cells or repeated references to the same tile; traversal uses the original
+pixels so writes to shared cells do not break the fill.
+Shift offsets use whole pixels. Fill ignores seeds outside the image, inside a masked
+cell, or at non-integer coordinates; mismatched buffer dimensions throw a `RangeError`.
+
 ```ts
 import { emptyBlock, serializeBlocks } from '@lewismoten/gamemaker-sandbox-tools/formats/blocks';
 import { Pixels } from '@lewismoten/gamemaker-sandbox-tools/drawing';
@@ -21,7 +37,9 @@ blocks[0].pixels.set(new Pixels(20, 20, 1).px);
 const data = serializeBlocks(blocks);
 ```
 
-Keep these imports in build scripts and tests. The package explicitly rejects browser imports. Generated game data and your own copied assets belong in the consuming project.
+`medianCutRgba` from `images` chooses up to a requested 1–256 eight-bit RGB colors from portable RGBA image buffers. It needs no canvas or DOM; flatten transparency onto the intended background before calling it. The palette is based on pixel colors and their frequency, not unused color-table entries.
+
+Keep drawing and simulation imports in Node build scripts and tests; those entry points reject browser imports. Browser-safe `audio`, `images`, `text`, `colors`, `microFont`, `music/compose`, `image/png`, `kit/tar`, `kit/blockRoles` and `menu-version` (stamps "v1.0" on a game menu picture) entry points also support the web editor. Playback through the engine and archives packages does not load this toolkit. Generated game data and your own copied assets belong in the consuming project.
 
 ## Fonts, text images, and lighting
 
@@ -52,11 +70,283 @@ const lit = lightColor([100, 180, 80], 'night');
 
 `outline` and `dropShadow` also decorate `Pixels` sprites within their existing bounds; edges clip. The existing sprite outline uses four neighbors, while text outlines include all eight neighbors.
 
-`colorRamp` returns eight-bit RGB stops without allocating palette entries. `PaletteBuilder.ramp` allocates named ramps in a six-bit VGA palette. `TIME_OF_DAY_LIGHT`, `TIME_OF_DAY_SKY`, and `lightColor` provide morning, noon, afternoon, sunset, night, and stage-light presets. `adjustPalette` returns an adjusted native VGA palette without mutating its input. By default it preserves indexes 0 and 255; pass a custom index list to protect glowing colors or designer inks. Game-specific ramp names and cast colors belong in the consumer.
+`colorRamp` returns eight-bit RGB stops without allocating palette entries. `rgbToHsv` and `hsvToRgb` convert eight-bit RGB and hue in degrees with saturation/value in 0..1, without changing inputs. `PaletteBuilder.ramp` allocates named ramps in a six-bit VGA palette. `TIME_OF_DAY_LIGHT`, `TIME_OF_DAY_SKY`, and `lightColor` provide morning, noon, afternoon, sunset, night, and stage-light presets. `adjustPalette` returns an adjusted native VGA palette without mutating its input. By default it preserves indexes 0 and 255; pass a custom index list to protect glowing colors or designer inks. Game-specific ramp names and cast colors belong in the consumer.
+
+## Source audio files to VOC (Node.js)
+
+Mono unsigned 8-bit PCM WAV files at the requested rate decode directly in Node.js, with
+no additional software. For Ogg, FLAC, other WAV variants or resampling, install
+[FFmpeg](https://ffmpeg.org/download.html) separately and make `ffmpeg` available on PATH,
+or pass its executable path as `ffmpegPath`. No decoder binary is bundled, and browser
+playback gains no dependency.
+
+```ts
+import { audioFileToVoc, decodeAudioFile } from '@lewismoten/gamemaker-sandbox-tools/audio-files';
+import { writeFileSync } from 'node:fs';
+
+writeFileSync('VOICE.VOC', audioFileToVoc(new URL('./voice.wav', import.meta.url), {
+  sampleRate: 11025, maxBytes: 39999,
+}));
+const samples = decodeAudioFile('voice.ogg', { sampleRate: 8000 });
+```
+
+FLAC, Ogg, WAV and other formats supported by your FFmpeg build are accepted. Output is
+mono at the requested sample rate (11025 Hz by default). VOC conversion defaults to a
+65535-byte DOS limit; oversized clips fail instead of being shortened. `decodeAudioFile`
+returns samples for mixing or other authoring operations, bounded by `maxSamples`
+(default 16 MiB). Both functions accept `timeoutMs` (default 30000).
+
+Use PCM WAV sources for inline GitHub audio previews and sample-exact native game builds.
+Lossless FLAC input is also supported at its original sample rate.
+The converter disables dithering and uses the inverse of the native VOC encoder's byte
+mapping. Lossy sources such as Ogg Vorbis are supported for new audio, but cannot recreate
+a previous recording's exact samples. Source `.wav`/`.ogg`/`.flac` files are authoring assets; only
+8.3-named `.VOC` files belong on the generated DOS disk.
+
+### Extended micro fonts
+
+`microFont` exports `MICRO_GLYPHS`, `MICRO_SQUARE_GLYPHS`, and `microGlyphs(characters, square?)`.
+The shared repertoire includes the sign and technical-label additions such as `µ`, `¢`,
+`#`, `%`, `@`, `~`, quotes, underscore, and backslash. Both rounded and square letterforms
+are preserved. `renderText(text, {font: 'micro-square'})` selects the square style;
+`glyphRows(code, 'micro-square')` returns its five rows. `microGlyphs` can select an exact
+legacy repertoire when an existing game's unsupported-character behavior must stay the same.
+See NOTICE.md for the source and license of both project fonts.
+
+### Shared text renderers
+
+`drawing` exports `createMicroText` and `createPcText` for adapting existing lettering
+without copying drawing loops. Micro text accepts a glyph repertoire, fallback, spacing,
+and optional consumer-owned multicolor glyphs. PC text accepts custom glyph artwork,
+scaled or absolute shadow offsets, and outline spacing. Both report ink to the existing
+text-bounds audit. The default `text`, `outlined`, and `centered` retain their old behavior.
+
+### Sprite composition
+
+`drawing` also exports ASCII sprites, nearest-pixel rotations and reflections, and
+`resampleBlit` for fractional scaling. `outline` can ignore existing outline-colored
+neighbors or use an explicit transparent index; `outlineInPlace` keeps the original
+canvas. `scaleBlitTransparent` selects transparency without changing its mirroring flag.
+`bevel` accepts separate top/left/bottom/right shade offsets, and `pool` paints radial light.
+
+`microWidth` measures visible cells with zero width for an empty string; `microAdvance`
+retains the older cell-advance formula when preserving legacy layout. Default micro
+drawing recognizes direct symbols such as `µ` before trying their uppercase forms.
+
+### Palette and texture helpers
+
+`drawing` and `kit/coverPaint` expose seeded tileable value noise, RGB mixing, smoothstep,
+and clamping. `kit/palRamps` exports `Pal` and `wrap` for named palette ramps.
+
+### Software rendering
+
+`kit/quantize` chooses shared VGA palettes and ordered dithering for RGB frames.
+`kit/sdftext` provides rounded stroke lettering, distance grids and extrusion; `kit/raytrace`
+provides shapes, transforms, cameras and lighting. Consumers supply their own scenes.
+The stroke glyphs, implementation provenance and method references are in NOTICE.md.
+
+### Archives for downloads
+
+`kit/blockRoles` is the block-role vocabulary (wall, door, locked door and key with a lock number, furniture with a facing...), `suggestRoles` (guesses from a block's behavior and picture; it never decides) and `cleanRoles`/`packRoles` for editor companion data; it needs no DOM and changes no game bytes.
+
+`kit/levelGen` draws a dungeon (binary space partition: rooms joined by corridors) or a forest (cellular automata on a tree mask, clearings, a winding path) into a rectangle of a map from the blocks that hold roles. `checkNeeds(kind, roles)` says which roles a kind needs and which it uses when present; `generate(roles, { kind, seed, rect })` returns block numbers, the plain kind of each cell, the cells a terrain brush should give edges to, and a proposed entry and exit (never applied or linked), or a plain message when a needed role is missing; `offerSeed` gives the four seeds of a set of offers; `verifyReach` checks every open cell can be reached from the entry. Dungeons also get locked doors (a one-wide passage that cuts the entry from the exit, with the matching key placed in the part still reachable with that lock and every later one shut), treasure and a heart in corners and dead ends, and `monsters` (pass monster numbers in `params.monsters`; spread out, five or more steps from the entry); forests get treasure, a heart and monsters. `proveResult` plays the keys out and checks reach, key-before-lock and that everything can be collected. It needs no DOM, runs in a Worker, and the same seed always gives the same blocks. It writes no game data: the map editor places the cells. `town` (a winding main street between two gates, cross streets that end on one side only, a plaza, and houses with a door on the street) and `overworld` (value noise for sea level, mountains and forest, periodic when `GenParams.wrap` is set so the land lines up across the seam; a road cut between three to five sites) also return `links`: doors and sites a person could link to other scenes (`SceneLink`: cell, kind, label). They are proposals only; nothing creates a scene or a link, and `proveResult` checks each can be reached from the entry (`linked`).
+
+`generatePlatform({ roles, hero, seed, rect, difficulty, monsters })` draws a **side view** (platform) level and is meant for a game's `build.ts` as well as the editor. `hero` is the parsed character file (`hero.chr`): `heroPhysics(chr)` reads his walk speed, the jump's upward push (the momentum sequence) and whether he climbs, and plays them with the engine's gravity (one pixel a tick back, at most 11 pixels a tick). Nothing about the hero is written in the generator, so a game with a bigger or smaller jump gets bigger or smaller pits. `capability(physics)` measures, with the reach model, the highest step he jumps onto and the widest pit he clears on level ground (and spikes); `difficulty` (percent, 80 by default) is the share of those the layout asks. The layout has ground with pits (spiked at the bottom with a hazard block), steps up and down, towers with a ladder (only with a ladder block and a hero who climbs), spikes to jump over, stepping stones across wide pits, ledges to jump up to (`platform` blocks, solid on top only), coins where the jumps pass, a heart at the highest place he can stand, one tall locked door with its key on an earlier stretch, and monsters on the long stretches. It needs wall and sky blocks; every other role is optional. The entry is on the left and the exit on the right (proposals; nothing is linked). The result's `platform.proof` says whether the reach model (`reachFrom`: walks, jumps with every steering length, falls off edges and ladders tick by tick against the cells) proved the exit reachable, every coin, heart and key touchable, and the locked door a real barrier (the exit unreachable until the key); a layout that cannot be proven is drawn again, easier. The same seed always draws the same layout; `proveResult` and the Generate dialog's chip use the proof. The editor goes one step further (`editors/map/generate/platformBot.ts`): a bot presses the hero's own keys along the model's route on the real engine and the chip says "Bot won". Monsters and fun are not judged.
+
+`kit/tar` writes and reads POSIX ustar archives (`createTar`, `createTarGz`, `readTar`). Entries keep
+their Unix mode, so a game folder's programs and scripts unpack executable, and names over 100
+bytes use the header's prefix field. It has no dependencies and runs in Node and browsers
+(`.tar.gz` uses the platform's `CompressionStream`).
+
+### Native object builders
+
+`kit/laserJoints` makes flat wooden-box panel outlines for the laser kits: finger (box) joints whose two sides mesh,
+rectilinear outlines from rectangles, and mitered kerf offsets (`jointOutline`, `outlineFromRects`, `offsetPoly`).
+`kit/laserLayout` has `Part` (one flat piece with named elements, kerf applied, spacing-checked with
+`kit/laserClearance`) and `packRows`, which lays parts out on a Glowforge-bed sheet and throws if they do not fit.
+Games' laser kits (`games/sleuth/laser/`) build on them with `kit/laserSvg`, `laserPixels` and `laserPreview`.
+
+`embroidery/*` turns a vector design into machine-embroidery files. A `Design` is color blocks of items: `fill` (polygons), `satin` (a center line and a width) and `run`. `compile` sews each item with an underlay (an edge walk inside the shape, loose rows under big shapes, a center walk and zigzag under satin) and then its top stitching, and adds the jumps, trims, small tie stitches, color stops and an end, capping every stitch at 7 mm (`Params`: fill rows 0.4 mm apart with 3.5 mm stitches whose holes are staggered in thirds, satin 0.4 mm apart, 0.3 mm of pull compensation on satin and 0.15 mm on fills, a satin wider than 7 mm sewn as lanes). `fill` makes the tatami rows (a notched shape becomes several chains), `satin` the zigzag columns and their underlay, `strokeFont` a single-line capital alphabet that `arcText` bends around a circle for satin lettering (draw it 5 mm tall or more), and `geom` the outlines (`circle`, `star`, `inset`). `dst` (Tajima: a text header and 3-byte ternary records, a trim written as tiny jumps), `exp` (Melco, Bernina) and `pes` (Brother, Baby Lock: PES v1 written by hand, its PEC section with 7- and 12-bit moves, thread-chart indices and bitmaps) each write and read a `Pattern` (the readers are for checks). `units` turns a pattern into 0.1 mm moves and splits long jumps, `validate` reports stitch count, longest stitch, extents, jumps and color changes against a hoop, `simulate` draws the stitches thread by thread, and `svg` writes the design as a vector drawing in millimeters. None of it has been run on a real machine; sew a test on scrap first. `games/maximus/patch/` is the first design.
+
+`kit/actors` builds character sequences and monster paths. `kit/screenText` validates
+30-column, 16-line DOS text pages and looks up caller-supplied named sprites.
+
+`kit/road3d` provides three-lane perspective geometry, timed spawner chains and sprite
+shrinking. `kit/saveSlots` provides PLAYGAME's save-slot rectangles and their backgrounds.
+These helpers take the consuming game's data and palette.
+
+### Image preparation and previews
+
+`kit/photo` reads a caller-supplied JPEG (`readScan`) and provides resampling, toning,
+quantization, dithering and indexed photo composition. No photographs are included.
+`kit/png` writes synchronous RGB preview PNGs with a checkerboard for transparent pixels
+and builds block sheets. `kit/levelPicture` renders a level region with its placed monsters, and `kit/levelGrid` is a character grid to paint a level in code.
+These Node build helpers complement the browser-safe `images` API.
+
+### Sound and arrangement helpers
 
-## Build and inspect
+`audio` / `kit/synthParts` expose low-pass noise, envelopes, gates and filtering.
+`kit/song` builds CMF arrangements from caller-supplied sections; `kit/songFx` adds native
+CMF swells, arpeggios, glides, echoes and rhythm effects. Instrument presets are original
+project data under the MIT License; recordings and complete songs are not included.
 
-From this directory, with the repository's web development dependencies installed:
+### Mumble-speak (nonsense talk as VOC)
+
+`kit/mumble` is a small formant synthesizer that says nonsense, the way a game of 1994 might hum a character's
+talk. A line is a list of syllables `[vowel, fromHz, toHz, seconds, restSeconds?]`. `mumble(line, { rate, gain })`
+returns samples in -1..1, `mumbleVoc(line)` returns an 8-bit mono 11 kHz .VOC, and `syllablesFromText(text, { pitch, speed, seed })`
+turns a line of text into syllables (vowels from its letters, so the same line and seed mumble the same way;
+a question rises, a sentence falls). `MUMBLE_VOICES` has `bright`, `deep` and `small` settings.
+
+```ts
+import { MUMBLE_VOICES, mumbleVoc, syllablesFromText } from '@lewismoten/gamemaker-sandbox-tools/kit/mumble';
+
+const voc = mumbleVoc(syllablesFromText('Welcome to the show!', MUMBLE_VOICES.bright)); // write it as HELLO.VOC
+```
+
+### Native animations and demos
+
+`kit/fadeOut` adds palette-only FLI fades. `kit/fliClips` splits long animations at stable
+palette boundaries and builds their slide-list entries; its opt-in `ClipOptions` leave out
+the closing ring frame no player shows (`noLoopFrame`, also an `encodeFli` option) and put
+cuts where a whole frame costs the fewest extra bytes (`cheapCuts`), and run `shrink` steps first.
+`kit/fliShrink` is the size report (`fliReport`: bytes per chunk type per frame, and why) and the shrink
+steps (`sparsePalettesStep` lossless; `holdStillStep`, `snapColorsStep`, `maxColorsStep`,
+`flattenDitherStep`, `dropFramesStep` lossy), each returning the new frames, the bytes saved and how
+visible the change is (`Visibility`: mean, worst, changed share); `decodeFli`/`encodeFrames` convert,
+`shrinkFrames` chains steps. `kit/recordedDemo` turns delta/key
+pairs into a native title demo with configurable Escape press and release delays.
+
+### Shared block sets
+
+`kit/shareBlocks` merges several scenes' background blocks into one `.BBL`: only the blocks a
+map uses (and what they change into) are kept, matching blocks and rings become one, a pinned
+number (such as a felt egg's) stays put, and each scene's map is renumbered.
+
+### Look-alike blocks
+
+`findLookAlikes` finds background blocks that are drawn the same colors under every palette a set
+is shown with and play the same (it keeps what they turn into in step), and lists blocks that
+share a shape in other colors without joining them: a scene has one palette. `applyFold` removes
+the folded blocks and renumbers maps and links. Import from `@lewismoten/gamemaker-sandbox-tools/look-alike`.
+
+### Versions as deltas
+
+`diffVersions`, `applyDelta` and `deltaSize` keep a game's earlier versions like a git repository: a binary file
+is a list of byte-range patches (one recolored block or map cell is a few bytes), a text file (lst, txt, json,
+md...) a line patch, so each version costs only what changed. Lossless for any bytes. Import from
+`@lewismoten/gamemaker-sandbox-tools/delta`.
+
+### Color reduction
+
+`reduceBlocks` moves the pixels of blocks that use colors outside their allowed set (a block type's reserved
+range plus the colors nobody reserved) to the nearest allowed color, and scores the change in CIELAB delta E
+(mean over changed pixels, worst pixel; a block is flagged above 6 mean or 20 worst, thresholds a guess). Index
+0 and 255 never move. Import from `@lewismoten/gamemaker-sandbox-tools/color-reduce`.
+
+### Palette reservations
+
+`planRanges` proposes, for a game with no reservations, a range of color numbers for monsters and one for
+characters (sized by the different colors their blocks draw, at most 48 each, starting at 16 because 1-15 look
+like the engine's own interface colors, placed where the fewest other blocks already draw). `syncRange` makes a
+reserved range identical in every palette a role's files are shown with: the role's colors move into the range
+(pixels renumbered, palettes updated), and colors beyond the range's size become the nearest kept one, all scored
+in delta E. Import from `@lewismoten/gamemaker-sandbox-tools/palette-reserve`.
+
+### Joining block sets
+
+`mergeBackgroundSets` moves one background set's drawn blocks into another's free slots (reusing an
+identical block already there) and renumbers the moved set's maps; the kept set is not renumbered.
+Pickups, required and starting items and block 0 keep their number or the join is refused.
+Import from `@lewismoten/gamemaker-sandbox-tools/block-merge`.
+
+### Meshes for 3D printing
+
+`mesh/surfaceNets` turns a signed distance field (negative inside) into a closed triangle mesh
+(`surfaceNets(field, { min, max, cell })`; it retries with a shifted grid until every edge is in exactly two
+triangles), `mesh/stl` writes and reads binary STL (`writeStl`, `readStl`; a color per triangle goes in the
+attribute bytes the VisCAM way, which slicers ignore) and `mesh/meshCheck` reports whether a mesh is closed,
+how many pieces it has, its size and volume (`inspectMesh`). `mesh/tetraMesh` is the other mesher (four times
+the triangles, but closed for any field, and neighbors meet on the same vertices); `mesh/overhang` measures what
+an FDM printer cannot print (`overhang`) and builds the support pillars as a body of their own (`supportBody`);
+`mesh/colorBodies` picks at most four colors from a colored mesh (`pickPalette`) and splits the solid into one
+closed body per color (`colorBodies`, thinned and grown to the volume you give it); `mesh/decimate` takes the triangles a
+closed mesh does not need out by quadric edge collapse (`decimate(mesh, { maxError })`: stays closed and in one piece, and the
+borders between a triangle color and the next stay put); `mesh/sampledField` samples a field once on a grid and reads it back
+by trilinear interpolation, for the many passes over one figure (`sampledField`); `mesh/threeMf` writes and reads multi-color 3MF files (`write3mf(parts,
+title, codec)`, `read3mf`: parts are a mesh and a color), over the small ZIP writer `mesh/zipFile` (pass Node's
+`deflateRawSync` as `codec.deflate` to compress). `pack/meshPack` packs a binary STL losslessly into a much smaller file
+(`packStl`, `unpackStl`: a table of distinct corners in byte planes, corner numbers as varints, normals worked out again;
+deflate the result) and gives the pieces (`toPlanes`, `packIndices`) for other mesh files; `pack/threeMfPack` does the same
+for a 3MF `write3mf` wrote (`pack3mf`, `unpack3mf`: corners in thousandths, as the file has them; `threeMfEntries` makes
+its inner files again, the same bytes, to zip with any deflate). `mesh/voxel` meshes filled voxels (`voxelMesh`: coplanar faces merged into
+rectangles, no T-junctions, so it stays closed) and `mesh/pixelFigure` turns a pixel sprite into a standee on a base with at
+most four color bodies (`pixelFigure`). They are browser safe, except `mesh/trinketTool`.
+
+Trinkets made of distance fields (Depth Perception's, Quest for the Round Tuit's) share one pipeline, all in millimeters
+with the floor at z = 0: `mesh/sdfShapes` has the 2D shapes (circle, rounded rectangle, polygon, ring, capsule and
+`pixelText2`, lettering in the 3x5 micro font), `extrude` and the solid combiners; `mesh/strokeText` (`strokeText2`, `ringText2`) letters raised or sunk text in smooth capsule strokes (capitals, digits, marks; use it instead of the stair-stepped `pixelText2` for anything printed); `mesh/figureShapes` has ellipsoids, round cones, a smooth union and `place3` for 3D figures; `mesh/trinketKinds` builds a `plate` (coin,
+token, key-chain tag or badge: outline, raised rim, raised relief, sunk art, holes, a pin-back `pocket` from `pinBack`), a key-chain `ringTab`, a faceted `gem` (also a crystal shard) and a `die`; `mesh/fieldTrinket`
+(`meshFieldTrinket`) meshes a field with a color per triangle and gives the checks (eroded pieces and specks, overhang),
+up to four color bodies and supports; `mesh/trinketTool` (`runTrinketTool`, Node only) writes the STL, 3MF and manifest.json
+of a game's trinkets, with a source key so an unchanged game is skipped, in worker threads when `--workers N` runs a bundle.
+A game keeps its designs in `games/<id>/src/trinkets/` (`TRINKETS` and `makeTrinket`) and a four-line `tools/trinkets.ts`.
+Surface nets need a cell smaller than half of any gap between pieces (a 0.6 mm kerf wants a 0.26 mm cell).
+
+### Disk comparison
+
+`diffDisks(a, b)` takes two `Map<name, bytes>` disks and returns the added, removed and changed files, with a plain-text
+summary per changed file by type (`.gam`, `.pal`, blocks, `.map`, `.chr`, `.mon`, text, GIF, FLI, VOC, else bytes).
+`formatDiff` prints it, sorted and the same every time. Import from
+`@lewismoten/gamemaker-sandbox-tools/disk-diff`; `npm run disk:diff` in `web/` is the command line.
+`releaseNotes(diff)` (`.../release-notes`) turns a diff into short paste-ready text grouped by kind of file, such as
+"Changed 2 maps (A.MAP, B.MAP) and 1 palette (X.PAL). Added 1 sound (SONG3.VOC)."; `disk:diff -- --notes` prints it.
+
+### Headless checking
+
+`kit/hopBot` provides configurable hopping, steering and retry support for `GameSim`.
+`kit/align` audits caller-supplied disks, multi-block layouts and pixel seams; finding the
+games to audit and reporting the results belong to the consumer. `simulation` also exposes route scene
+assertions and scene initialization that delegates to the engine. `GameSimState` names
+the snapshot type; compatibility initialization preserves older block-birth bookkeeping.
+
+### DOS disk output
+
+`kit/disk` exports `Disk` for collecting 8.3-named files and writing a clean output
+directory, plus the legacy `dosText` byte conversion. Destination and metadata are
+caller-supplied. `kit/menuVersion` can stamp a supplied version on a native menu GIF;
+this package reads no game metadata files and imposes no version policy.
+
+`kit/palRamps` also exports `wrapWithBuilder` and `buildRampPalette`: supply ramp
+descriptors, optional named endpoint replacements, and a color transform. The game
+keeps its actual colors and lighting choices. `colors` and `text` are direct browser-safe
+entries for the existing lighting, ramp, glyph-row, and rendered-text APIs.
+
+`kit/textfit` audits caller-supplied native files for menu, save-slot, score-table and
+text-page layout and contrast. Choosing which games to check, and printing the results, are left to the consumer.
+
+## Original Library palette
+
+`libraryDefaultPalette()` from `@lewismoten/gamemaker-sandbox-tools/palettes` returns
+an independent 768-byte copy of the CD Library's `DEFAULT.PAL`, with black at index
+zero. This is the original RSD palette, rather than the engine's generated fallback.
+It works in browsers and Node without fetching the CD or using repository files.
+See `NOTICE.md` for its source and license.
+
+### Palette templates
+
+`PALETTE_PRESETS` from `palettes` lists 20 ready-made templates with names, descriptions,
+occupied entry counts and DOS-safe filename stems. `createPalettePreset(id)` returns a fresh
+768-byte VGA palette with menu black at index 0, transparency reserved at 255, and unused
+entries black. Templates include monochrome, Atari NTSC/PAL, NES, CGA, EGA, EGA with skin/hair
+ramps, LCD greens, Sega Master System, Commodore 64, web-safe colors and grayscale steps.
+128-step grayscale necessarily repeats VGA's 64 distinct gray shades. LCD greens include
+four green shades plus menu black. Console RGB references and their licenses are in NOTICE.md;
+all values are adapted to six-bit VGA and do not impose the original consoles' drawing limits.
+
+## Developing
+
+This package's source lives in [the project's repository](https://github.com/lewismoten/GameMaker-SandboxEdition), in `web/packages/tools`. The folder holds its builders in `src/`, build configuration, license and notices. Shared codecs and runtime types come through declared engine and archives dependencies, and it never reads source from another repository folder. After `npm install` in a standalone copy, or `npm ci` at the repository root:
 
 ```sh
 npm run build
@@ -64,14 +354,10 @@ npm run verify
 npm pack
 ```
 
-The build bundles source from the format, drawing, audio, and simulation modules. It does not use or restart the site's Vite configuration. The tarball contains JavaScript, declarations, this guide, the MIT license, and notices. Validate a packed installation in a separate project before publishing.
-
-`verify` installs the tarball in a temporary npm consumer and checks codecs, drawing, sound generation, headless simulation, NodeNext declarations, absence of game content, and rejected browser imports. After reviewing the candidate, publish with `npm publish --access public`; publishing is a separate action.
-
-## Tagged releases
+The build bundles source from the format, drawing, audio, and simulation modules. It does not use or restart the site's Vite configuration. The tarball contains JavaScript, declarations, this guide, the MIT license, and notices. From the repository root, `npm run verify:packages` copies each package outside the repository, builds it with packed declared dependencies, and tests its npm distribution, which also supports unpublished sibling versions.
 
-The [release workflow](../../../.github/workflows/publish-tools.yml) publishes to the public npm registry when a `tools-v<version>` tag is pushed. The tag must match this package's version and point to a commit on `master`. For this release, use `tools-v3.1.0` after merging the package changes.
+`verify` installs the tarball in a temporary npm consumer and checks codecs, drawing, sound generation, headless simulation, NodeNext declarations, absence of game content, and rejected browser imports. Tarballs are local build artifacts and must not be committed to a consuming project. The [monorepo guide](https://github.com/lewismoten/GameMaker-SandboxEdition/blob/master/docs/monorepo.md) covers the workspace layout, and the [package release guide](https://github.com/lewismoten/GameMaker-SandboxEdition/blob/master/docs/package-releases.md) covers publishing.
 
-Configure the repository's `NPM_TOKEN` Actions secret with an npm publishing token authorized for `@lewismoten/gamemaker-sandbox-tools` (including automated publishing with 2FA). The workflow checks source, builds and verifies the packed package, then publishes with provenance. Ordinary branch pushes do not publish anything. See npm's [publishing documentation](https://docs.npmjs.com/creating-and-publishing-scoped-public-packages/).
+## License and notices
 
-Tarballs are local build artifacts and must not be committed to a consuming project. Consumers should use `npm install --save-dev @lewismoten/gamemaker-sandbox-tools@^3.1.0` after the tagged release is published.
+The source is MIT licensed. The published package carries `LICENSE` and `NOTICE.md` (credits for third-party code and formats); it includes no game assets.

package/dist/audio-files.js

@@ -0,0 +1,82 @@
+import { execFileSync as l } from "node:child_process";
+import { statSync as u, readFileSync as d } from "node:fs";
+import { fileURLToPath as p } from "node:url";
+import { encodeVoc as g } from "@lewismoten/gamemaker-sandbox-engine/formats/voc";
+function h(t) {
+  const n = (a) => String.fromCharCode(...t.subarray(a, a + 4));
+  if (t.length < 12 || n(0) !== "RIFF" || n(8) !== "WAVE") return;
+  const r = new DataView(t.buffer, t.byteOffset, t.byteLength);
+  let o, m;
+  for (let a = 12; a + 8 <= t.length; ) {
+    const i = n(a), s = r.getUint32(a + 4, !0), e = a + 8;
+    if (s > t.length - e) throw new Error("Truncated WAV chunk");
+    if (i === "fmt ") {
+      if (s < 16) throw new Error("Truncated WAV format");
+      if (r.getUint16(e, !0) !== 1 || r.getUint16(e + 2, !0) !== 1 || r.getUint16(e + 14, !0) !== 8) return;
+      if (r.getUint16(e + 12, !0) !== 1) throw new Error("Invalid mono 8-bit WAV alignment");
+      if (o = r.getUint32(e + 4, !0), !o) throw new Error("Invalid WAV sample rate");
+    } else i === "data" && (m = t.subarray(e, e + s));
+    a = e + s + (s & 1);
+  }
+  if (!o || !m) throw new Error("WAV is missing its format or sample data");
+  return { sampleRate: o, samples: m };
+}
+function c(t, n) {
+  if (!Number.isSafeInteger(t) || t <= 0) throw new RangeError(`${n} must be a positive integer`);
+}
+function w(t, n = {}) {
+  const r = n.sampleRate ?? 11025, o = n.maxSamples ?? 16 * 1024 * 1024, m = n.timeoutMs ?? 3e4;
+  if (c(r, "sampleRate"), c(o, "maxSamples"), c(m, "timeoutMs"), r < 3906 || r > 1e6) throw new RangeError("sampleRate is outside the VOC time-constant range (3906–1000000 Hz)");
+  const a = t instanceof URL ? p(t) : t;
+  if (!a) throw new TypeError("An audio file path is required");
+  let i;
+  if (/\.wav$/i.test(a) && u(a).size <= o + 65536) {
+    const e = h(d(a));
+    e?.sampleRate === r && (i = e.samples);
+  }
+  try {
+    i ??= l(
+      n.ffmpegPath ?? "ffmpeg",
+      [
+        "-nostdin",
+        "-hide_banner",
+        "-loglevel",
+        "error",
+        "-i",
+        a,
+        "-map",
+        "0:a:0",
+        "-vn",
+        "-ac",
+        "1",
+        "-ar",
+        String(r),
+        "-af",
+        "aresample=dither_method=none",
+        "-c:a",
+        "pcm_u8",
+        "-f",
+        "u8",
+        "pipe:1"
+      ],
+      { timeout: m, maxBuffer: o, stdio: ["ignore", "pipe", "pipe"] }
+    );
+  } catch (e) {
+    const f = e.code;
+    throw f === "ENOENT" ? new Error("FFmpeg is required to convert audio files. Install it or set ffmpegPath.", { cause: e }) : f === "ENOBUFS" || f === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER" ? new RangeError(`Decoded audio exceeds ${o} samples`, { cause: e }) : new Error("FFmpeg could not decode the audio file within the conversion limits.", { cause: e });
+  }
+  if (i.length > o) throw new RangeError(`Decoded audio exceeds ${o} samples`);
+  const s = new Float32Array(i.length);
+  for (let e = 0; e < i.length; e++) s[e] = (i[e] - 128) / 127;
+  return s;
+}
+function v(t, n = {}) {
+  const r = n.maxBytes ?? 65535;
+  if (!Number.isSafeInteger(r) || r < 34 || r > 65535) throw new RangeError("maxBytes must be between 34 and 65535");
+  const o = w(t, { ...n, maxSamples: r - 33 });
+  return g(o, n.sampleRate ?? 11025);
+}
+export {
+  v as audioFileToVoc,
+  w as decodeAudioFile
+};