@lewismoten/gamemaker-sandbox-tools 0.0.0-stage → 3.1.0

package/LICENSE

@@ -0,0 +1,24 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 gandrewstone
+Copyright (c) 2026 Lewis Moten (modifications: the web port, the 1994 desk, the
+Sandbox Software and Bard of Bizarre games, and the Mac, Windows and Linux players;
+see NOTICE.md)
+
+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, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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/NOTICE.md

@@ -0,0 +1,19 @@
+# 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.
+
+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.
+- **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
+
+The lighting presets were written for this project. GIF, FLI, Creative Voice File, Creative Music File, and ZIP/PNG support follow their respective file formats; CRC-32 uses the reflected polynomial 0xEDB88320.
+
+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.

package/README.md

@@ -1,3 +1,77 @@
-# Temporary Holding Version
+# @lewismoten/gamemaker-sandbox-tools
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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.
+
+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.
+
+## 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.
+- `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.
+- `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.
+
+```ts
+import { emptyBlock, serializeBlocks } from '@lewismoten/gamemaker-sandbox-tools/formats/blocks';
+import { Pixels } from '@lewismoten/gamemaker-sandbox-tools/drawing';
+
+const blocks = Array.from({ length: 150 }, (_, i) => emptyBlock(i));
+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.
+
+## Fonts, text images, and lighting
+
+`drawing` exports the complete `FONT_CP437` (256 × 8 rows, bit 0 leftmost), including DOS symbols, accents, block shading, and box drawing. NUL, space, and nonbreaking space are intentionally blank. The legacy `FONT8X8` and `text` helpers retain their ASCII behavior. `glyphRows(code)` returns a copy; `encodeText`, `toCp437`, and `fromCp437` convert Unicode DOS symbols and CP437 codes. This is the DOS glyph set, not an ANSI escape-sequence parser.
+
+`MICRO_GLYPHS` exposes the project's original 3×5 uppercase font and punctuation. `glyphRows(code, 'micro')` accepts lowercase as uppercase and uses `?` for unsupported glyphs. It does not include game-specific lettering.
+
+```ts
+import { renderText, encodeText, PaletteBuilder, lightColor, TIME_OF_DAY_SKY } from '@lewismoten/gamemaker-sandbox-tools/drawing';
+
+const caption = renderText('╔═╗\n║é║\n╚═╝', {
+  color: 12, outline: 0, shadow: { color: 8 },
+});
+// caption.width, caption.height, caption.pixels suit indexed GIF/picture builders.
+// Copy small images into a native block's 20×20 pixel array before serializing it.
+const sign = renderText('GO!', { font: 'micro', color: 15, scale: 2 });
+const rawGlyphs = renderText(Uint8Array.of(1, 3, 10, 219), { color: 15 });
+const dosTextBytes = encodeText('Café ♥');
+
+const palette = new PaletteBuilder();
+palette.designerColors();
+const [dark, light, middle] = TIME_OF_DAY_SKY.sunset;
+palette.ramp('sky', 8, dark, light, middle);
+const lit = lightColor([100, 180, 80], 'night');
+```
+
+`renderText` returns row-major indexed pixels with transparent index 255 and an origin for the first text cell. It pads the output for a one-pixel outline and shadow, even at larger scales or negative shadow offsets. Strings support LF/CRLF lines; raw byte arrays draw every byte as a glyph on one line. Empty text returns a 0×0 image. Unsupported Unicode throws rather than selecting an unrelated glyph. Ink indexes are 0–254.
+
+`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.
+
+## Build and inspect
+
+From this directory, with the repository's web development dependencies installed:
+
+```sh
+npm run build
+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 [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.
+
+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/).
+
+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.

package/dist/audio.js

@@ -0,0 +1,140 @@
+import { encodeCmf as S } from "./formats/cmf.js";
+import { encodeVoc as L } from "./formats/voc.js";
+import { NUMFREQ as p } from "./formats/sound.js";
+import { r as b } from "./pixels-DzfIIUOl.js";
+function s(e) {
+  return Uint8Array.from([
+    e.modChar,
+    e.carChar,
+    e.modLevel,
+    e.carLevel,
+    e.modAD,
+    e.carAD,
+    e.modSR,
+    e.carSR,
+    e.modWave ?? 0,
+    e.carWave ?? 0,
+    e.feedback,
+    0,
+    0,
+    0,
+    0,
+    0
+  ]);
+}
+const C = {
+  piano: s({ modChar: 1, carChar: 1, modLevel: 90, carLevel: 0, modAD: 242, carAD: 243, modSR: 99, carSR: 101, feedback: 8 }),
+  bass: s({ modChar: 1, carChar: 1, modLevel: 26, carLevel: 0, modAD: 246, carAD: 245, modSR: 84, carSR: 69, feedback: 8 }),
+  strings: s({ modChar: 97, carChar: 33, modLevel: 29, carLevel: 0, modAD: 116, carAD: 99, modSR: 19, carSR: 21, feedback: 14 }),
+  brass: s({ modChar: 33, carChar: 33, modLevel: 26, carLevel: 0, modAD: 99, carAD: 116, modSR: 40, carSR: 23, feedback: 12 }),
+  lead: s({ modChar: 34, carChar: 33, modLevel: 27, carLevel: 0, modAD: 244, carAD: 244, modSR: 68, carSR: 36, modWave: 2, feedback: 12 }),
+  bell: s({ modChar: 7, carChar: 1, modLevel: 35, carLevel: 0, modAD: 245, carAD: 243, modSR: 34, carSR: 19, feedback: 4 }),
+  organ: s({ modChar: 50, carChar: 49, modLevel: 68, carLevel: 0, modAD: 240, carAD: 240, modSR: 15, carSR: 15, feedback: 1 }),
+  pad: s({ modChar: 161, carChar: 33, modLevel: 41, carLevel: 0, modAD: 67, carAD: 82, modSR: 5, carSR: 4, modWave: 1, feedback: 10 }),
+  pluck: s({ modChar: 3, carChar: 1, modLevel: 30, carLevel: 0, modAD: 248, carAD: 246, modSR: 53, carSR: 85, feedback: 12 })
+}, D = { C: 0, D: 2, E: 4, F: 5, G: 7, A: 9, B: 11 }, k = { w: 4, h: 2, q: 1, e: 0.5, s: 0.25, t: 1 / 3 };
+function M(e) {
+  if (/^r$/i.test(e)) return null;
+  const r = /^([A-G])([#b]?)(-?\d)$/.exec(e);
+  if (!r) throw new Error(`Bad note ${e}`);
+  return 12 * (Number(r[3]) + 1) + D[r[1]] + (r[2] === "#" ? 1 : r[2] === "b" ? -1 : 0);
+}
+function g(e, r) {
+  const a = Math.round(8760 / e), t = [], o = [], l = /* @__PURE__ */ new Map();
+  for (const n of r) {
+    t[n.channel] = n.instrument;
+    let c = 0;
+    for (const i of n.notes.split(",").map((d) => d.trim()).filter(Boolean)) {
+      const d = /^(.+?)\s+([whqest])(\.?)$/.exec(i);
+      if (!d) throw new Error(`Bad note "${i}"`);
+      const f = k[d[2]] * (d[3] ? 1.5 : 1) * a;
+      d[1].replace(/[[\]]/g, " ").trim().split(/\s+/).forEach((R, u) => {
+        const v = M(R);
+        if (v === null) return;
+        const h = Math.min(15, n.channel + u);
+        u > 0 && l.set(h, n.instrument);
+        const A = v + (n.transpose ?? 0);
+        o.push({ tick: c, data: [144 | h, A, n.velocity ?? 100] }), o.push({ tick: c + f * 0.92, data: [128 | h, A, 0] });
+      }), c += f;
+    }
+  }
+  for (const [n, c] of l) t[n] ??= c;
+  for (let n = 0; n < 16; n++) t[n] ??= C.piano;
+  return S({ instruments: t, events: o, ticksPerBeat: a });
+}
+function j(e = 120) {
+  const r = Math.round(8760 / e), a = Array.from({ length: 16 }, () => C.piano);
+  return S({ instruments: a, events: [{ tick: 4 * r, data: [176, 7, 100] }], ticksPerBeat: r });
+}
+const w = { w: 4, h: 2, q: 1, e: 0.5, s: 0.25, t: 1 / 3 }, E = (e) => e.split(",").map((r) => r.trim()).filter(Boolean).reduce((r, a) => r + w[a.endsWith(".") ? a.slice(-2, -1) : a.slice(-1)] * (a.endsWith(".") ? 1.5 : 1), 0);
+function q(e, r) {
+  const a = r.map((t) => E(t.notes));
+  if (a.some((t) => Math.abs(t - a[0]) > 1e-6)) throw new Error(`Voices differ in length: ${a.join(" ")}`);
+  return g(e, r);
+}
+const P = (e, r, a, t = 100, o = 0) => ({
+  channel: e,
+  instrument: r,
+  notes: a,
+  velocity: t,
+  transpose: o
+}), U = (...e) => e.filter(Boolean).join(", "), F = (e, r) => Array(e).fill(r).join(", ");
+function m(e) {
+  return Uint16Array.from({ length: p }, (r, a) => Math.max(0, Math.min(8192, Math.round(e(a, a / (p - 1))))));
+}
+const T = {
+  rise: (e = 200, r = 2e3) => m((a, t) => e * (r / e) ** t),
+  fall: (e = 2e3, r = 150) => m((a, t) => e * (r / e) ** t),
+  coin: () => m((e) => e < 4 ? 988 : e < 18 ? 1319 : 0),
+  hurt: () => m((e) => (e % 2 ? 140 : 95) * (1 - e / 60)),
+  zap: () => m((e) => 3e3 - e * 75 + e % 3 * 300),
+  chirp: () => m((e) => e < 12 ? 1200 + e * 120 : 0),
+  arpeggio: (e = [523, 659, 784, 1047]) => m((r) => r < e.length * 6 ? e[Math.floor(r / 6)] : 0),
+  noise: (e = 1, r = 100, a = 2e3) => {
+    const t = b(e);
+    return m((o) => o < 30 ? r + t() * (a - r) : 0);
+  },
+  warble: (e = 600, r = 300, a = 1.3) => m((t) => e + Math.sin(t * a) * r)
+}, B = {
+  sine: (e) => {
+    let r = 0, a = 0;
+    return (t) => {
+      const o = typeof e == "number" ? e : e(t);
+      return r += 2 * Math.PI * o * (t - a), a = t, Math.sin(r);
+    };
+  },
+  square: (e) => {
+    const r = B.sine(e);
+    return (a) => r(a) >= 0 ? 1 : -1;
+  },
+  noise: (e = 7) => {
+    const r = b(e);
+    return () => r() * 2 - 1;
+  }
+};
+function _(e, r, a = {}) {
+  const t = a.rate ?? 11025, o = Math.round(e * t), l = new Float32Array(o), n = a.attack ?? 5e-3;
+  for (let c = 0; c < o; c++) {
+    const i = c / t, d = a.envelope ? a.envelope(i / e) : Math.min(1, i / n) * (1 - i / e) ** 1.5;
+    l[c] = Math.max(-1, Math.min(1, r(i) * d * (a.gain ?? 0.9)));
+  }
+  return L(l, t);
+}
+const G = (...e) => (r) => e.reduce((a, [t, o]) => a + t(r) * o, 0);
+export {
+  C as INSTRUMENTS,
+  w as LEN,
+  T as SPEAKER,
+  j as blankSong,
+  U as join,
+  M as midi,
+  G as mix,
+  B as osc,
+  _ as sample,
+  s as sbi,
+  g as song,
+  m as speaker,
+  F as times,
+  q as tune,
+  P as v
+};

package/dist/binary-D7wuaC5g.js

@@ -0,0 +1,120 @@
+const n = new TextDecoder("latin1");
+class h {
+  bytes;
+  offset;
+  constructor(t, s = 0) {
+    this.bytes = t, this.offset = s;
+  }
+  get length() {
+    return this.bytes.length;
+  }
+  get eof() {
+    return this.offset >= this.bytes.length;
+  }
+  skip(t) {
+    return this.offset += t, this;
+  }
+  u8() {
+    const t = this.offset < this.bytes.length ? this.bytes[this.offset] : 0;
+    return this.offset++, t;
+  }
+  i8() {
+    const t = this.u8();
+    return t > 127 ? t - 256 : t;
+  }
+  u16() {
+    return this.u8() | this.u8() << 8;
+  }
+  i16() {
+    const t = this.u16();
+    return t > 32767 ? t - 65536 : t;
+  }
+  u32() {
+    return (this.u16() | this.u16() << 16) >>> 0;
+  }
+  i32() {
+    return this.u16() | this.u16() << 16;
+  }
+  /** Copies n bytes (zero padded when the source is short). */
+  bytesOf(t) {
+    const s = new Uint8Array(t), e = Math.max(0, Math.min(t, this.bytes.length - this.offset));
+    return e > 0 && s.set(this.bytes.subarray(this.offset, this.offset + e)), this.offset += t, s;
+  }
+  /** Reads a fixed size, NUL terminated string field. */
+  cstr(t) {
+    return u(this.bytesOf(t));
+  }
+}
+class f {
+  buf;
+  offset = 0;
+  constructor(t = 1024) {
+    this.buf = new Uint8Array(t);
+  }
+  ensure(t) {
+    if (this.offset + t <= this.buf.length) return;
+    let s = this.buf.length * 2;
+    for (; s < this.offset + t; ) s *= 2;
+    const e = new Uint8Array(s);
+    e.set(this.buf), this.buf = e;
+  }
+  u8(t) {
+    return this.ensure(1), this.buf[this.offset++] = t & 255, this;
+  }
+  // Signed writes store the same two's complement bytes as the unsigned ones.
+  i8(t) {
+    return this.u8(t);
+  }
+  u16(t) {
+    return this.u8(t).u8(t >> 8);
+  }
+  i16(t) {
+    return this.u16(t);
+  }
+  u32(t) {
+    return this.u16(t & 65535).u16(t >>> 16 & 65535);
+  }
+  i32(t) {
+    return this.u32(t >>> 0);
+  }
+  bytes(t, s = t.length) {
+    this.ensure(s);
+    for (let e = 0; e < s; e++) this.buf[this.offset++] = e < t.length ? t[e] & 255 : 0;
+    return this;
+  }
+  /** Writes a string into a fixed size NUL padded field (truncated to leave room for the NUL). */
+  cstr(t, s) {
+    const e = new Uint8Array(s);
+    for (let i = 0; i < Math.min(t.length, s - 1); i++) e[i] = t.charCodeAt(i) & 255;
+    return this.bytes(e);
+  }
+  /**
+   * Writes a fixed size string field. When the text is unchanged the original raw
+   * bytes (including any garbage after the NUL) are kept so files round-trip exactly.
+   */
+  cstrOver(t, s, e) {
+    return s && s.length === e && u(s) === t ? this.bytes(s) : this.cstr(t, e);
+  }
+  toBytes() {
+    return this.buf.slice(0, this.offset);
+  }
+}
+function u(r) {
+  const t = r.indexOf(0);
+  return n.decode(t < 0 ? r : r.subarray(0, t));
+}
+function o(r) {
+  return n.decode(r);
+}
+function c(r) {
+  const t = new Uint8Array(r.length);
+  for (let s = 0; s < r.length; s++) t[s] = r.charCodeAt(s) & 255;
+  return t;
+}
+export {
+  h as R,
+  f as W,
+  u as c,
+  o as l,
+  c as t
+};