@netforge/asset-library 0.0.0-stage → 0.1.0

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@netforge/asset-library",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "The per-style asset library of the Net Forge game engine: a manifest of CC0 models and sprites addressed by library id, shared rigs and clip sets, the look composer, the example gallery, and the three.js loader the templates draw with.",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./three": "./src/three/index.ts",
+    "./vite": "./src/vite.ts",
+    "./gallery": "./manifest/gallery.ts"
+  },
+  "files": [
+    "src",
+    "!src/brand",
+    "!src/**/*.test.ts",
+    "manifest",
+    "README.md",
+    "NOTICE",
+    "LICENSES",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/netnetdev/net-forge.git",
+    "directory": "packages/asset-library"
+  },
+  "homepage": "https://github.com/netnetdev/net-forge/tree/main/packages/asset-library#readme",
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "fflate": "0.8.3",
+    "three": "0.186.1",
+    "zod": "4.4.3",
+    "@netforge/engine": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "22.20.1",
+    "@types/three": "0.186.0",
+    "tsx": "4.23.0",
+    "typescript": "5.8.3",
+    "vite": "6.4.3",
+    "vitest": "3.2.7"
+  },
+  "bugs": {
+    "url": "https://github.com/netnetdev/net-forge/issues"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "fetch-packs": "tsx scripts/fetch.ts",
+    "viewer": "vite --config viewer/vite.config.ts",
+    "shoot": "tsx scripts/shoot.ts"
+  }
 }

package/src/audio.ts

@@ -0,0 +1,43 @@
+/**
+ * The audio section as a sound bank the engine's SoundPlayer loads
+ * (`@netforge/engine/runtime`): every cue's sample URL and mix gain,
+ * and one music loop. Pure data: the engine does the playing.
+ */
+import { cueSounds, musicTracks, soundById } from "./library.js";
+import { libraryUrl, soundPath } from "./paths.js";
+
+export interface BankSound {
+  readonly url: string;
+  readonly gain: number;
+}
+
+/** Structurally the engine's `SoundBank`. */
+export interface LibrarySoundBank {
+  readonly cues: Readonly<Record<string, BankSound>>;
+  readonly music: BankSound | null;
+}
+
+export interface SoundBankOptions {
+  /** A music id (audio.music.*), or null for none. Default: the first track. */
+  readonly music?: string | null;
+  /** Cue name -> sound id overrides (e.g. { kill: "audio.sfx.big_kill" }). */
+  readonly cues?: Readonly<Record<string, string>>;
+}
+
+/** URLs and gains for every cue sound and one music loop, under the library's base URL. */
+export function soundBank(base: string, o: SoundBankOptions = {}): LibrarySoundBank {
+  const cues: Record<string, BankSound> = {};
+  for (const [cue, s] of cueSounds()) cues[cue] = { url: libraryUrl(base, soundPath(s)), gain: s.gain };
+  for (const [cue, id] of Object.entries(o.cues ?? {})) {
+    const s = soundById(id);
+    if (!s || s.kind !== "sfx") throw new Error(`${id} is not a sound effect in the library`);
+    cues[cue] = { url: libraryUrl(base, soundPath(s)), gain: s.gain };
+  }
+  let music: BankSound | null = null;
+  if (o.music !== null) {
+    const s = o.music ? soundById(o.music) : musicTracks()[0];
+    if (o.music && (!s || s.kind !== "music")) throw new Error(`${o.music} is not a music loop in the library`);
+    if (s) music = { url: libraryUrl(base, soundPath(s)), gain: s.gain };
+  }
+  return { cues, music };
+}

package/src/guide.ts

@@ -0,0 +1,54 @@
+/**
+ * The asset library as the builder model reads it: every id it may use in a
+ * style, grouped by kind with one plain line each, then how appearances dress a
+ * model. Stable text (no dates, no per-request data) so it caches in the
+ * model's system prefix.
+ */
+import { APPEARANCE_PARTS } from "@netforge/engine";
+import { library } from "./library.js";
+import { ASSET_KINDS, type LibraryStyle } from "./schema.js";
+
+const KIND_TITLE: Readonly<Record<(typeof ASSET_KINDS)[number], string>> = {
+  character: "Characters (heroes and players; animated)",
+  creature: "Creatures and enemies (animated)",
+  vehicle: "Vehicles",
+  weapon: "Weapons",
+  prop: "Props",
+  pickup: "Pickups",
+  building: "Buildings",
+  nature: "Nature",
+  food: "Food",
+  tile: "Tiles",
+};
+
+export function modelGuide(style: string): string {
+  const m = library().styles.get(style as LibraryStyle);
+  if (!m) return `No assets are stocked for style "${style}".`;
+  const lines: string[] = [
+    `## Asset library: style "${style}" (${m.assets.length} models, all CC0, all originals you can rename freely)`,
+    "",
+    "Use these ids for every model: prefab model, players.prefab, weapon model. Pick by what the thing is; name it anything original in names.json.",
+    "Body plans: biped, quadruped, flyer (hovers), blob (squashes), wheeled, static. Animated ones walk, run, attack, get hit and die by themselves.",
+  ];
+  for (const kind of ASSET_KINDS) {
+    const of = m.assets.filter((a) => a.kind === kind);
+    if (of.length === 0) continue;
+    lines.push("", `### ${KIND_TITLE[kind]}`);
+    for (const a of of) lines.push(`${a.id}: ${a.line} [${a.plan}]`);
+  }
+  lines.push(
+    "",
+    "## Appearances: dress a model so it becomes your own character",
+    "A prefab (and players) can carry appearance: { tint, accent, scale, parts }. tint shifts the model's colours toward \"#rrggbb\"; accent colours the parts; scale is 0.4 to 3 (visual only, radius is the hit size); parts adds up to 4 of:",
+    APPEARANCE_PARTS.join(", "),
+    "Use an appearance whenever the creator describes a character the library does not have as-is, and to make several enemies from one base.",
+    "",
+    "Examples",
+    '- "add a monster truck": prefab("big_wheel", { model: "style.lowpoly.monster_truck", ... }) (the truck on big_wheels).',
+    '- "make the enemies look like slimes": change each enemy prefab\'s model to style.lowpoly.slime_green, slime_pink, slime_spiky (tint them apart if you want more).',
+    '- "a storm fox that crackles": model "style.lowpoly.shiba", appearance: { tint: "#5ec8ff", accent: "#1a2a40", parts: ["antenna", "tail_bolt"] }, with a new name of your own.',
+    '- "a hero in overalls with a mustache": players.prefab "style.lowpoly.worker", players.appearance: { tint: "#2e7d32", parts: ["mustache", "hat_cap"] }.',
+    "- Unknown words resolve to the nearest library model plus an appearance; never invent an id.",
+  );
+  return lines.join("\n");
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+/**
+ * @netforge/asset-library: the per-style asset library of the NetNet
+ * game runtime. Pure data and lookups here (no
+ * three.js); the renderer side is "@netforge/asset-library/three".
+ */
+export { assetById, baseAsset, buildLibrary, cueSounds, galleryFor, idsForStyle, library, musicTracks, referenceableIds, search, soundById, stockedStyles } from "./library.js";
+export type { Library, SearchHit } from "./library.js";
+export { PART_ANCHOR, resolveLook } from "./look.js";
+export type { AnchorName, ResolvedLook, ResolvedPart } from "./look.js";
+export { bareClipName, CLIP_FALLBACK, CLIPS, clipFor, PLAN_MOTION, RIGS } from "./rigs.js";
+export type { Clip, PlanMotion, RigDef } from "./rigs.js";
+export { ASSET_KINDS, BODY_PLANS, LIBRARY_STYLES, LICENSES, SOUND_FORMATS, SOUND_ID } from "./schema.js";
+export type { AssetDef, AssetKind, AssetSource, AudioManifest, BodyPlan, GalleryEntry, LibraryStyle, PackDef, SoundDef, StyleManifest } from "./schema.js";
+export { assetPath, libraryIdsIn, libraryUrl, soundPath } from "./paths.js";
+export { soundBank } from "./audio.js";
+export type { BankSound, LibrarySoundBank, SoundBankOptions } from "./audio.js";
+export { modelGuide } from "./guide.js";
+export { inEveryStyle, restyleId } from "./restyle.js";
+// The voxel style: the voxel core the library build and the runtime share.
+export * as voxel from "./voxel.js";

package/src/library.ts

@@ -0,0 +1,199 @@
+/**
+ * The library: every asset a game can draw, by id. Loaded from the JSON
+ * manifests in ../manifest and validated once. Pure data, no three.js, so
+ * the generator, the gate, the assets service and the templates all read
+ * the same list.
+ */
+import audio from "../manifest/audio.json" with { type: "json" };
+import { GALLERY as gallery } from "../manifest/gallery.js";
+import lowpoly from "../manifest/lowpoly.json" with { type: "json" };
+import packs from "../manifest/packs.json" with { type: "json" };
+import pixel from "../manifest/pixel.json" with { type: "json" };
+import ps1 from "../manifest/ps1.json" with { type: "json" };
+import voxel from "../manifest/voxel.json" with { type: "json" };
+import { RIGS } from "./rigs.js";
+import {
+  audioManifestSchema,
+  gallerySchema,
+  packSchema,
+  styleManifestSchema,
+  type AssetDef,
+  type GalleryEntry,
+  type LibraryStyle,
+  type PackDef,
+  type SoundDef,
+  type StyleManifest,
+} from "./schema.js";
+
+export interface Library {
+  readonly packs: ReadonlyMap<string, PackDef>;
+  readonly styles: ReadonlyMap<LibraryStyle, StyleManifest>;
+  /** Every asset by id, aliases included (an alias maps to its asset). */
+  readonly byId: ReadonlyMap<string, AssetDef>;
+  readonly gallery: Readonly<Partial<Record<LibraryStyle, readonly GalleryEntry[]>>>;
+  /** The audio section: sound effects and music loops by id (audio.sfx.hit). */
+  readonly sounds: ReadonlyMap<string, SoundDef>;
+}
+
+/** Validate manifests and cross-references. Throws with every problem listed. */
+export function buildLibrary(input: { packs: unknown; styles: readonly unknown[]; gallery: unknown; audio?: unknown }): Library {
+  const issues: string[] = [];
+  const packList = packSchema.array().parse(input.packs);
+  const packMap = new Map(packList.map((p) => [p.id, p]));
+  const styles = new Map<LibraryStyle, StyleManifest>();
+  const byId = new Map<string, AssetDef>();
+  for (const raw of input.styles) {
+    const m = styleManifestSchema.parse(raw);
+    styles.set(m.style, m);
+    for (const a of m.assets) {
+      if (!a.id.startsWith(`style.${m.style}.`)) issues.push(`${a.id} is listed under style ${m.style}`);
+      if (byId.has(a.id)) issues.push(`${a.id} is listed twice`);
+      byId.set(a.id, a);
+      if ("pack" in a.source && !packMap.has(a.source.pack)) issues.push(`${a.id} names unknown pack ${a.source.pack}`);
+      if (a.rig && !RIGS[a.rig]) issues.push(`${a.id} names unknown rig ${a.rig}`);
+    }
+  }
+  for (const m of styles.values()) {
+    for (const a of m.assets) {
+      if ("base" in a.source) {
+        const base = byId.get(a.source.base);
+        if (!base) issues.push(`${a.id} is based on unknown ${a.source.base}`);
+        else if ("base" in base.source) issues.push(`${a.id}: a variant's base must be a real asset, not another variant`);
+      }
+      if ("voxelize" in a.source) {
+        const from = byId.get(a.source.voxelize);
+        if (!from) issues.push(`${a.id} voxelizes unknown ${a.source.voxelize}`);
+        else if (!("pack" in from.source)) issues.push(`${a.id}: only a model with a file can be voxelized (${a.source.voxelize} has none)`);
+      }
+      for (const al of a.aliases) {
+        if (byId.has(al)) issues.push(`alias ${al} collides with an id`);
+        byId.set(al, a);
+      }
+    }
+  }
+  const g = gallerySchema.parse(input.gallery);
+  for (const [style, entries] of Object.entries(g)) {
+    for (const e of entries) if (!byId.has(e.model)) issues.push(`gallery ${style}.${e.id} uses unknown model ${e.model}`);
+  }
+  const sounds = new Map<string, SoundDef>();
+  const cues = new Set<string>();
+  for (const s of input.audio === undefined ? [] : audioManifestSchema.parse(input.audio).sounds) {
+    if (sounds.has(s.id)) issues.push(`${s.id} is listed twice`);
+    sounds.set(s.id, s);
+    if (!packMap.has(s.source.pack)) issues.push(`${s.id} names unknown pack ${s.source.pack}`);
+    if (s.cue && cues.has(s.cue)) issues.push(`${s.id}: cue ${s.cue} already has a sound`);
+    if (s.cue) cues.add(s.cue);
+    if (s.kind === "music" && s.cue) issues.push(`${s.id}: music has no cue`);
+  }
+  if (issues.length) throw new Error(`asset library manifest:\n  - ${issues.join("\n  - ")}`);
+  return { packs: packMap, styles, byId, gallery: g, sounds };
+}
+
+let cached: Library | null = null;
+
+/** The library as shipped in this repository. */
+export function library(): Library {
+  cached ??= buildLibrary({ packs, styles: [lowpoly, pixel, ps1, voxel], gallery, audio });
+  return cached;
+}
+
+/** An asset by id or alias, or undefined. */
+export function assetById(id: string): AssetDef | undefined {
+  return library().byId.get(id);
+}
+
+/** The asset a variant ultimately draws (itself for a real asset). */
+export function baseAsset(a: AssetDef): AssetDef {
+  if ("base" in a.source) return library().byId.get(a.source.base) ?? a;
+  return a;
+}
+
+/** Canonical ids (no aliases) of one style. */
+export function idsForStyle(style: string): string[] {
+  const m = library().styles.get(style as LibraryStyle);
+  return m ? m.assets.map((a) => a.id) : [];
+}
+
+/** Ids a game may reference in a style: canonical ids and the aliases older drafts used. */
+export function referenceableIds(style: string): Set<string> {
+  const m = library().styles.get(style as LibraryStyle);
+  const out = new Set<string>();
+  for (const a of m?.assets ?? []) {
+    out.add(a.id);
+    for (const al of a.aliases) out.add(al);
+  }
+  return out;
+}
+
+/** Styles that have assets today. */
+export function stockedStyles(): LibraryStyle[] {
+  return [...library().styles.keys()];
+}
+
+const STOP = new Set(["a", "an", "the", "of", "like", "with", "and", "or", "to", "make", "add", "look", "looks", "some", "my", "for", "in", "on"]);
+
+function words(s: string): string[] {
+  return s
+    .toLowerCase()
+    .replace(/[^a-z0-9 ]+/g, " ")
+    .split(/\s+/)
+    .filter((w) => w && !STOP.has(w))
+    .map((w) => (w.length > 3 && w.endsWith("s") && !w.endsWith("ss") ? w.slice(0, -1) : w));
+}
+
+export interface SearchHit {
+  readonly asset: AssetDef;
+  readonly score: number;
+}
+
+/**
+ * Library assets that match a description ("a monster truck", "slimes",
+ * "a knight"), best first. Matches tags, the id's name and the line.
+ */
+export function search(style: string, query: string, limit = 8): SearchHit[] {
+  const q = words(query);
+  if (q.length === 0) return [];
+  const m = library().styles.get(style as LibraryStyle);
+  if (!m) return [];
+  const hits: SearchHit[] = [];
+  for (const a of m.assets) {
+    const name = a.id.split(".")[2] ?? "";
+    const tagWords = a.tags.flatMap((t) => words(t));
+    const nameWords = words(name.replace(/_/g, " "));
+    const lineWords = words(a.line);
+    let score = 0;
+    for (const w of q) {
+      if (a.tags.includes(q.join(" "))) score += 6;
+      if (tagWords.includes(w)) score += 3;
+      if (nameWords.includes(w)) score += 3;
+      if (lineWords.includes(w)) score += 1;
+    }
+    // Whole-phrase tag match ("monster truck") beats its words alone.
+    const phrase = q.join(" ");
+    if (a.tags.some((t) => t === phrase)) score += 8;
+    if (score > 0) hits.push({ asset: a, score });
+  }
+  return hits.sort((x, y) => y.score - x.score || x.asset.id.localeCompare(y.asset.id)).slice(0, limit);
+}
+
+/** The gallery of ready-made looks for a style. */
+export function galleryFor(style: string): readonly GalleryEntry[] {
+  return library().gallery[style as LibraryStyle] ?? [];
+}
+
+/** A sound by id (audio.sfx.hit, audio.music.battle_theme_a), or undefined. */
+export function soundById(id: string): SoundDef | undefined {
+  return library().sounds.get(id);
+}
+
+/** Every sound effect that plays a FeelKit cue by default, by cue name. */
+export function cueSounds(): ReadonlyMap<string, SoundDef> {
+  const out = new Map<string, SoundDef>();
+  for (const s of library().sounds.values()) if (s.kind === "sfx" && s.cue) out.set(s.cue, s);
+  return out;
+}
+
+/** The music loops, in manifest order. */
+export function musicTracks(): SoundDef[] {
+  return [...library().sounds.values()].filter((s) => s.kind === "music");
+}

package/src/look.ts

@@ -0,0 +1,112 @@
+/**
+ * The look composer (internal): base model + palette + scale + a few parts.
+ * This is how the builder turns a description ("a yellow electric critter
+ * with long ears") into a consistent, animated original from the library.
+ * Creators never see it; they describe what they want or pick from the
+ * gallery, and the model writes the look.
+ *
+ * `resolveLook` is pure and deterministic: the same model id and look give
+ * the same result on every client and in every test.
+ */
+import { appearanceSchema, type AppearanceDef, type AppearancePart } from "@netforge/engine";
+import { assetById, baseAsset } from "./library.js";
+import type { AssetDef, BodyPlan } from "./schema.js";
+
+/** Where a part goes, per body plan: an anchor and an offset in model units (0..1 of height). */
+export type AnchorName = "head" | "back" | "tail" | "face" | "wheels" | "body";
+
+export const PART_ANCHOR: Readonly<Record<AppearancePart, AnchorName>> = {
+  horns: "head",
+  ears_long: "head",
+  ears_round: "head",
+  antenna: "head",
+  crown: "head",
+  hat_cap: "head",
+  hat_top: "head",
+  mustache: "face",
+  tail: "tail",
+  tail_bolt: "tail",
+  wings: "back",
+  armor: "body",
+  backpack: "back",
+  big_wheels: "wheels",
+};
+
+/** Parts that make no sense on a plan are dropped (a mustache on a truck), with a note. */
+const PLAN_PARTS: Readonly<Record<BodyPlan, ReadonlySet<AnchorName>>> = {
+  biped: new Set(["head", "back", "tail", "face", "body"]),
+  quadruped: new Set(["head", "back", "tail", "face", "body"]),
+  flyer: new Set(["head", "back", "tail", "face", "body"]),
+  blob: new Set(["head", "back", "tail", "face", "body"]),
+  wheeled: new Set(["wheels", "body", "back"]),
+  static: new Set(["body"]),
+};
+
+export interface ResolvedPart {
+  readonly part: AppearancePart;
+  readonly anchor: AnchorName;
+}
+
+export interface ResolvedLook {
+  /** The asset whose file is drawn. */
+  readonly asset: AssetDef;
+  /** The id the game asked for (may be a variant or an alias). */
+  readonly requested: string;
+  readonly tint: number | null;
+  readonly accent: number;
+  readonly scale: number;
+  readonly parts: readonly ResolvedPart[];
+  /** Parts dropped because the body plan has no place for them. */
+  readonly dropped: readonly AppearancePart[];
+  /** Stable key: identical looks share one loaded model and one instanced draw. */
+  readonly key: string;
+}
+
+const hex = (s: string): number => Number.parseInt(s.slice(1), 16);
+
+/** Darken a colour for a default accent. */
+function shade(c: number, f: number): number {
+  const r = Math.round(((c >> 16) & 0xff) * f);
+  const g = Math.round(((c >> 8) & 0xff) * f);
+  const b = Math.round((c & 0xff) * f);
+  return (r << 16) | (g << 8) | b;
+}
+
+/** Merge a variant's built-in look under the game's own look: the game's fields win, parts are unioned. */
+function mergeLooks(base: AppearanceDef | undefined, top: AppearanceDef | undefined): AppearanceDef {
+  const parts = [...new Set([...(base?.parts ?? []), ...(top?.parts ?? [])])].slice(0, 4);
+  return appearanceSchema.parse({
+    ...(base?.tint ? { tint: base.tint } : {}),
+    ...(base?.accent ? { accent: base.accent } : {}),
+    ...(base?.scale !== undefined ? { scale: base.scale } : {}),
+    ...(top?.tint ? { tint: top.tint } : {}),
+    ...(top?.accent ? { accent: top.accent } : {}),
+    ...(top?.scale !== undefined ? { scale: (base?.scale ?? 1) * top.scale } : {}),
+    parts,
+  });
+}
+
+/** Resolve a model id and an optional look into what to draw. Throws on an unknown id. */
+export function resolveLook(modelId: string, look?: AppearanceDef): ResolvedLook {
+  const requested = assetById(modelId);
+  if (!requested) throw new Error(`unknown library id ${modelId}`);
+  const asset = baseAsset(requested);
+  const builtIn = "base" in requested.source ? requested.source.appearance : undefined;
+  const l = mergeLooks(builtIn, look);
+  const allowed = PLAN_PARTS[asset.plan];
+  const parts: ResolvedPart[] = [];
+  const dropped: AppearancePart[] = [];
+  for (const p of l.parts) {
+    const anchor = PART_ANCHOR[p];
+    if (!allowed.has(anchor)) {
+      dropped.push(p);
+      continue;
+    }
+    parts.push({ part: p, anchor });
+  }
+  const tint = l.tint ? hex(l.tint) : null;
+  const accent = l.accent ? hex(l.accent) : tint !== null ? shade(tint, 0.45) : 0x2a2a2a;
+  const scale = l.scale ?? 1;
+  const key = `${asset.id}|${tint ?? "-"}|${accent}|${scale}|${parts.map((p) => p.part).join(",")}`;
+  return { asset, requested: modelId, tint, accent, scale, parts, dropped, key };
+}

package/src/paths.ts

@@ -0,0 +1,34 @@
+/**
+ * Where a library file lives, relative to the library's base URL. Games
+ * never see these (they use library ids); only the runtime's resolver does.
+ * The base URL is the local build in dev ("./library" next to the page),
+ * and `<CDN>/ipfs/<library cid>` in production (VITE_LIBRARY_URL).
+ */
+import type { AssetDef, SoundDef } from "./schema.js";
+
+/** "style.lowpoly.truck" -> "lowpoly/truck.glb"; pixel sprites are PNG. Null for procedural and variant entries. */
+export function assetPath(a: AssetDef): string | null {
+  const src = a.source;
+  if ("procedural" in src || "base" in src) return null;
+  const [, style = "", name = ""] = a.id.split(".");
+  const ext = "path" in src && src.path.toLowerCase().endsWith(".png") ? "png" : "glb";
+  return `${style}/${name}.${ext}`;
+}
+
+/** Every library id written in a source text (a game.ts), in first-seen order. */
+export function libraryIdsIn(source: string): string[] {
+  return [...new Set(source.match(/style\.[a-z0-9]+\.[a-z][a-z0-9_]*/g) ?? [])];
+}
+
+/** Join a base URL and a library path. */
+export function libraryUrl(base: string, path: string): string {
+  return `${base.replace(/\/+$/, "")}/${path}`;
+}
+
+/** "audio.sfx.hit" -> "audio/sfx/hit.ogg"; the extension is the source file's. */
+export function soundPath(s: SoundDef): string {
+  const [, group = "", name = ""] = s.id.split(".");
+  const file = "path" in s.source ? s.source.path : s.source.url;
+  const ext = file.toLowerCase().endsWith(".mp3") ? "mp3" : "ogg";
+  return `audio/${group}/${name}.${ext}`;
+}

package/src/restyle.ts

@@ -0,0 +1,23 @@
+/**
+ * Draw a game in another art style: the same library name in that style.
+ * A game written against "style.lowpoly.ghost" draws "style.voxel.ghost"
+ * when it plays in the voxel style (a template's ?style= flag, or the game's
+ * declared style). Names a style does not carry stay as they are.
+ */
+import { assetById, library } from "./library.js";
+
+export function restyleId(id: string, style: string | null | undefined): string {
+  if (!style) return id;
+  const parts = id.split(".");
+  if (parts.length !== 3 || parts[0] !== "style" || parts[1] === style) return id;
+  const target = `style.${style}.${parts[2]}`;
+  const a = assetById(target);
+  return a ? a.id : id;
+}
+
+/** Ids plus the same name in every other style the library carries (a draft build copies what any ?style= may draw). */
+export function inEveryStyle(ids: readonly string[]): string[] {
+  const out = new Set(ids);
+  for (const id of ids) for (const style of library().styles.keys()) out.add(restyleId(id, style));
+  return [...out];
+}