TypeScript
// Project: the registry an art file fills in, plus the lazy, cached, cycle-checked resolver.
import { type BuildCtx, type BuildOut, buildAsset, gcd } from "./build.ts";
import { OPS } from "./canvas.ts";
import { PxError, didYouMean, wrap } from "./errors.ts";
import type { Img } from "./image.ts";
import {
type AssetDef, type AssetKind, type AssetOpts, type GroupDef, type Item, type Layer, type LayerOpts, type Op,
type SheetDef, type SheetOpts, type Timeline, isLayer, isOp,
} from "./model.ts";
import { Palette } from "./palette.ts";
import { Trace } from "./trace.ts";
import { globRe, rng } from "./util.ts";
/**
* Op signatures: name:type, "?" marks the first optional argument.
* n number, c color, s string, t text (string|number), S colors ("abc" or array),
* a point array, r region, o object, b boolean, I items (rest).
*/
export const SIGNATURES: Record<string, string> = {
px: "x:n y:n c:c",
rect: "x:n y:n w:n h:n c:c",
box: "x:n y:n w:n h:n c:c",
line: "x0:n y0:n x1:n y1:n c:c ?width:n",
hline: "x:n y:n len:n c:c",
vline: "x:n y:n len:n c:c",
ellipse: "cx:n cy:n rx:n ry:n c:c ?ring:b",
circ: "cx:n cy:n r:n c:c",
ring: "cx:n cy:n r:n c:c",
poly: "points:a c:c",
fill: "x:n y:n c:c",
dither: "x:n y:n w:n h:n c1:c c2:c ?density:n",
grad: "x:n y:n w:n h:n colors:S ?dir:s soft:n",
noise: "x:n y:n w:n h:n colors:S ?density:n seed:n on:s",
recolor: "map:o ?where:r density:n",
shade: "?where:r steps:n density:n",
light: "?where:r steps:n density:n",
stamp: "name:s ?x:n y:n opts:o",
tile: "name:s x:n y:n ?cols:n rows:n opts:o",
pattern: "name:s x:n y:n w:n h:n ?opts:o",
tilemap: "map:s opts:o",
scatter: "name:s x:n y:n w:n h:n count:n ?opts:o",
grid: "x:n y:n str:s",
wire: "x0:n y0:n x1:n y1:n sag:n c:c ?opts:o",
text: "x:n y:n str:t c:c ?opts:o",
clip: "where:r ...items:I",
lamp: "x:n y:n ?opts:o",
bump: "?shape:s opts:o",
normals: "x:n y:n str:s",
lighting: "?opts:o",
glow: "keys:S ?opts:o",
};
/** Allowed option keys of ops whose last argument is an options object. */
const OP_OPTS: Record<string, string[]> = {
lamp: ["r", "color", "power", "z"],
bump: ["w", "depth", "on", "where"],
lighting: ["cell", "ambient", "ambientColor", "sky", "skyColor", "skyReach", "block", "smooth", "emit", "shape", "relief", "skyDir"],
glow: ["where", "r", "strength", "color", "bands", "ramp"],
};
const ASSET_OPTS: Record<AssetKind, string[]> = {
sprite: ["w", "h", "base", "mx", "my", "swap", "flip", "rot", "outline", "outline8", "crop", "layers"],
scene: ["w", "h", "bg", "mx", "my", "swap", "flip", "rot", "outline", "outline8", "crop", "layers"],
anim: ["w", "h", "base", "mx", "my", "swap", "flip", "rot", "outline", "outline8", "crop", "layers", "fps", "frames", "loop"],
};
const FRAME_OPTS = ["ms", "hold"];
/** Longest loop a combined timeline may have (ms); longer ones are cut. */
const MAX_LOOP = 60000;
const LAYER_OPTS = ["x", "y", "hidden", "shade", "light", "density", "solid", "wall", "unlit"];
const SHEET_OPTS = ["cols", "pad"];
function checkArgs(name: string, args: unknown[]): void {
const sig = SIGNATURES[name];
if (!sig) return;
let optional = false;
sig.split(" ").forEach((part, i) => {
if (part.startsWith("?")) { optional = true; part = part.slice(1); }
const [pname, type] = part.split(":");
if (pname.startsWith("...")) return;
const v = args[i];
if (v === undefined) {
if (!optional) throw new PxError(`${name}: missing argument ${i + 1} (${pname}); usage: ${name}(${usage(sig)})`);
return;
}
const bad = (want: string) => {
throw new PxError(`${name}: argument ${i + 1} (${pname}) must be ${want}, got ${JSON.stringify(v) ?? typeof v}; usage: ${name}(${usage(sig)})`);
};
switch (type) {
case "n": if (typeof v !== "number" || !Number.isFinite(v)) bad("a number"); break;
case "c": if (typeof v !== "string") bad('a color key or "#hex"'); break;
case "s": if (typeof v !== "string") bad("a string"); break;
case "t": if (typeof v !== "string" && typeof v !== "number") bad("text"); break;
case "S": if (typeof v !== "string" && !Array.isArray(v)) bad('colors like "abc" or ["a","b"]'); break;
case "a": if (!Array.isArray(v)) bad("an array of numbers"); break;
case "o": if (typeof v !== "object" || v === null || Array.isArray(v)) bad("an options object"); break;
case "b": if (typeof v !== "boolean") bad("true/false"); break;
}
});
}
function usage(sig: string): string {
return sig.split(" ").map((p) => p.replace(/:.*/, "").replace(/^\?/, "[")).join(", ") + (sig.includes("?") ? "]" : "");
}
function checkKeys(what: string, obj: object, allowed: string[], loc?: string): void {
for (const k of Object.keys(obj))
if (!allowed.includes(k)) throw new PxError(`${what}: unknown option '${k}'${didYouMean(k, allowed)} (allowed: ${allowed.join(", ")})`, loc);
}
function isPlainObject(v: unknown): v is Record<string, unknown> {
return typeof v === "object" && v !== null && !Array.isArray(v) && !isOp(v) && !isLayer(v);
}
function checkItems(where: string, items: unknown[], loc?: string): Item[] {
items.forEach((v, i) => {
const ok = typeof v === "string" || typeof v === "function" || isOp(v) || isLayer(v);
if (!ok) {
const what = Array.isArray(v) ? "an array (use ...spread)" : v === undefined ? "undefined (missing comma or op name?)" : `a ${typeof v}`;
throw new PxError(`${where}: item ${i + 1} is ${what}; items are grid strings, ops, functions or layers`, loc);
}
});
return items as Item[];
}
export interface ProjectOptions {
/** Record painting traces for seed-0 builds (live viewer). */
trace?: boolean;
}
export class Project implements BuildCtx {
readonly assets = new Map<string, AssetDef>();
readonly order: string[] = [];
readonly groups = new Map<string, GroupDef>();
readonly sheets: SheetDef[] = [];
/** Art files loaded so far (absolute paths or virtual names), for locations and watching. */
readonly files: string[] = [];
pal: Palette = Palette.builtin("pico8");
/** Set by a loader to support include(). */
includeHook?: (path: string) => void;
private cache = new Map<string, BuildOut>();
/** Timelines gathered from animated assets placed by the builds in progress (innermost last). */
private collect: Partial<Timeline>[] = [];
private building = new Set<string>();
private cands = new Map<string, string[]>();
private failed = new Map<string, PxError>();
private tracing: boolean;
constructor(opts: ProjectOptions = {}) {
this.tracing = !!opts.trace;
}
// ---------------------------------------------------------------- locations
addFile(file: string): void {
if (!this.files.includes(file)) this.files.push(file);
}
locFromStack(stack: string): string | undefined {
for (const line of stack.split("\n")) {
for (const f of this.files) {
const i = line.indexOf(f + ":");
if (i < 0) continue;
const m = /^:(\d+):(\d+)/.exec(line.slice(i + f.length));
if (m) return `${shortName(f)}:${m[1]}:${m[2]}`;
}
}
return undefined;
}
callerLoc(): string | undefined {
const limit = Error.stackTraceLimit;
Error.stackTraceLimit = 60;
const stack = new Error().stack ?? "";
Error.stackTraceLimit = limit;
return this.locFromStack(stack);
}
// ---------------------------------------------------------------- DSL
/** Functions visible to art files. */
env(): Record<string, unknown> {
const env: Record<string, unknown> = {};
const define = (kind: AssetKind, name: unknown, rest: unknown[]) => {
const loc = this.callerLoc();
if (typeof name !== "string" || !name) throw new PxError(`${kind} needs a name string first`, loc);
const prev = this.assets.get(name) ?? this.groups.get(name);
if (prev) throw new PxError(`'${name}' is already defined at ${prev.loc}`, loc);
const opts = (isPlainObject(rest[0]) ? rest.shift() : {}) as AssetOpts;
checkKeys(`${kind} '${name}'`, opts, ASSET_OPTS[kind], loc);
const items = checkItems(`${kind} '${name}'`, rest, loc);
this.assets.set(name, { kind, name, opts, items, pal: this.pal, loc });
this.order.push(name);
};
env.use = (p: unknown) => {
if (Array.isArray(p)) this.pal = Palette.fromColors(p as (string | number)[]);
else if (typeof p === "string") this.pal = Palette.builtin(p);
else throw new PxError('use("pico8") or use(["#000", "#fff", ...])', this.callerLoc());
};
env.pal = (aliases: Record<string, string | number>) => {
try { this.pal = this.pal.extend(aliases); } catch (e) { throw wrap(e).within("pal", this.callerLoc()); }
};
env.ramps = (...ramps: string[]) => {
try { this.pal = this.pal.withRamps(ramps); } catch (e) { throw wrap(e).within("ramps", this.callerLoc()); }
};
env.sprite = (name: unknown, ...rest: unknown[]) => define("sprite", name, rest);
env.anim = (name: unknown, ...rest: unknown[]) => define("anim", name, rest);
env.frame = (...args: unknown[]): Op => {
const loc = this.callerLoc();
if (isPlainObject(args[0])) checkKeys("frame", args[0], FRAME_OPTS, loc);
checkItems("frame", isPlainObject(args[0]) ? args.slice(1) : args, loc);
return { __op: true, name: "frame", args, loc };
};
env.scene = (name: unknown, ...rest: unknown[]) => define("scene", name, rest);
env.layer = (name: unknown, ...rest: unknown[]): Layer => {
const loc = this.callerLoc();
if (typeof name !== "string") throw new PxError("layer needs a name string first", loc);
const opts = (isPlainObject(rest[0]) ? rest.shift() : {}) as LayerOpts;
checkKeys(`layer '${name}'`, opts, LAYER_OPTS, loc);
return { __layer: true, name, opts, items: checkItems(`layer '${name}'`, rest, loc), loc };
};
env.group = (name: unknown, members: unknown) => {
const loc = this.callerLoc();
if (typeof name !== "string" || !Array.isArray(members) || !members.every((m) => typeof m === "string"))
throw new PxError('group("name", ["a", "b*", ...])', loc);
const prev = this.assets.get(name) ?? this.groups.get(name);
if (prev) throw new PxError(`'${name}' is already defined at ${prev.loc}`, loc);
this.groups.set(name, { name, members, loc });
};
env.sheet = (name: unknown, entries: unknown, opts: SheetOpts = {}) => {
const loc = this.callerLoc();
if (typeof name !== "string" || !Array.isArray(entries)) throw new PxError('sheet("name", ["a", "b*"], { cols, pad })', loc);
checkKeys(`sheet '${name}'`, opts, SHEET_OPTS, loc);
this.sheets.push({ name, entries, opts, loc });
};
env.include = (path: unknown) => {
if (typeof path !== "string") throw new PxError('include("other.px.js")', this.callerLoc());
if (!this.includeHook) throw new PxError("include() is not available here", this.callerLoc());
this.includeHook(path);
};
env.rng = (seed?: number) => rng(seed);
for (const name of [...OPS, "clip", "lighting", "glow"]) {
env[name] = (...args: unknown[]): Op => {
const loc = this.callerLoc();
try {
checkArgs(name, args);
const o = args[args.length - 1];
if (OP_OPTS[name] && isPlainObject(o)) checkKeys(name, o, OP_OPTS[name]);
} catch (e) { throw wrap(e).within(name, loc); }
if (name === "clip") checkItems("clip", args.slice(1), loc);
return { __op: true, name, args, loc };
};
}
return env;
}
// ---------------------------------------------------------------- resolving
candidates(name: string, depth = 0): string[] {
const hit = this.cands.get(name);
if (hit) return hit;
if (typeof name !== "string") throw new PxError(`asset name must be a string, got ${typeof name}`);
if (depth > 8) throw new PxError(`group nesting too deep at '${name}'`);
let list: string[] = [];
const g = this.groups.get(name);
if (g) for (const m of g.members) list.push(...this.candidates(m, depth + 1));
else if (name.includes("*")) {
const re = globRe(name);
list = this.order.filter((n) => re.test(n));
} else list = [name];
if (!list.length) throw new PxError(`'${name}' matches no assets`);
this.cands.set(name, list);
return list;
}
image(name: string, seed = 0, t = 0, track = true): Img {
return this.build(name, seed, t, track).img;
}
timeline(name: string, seed = 0): Timeline | undefined {
return this.build(name, seed, 0, false).anim;
}
/**
* Build an asset at time t (ms). Still assets ignore t. Unless `track` is false, an animated
* result makes the asset being built around this call animated too.
*/
build(name: string, seed = 0, t = 0, track = true): BuildOut {
const first = this.buildAt(name, seed, 0);
const tl = first.anim;
if (tl && track && this.collect.length) {
const acc = this.collect[this.collect.length - 1];
acc.loop = acc.loop ? Math.min(MAX_LOOP, lcm(acc.loop, tl.loop)) : tl.loop;
acc.step = acc.step ? gcd(acc.step, tl.step) : tl.step;
}
if (!tl || t === 0) return first;
const tt = tl.once ? Math.min(Math.max(0, t), tl.loop) : ((t % tl.loop) + tl.loop) % tl.loop;
return tt === 0 ? first : this.buildAt(name, seed, tt);
}
/** One full loop of an animated asset as [{ img, ms }]; [] for still assets. */
frames(name: string, seed = 0, max = 600): { img: Img; ms: number }[] {
const tl = this.build(name, seed).anim;
if (!tl) return [];
if (tl.durations) {
let t = 0;
return tl.durations.map((ms) => {
const f = { img: this.build(name, seed, t).img, ms };
t += ms;
return f;
});
}
const n = Math.max(1, Math.min(max, Math.round(tl.loop / tl.step)));
return Array.from({ length: n }, (_, i) => ({ img: this.build(name, seed, i * tl.step).img, ms: tl.step }));
}
private buildAt(name: string, seed: number, t: number): BuildOut {
const key = (seed === 0 ? name : `${name}@${seed}`) + (t ? `#${t}` : "");
const hit = this.cache.get(key);
if (hit) return hit;
const def = this.assets.get(name);
if (!def) {
if (this.groups.has(name) || name.includes("*"))
throw new PxError(`'${name}' is a group/glob: use it in stamp, tile, pattern, tilemap, scatter or wire hang`);
throw new PxError(`unknown asset '${name}'${didYouMean(name, this.order)}`);
}
const failed = this.failed.get(key);
if (failed) throw new PxError(`depends on '${name}', which failed`);
if (this.building.has(name)) throw new PxError(`reference cycle through '${name}'`);
this.building.add(name);
const acc: Partial<Timeline> = {};
this.collect.push(acc);
try {
const out = buildAsset(this, def, seed, this.tracing && seed === 0 && t === 0 ? new Trace() : undefined, t);
// Anims keep their own frame timing; other assets are as animated as what they place.
if (!out.anim && acc.loop) out.anim = { loop: acc.loop, step: acc.step! };
this.cache.set(key, out);
return out;
} catch (e) {
const err = wrap(e, (s) => this.locFromStack(s)).within(`${def.kind} '${name}'`, def.loc);
this.failed.set(key, err);
throw err;
} finally {
this.collect.pop();
this.building.delete(name);
}
}
/** Exported asset names (no "_" prefix), in definition order. */
exported(): string[] {
return this.order.filter((n) => !n.startsWith("_"));
}
/** Expand a sheet's entries: globs match exported names, groups expand to members. */
sheetNames(s: SheetDef): string[] {
const out: string[] = [];
const add = (n: string) => { if (!out.includes(n)) out.push(n); };
for (const e of s.entries) {
if (e.includes("*")) {
const re = globRe(e);
this.exported().filter((n) => re.test(n)).forEach(add);
} else if (this.groups.has(e)) this.candidates(e).forEach(add);
else add(e);
}
return out;
}
}
function lcm(a: number, b: number): number {
return (a / gcd(a, b)) * b;
}
function shortName(f: string): string {
return f.replace(/^.*[\\/]/, "");
}