@netforge/asset-library 0.0.0-stage → 0.1.0

package/src/rigs.ts

@@ -0,0 +1,140 @@
+/**
+ * Shared rigs and the common clip set ("all humanoids
+ * in a style use one skeleton, so any animation plays on any character").
+ *
+ * Every animated asset names a rig. A rig maps the runtime's canonical
+ * clips (idle, walk, run, jump, attack, shoot, hit, die) to the clip names
+ * its files carry, as a list of candidates: the first one a file has wins.
+ * "Armature|Idle" matches "Idle" (the armature prefix is ignored), and a
+ * candidate that starts with "*" matches by suffix ("*_Idle" matches
+ * "TRex_Idle"). A clip a file lacks falls back along CLIP_FALLBACK, then to
+ * a procedural move the renderer does itself (a hit flash, a sink on death).
+ *
+ * Body plans (biped, quadruped, flyer, blob, wheeled, static) pick the
+ * fallbacks and the crowd motion when hundreds share one instanced draw.
+ */
+import type { BodyPlan } from "./schema.js";
+
+export const CLIPS = ["idle", "walk", "run", "jump", "attack", "shoot", "hit", "die"] as const;
+export type Clip = (typeof CLIPS)[number];
+
+/** Where a missing clip borrows from. Null: the renderer plays it procedurally. */
+export const CLIP_FALLBACK: Readonly<Record<Clip, Clip | null>> = {
+  idle: null,
+  walk: "run",
+  run: "walk",
+  jump: "idle",
+  attack: "shoot",
+  shoot: "attack",
+  hit: null,
+  die: null,
+};
+
+export interface RigDef {
+  readonly id: string;
+  /** Canonical clip -> candidate clip names, best first. */
+  readonly clips: Readonly<Record<Clip, readonly string[]>>;
+  /** Bone or node name patterns for the head and the right hand (parts and held weapons). */
+  readonly headBone: RegExp | null;
+  readonly handBone: RegExp | null;
+  /** Ground speed in m/s at which the walk and run clips look right at 1x. */
+  readonly walkSpeed: number;
+  readonly runSpeed: number;
+}
+
+export const RIGS: Readonly<Record<string, RigDef>> = {
+  /** Kenney Mini Characters and Blocky Characters: the same node names and the same 30-clip set. */
+  kenney_humanoid: {
+    id: "kenney_humanoid",
+    clips: {
+      idle: ["idle"],
+      walk: ["walk"],
+      run: ["sprint"],
+      jump: ["jump"],
+      attack: ["attack-melee-right"],
+      shoot: ["holding-right-shoot"],
+      hit: [],
+      die: ["die"],
+    },
+    headBone: /^head$/,
+    handBone: /^arm-right$/,
+    walkSpeed: 1.6,
+    runSpeed: 4.5,
+  },
+  /**
+   * Quaternius animated models. One naming family across the packs on the
+   * library (characters, big monsters, blobs, flyers, animals, dinosaurs),
+   * with per-family spellings ("HitRecieve", "Bat_Flying").
+   */
+  quaternius: {
+    id: "quaternius",
+    clips: {
+      idle: ["Idle", "Flying_Idle", "*_Idle", "Flying", "*_Flying", "Idle_2"],
+      walk: ["Walk", "*_Walk", "Flying_Idle", "Flying", "*_Flying", "*_Forward", "Run", "*_Running", "*_Run"],
+      run: ["Run", "*_Run", "*_Running", "Gallop", "Fast_Flying", "Flying", "*_Flying", "*_Forward", "Walk", "*_Walk"],
+      jump: ["Jump", "*_Jump", "Gallop_Jump"],
+      attack: ["Punch", "Attack", "*_Attack", "Bite_Front", "Headbutt", "Attack_Headbutt", "Dagger_Attack", "Sword_Slash"],
+      shoot: ["Gun_Shoot", "Idle_Gun_Shoot", "Idle_Shoot", "Shoot", "Punch", "Attack"],
+      hit: ["HitReact", "HitRecieve", "RecieveHit", "*_Hit", "Idle_HitReact_Left", "HitRecieve_1"],
+      die: ["Death", "*_Death", "Dead"],
+    },
+    headBone: /^head$/i,
+    handBone: /^(fist|hand|wrist|lowerarm)[._]?r$/i,
+    walkSpeed: 1.6,
+    runSpeed: 5,
+  },
+};
+
+/** The clip name after any "Armature|" prefixes. */
+export function bareClipName(name: string): string {
+  const i = name.lastIndexOf("|");
+  return i >= 0 ? name.slice(i + 1) : name;
+}
+
+function matches(candidate: string, name: string): boolean {
+  const bare = bareClipName(name);
+  if (candidate.startsWith("*")) return bare.endsWith(candidate.slice(1));
+  return bare === candidate;
+}
+
+/**
+ * The file's clip to play for a canonical clip, following fallbacks; null
+ * means the renderer plays it procedurally. `names` are the clips the file has.
+ */
+export function clipFor(rig: RigDef | undefined, clip: Clip, names: readonly string[]): string | null {
+  if (!rig) return null;
+  let c: Clip | null = clip;
+  const seen = new Set<Clip>();
+  while (c && !seen.has(c)) {
+    seen.add(c);
+    for (const cand of rig.clips[c]) {
+      // Prefer the shortest match: "CharacterArmature|Idle" over a doubled export of the same clip.
+      const hit = names.filter((n) => matches(cand, n)).sort((a, b) => a.length - b.length)[0];
+      if (hit) return hit;
+    }
+    c = CLIP_FALLBACK[c];
+  }
+  return null;
+}
+
+/** Procedural crowd motion per body plan (used where hundreds share one instanced draw). */
+export interface PlanMotion {
+  /** Vertical bob, as a share of height, and its rate in cycles per metre walked. */
+  readonly bob: number;
+  readonly bobRate: number;
+  /** Side-to-side lean, radians. */
+  readonly waddle: number;
+  /** Hover height above the floor, as a share of height (flyers). */
+  readonly hover: number;
+  /** Squash and stretch on the bob (blobs). */
+  readonly squash: number;
+}
+
+export const PLAN_MOTION: Readonly<Record<BodyPlan, PlanMotion>> = {
+  biped: { bob: 0.04, bobRate: 1.5, waddle: 0.1, hover: 0, squash: 0 },
+  quadruped: { bob: 0.03, bobRate: 1.8, waddle: 0.04, hover: 0, squash: 0 },
+  flyer: { bob: 0.08, bobRate: 0.7, waddle: 0.16, hover: 0.55, squash: 0 },
+  blob: { bob: 0.06, bobRate: 1.3, waddle: 0.04, hover: 0, squash: 0.18 },
+  wheeled: { bob: 0.01, bobRate: 3, waddle: 0, hover: 0, squash: 0 },
+  static: { bob: 0, bobRate: 0, waddle: 0, hover: 0, squash: 0 },
+};

package/src/schema.ts

@@ -0,0 +1,200 @@
+/**
+ * The library manifest's shape. The manifest is the
+ * only list of what a game can draw: every entry has a library id, the pack
+ * it came from, and that pack's verified licence. Files are never in git;
+ * `scripts/fetch.ts` downloads each pack from its official source and the
+ * Net Forge asset pipeline optimizes and publishes them.
+ */
+import { appearanceSchema } from "@netforge/engine";
+import { z } from "zod";
+
+/** Styles the library is designed for. Only lowpoly and pixel are stocked today. */
+export const LIBRARY_STYLES = ["lowpoly", "pixel", "toon", "voxel", "ps1", "handdrawn"] as const;
+export type LibraryStyle = (typeof LIBRARY_STYLES)[number];
+
+/** What an asset is, for search, the gallery and the fallback shape. */
+export const ASSET_KINDS = ["character", "creature", "vehicle", "weapon", "prop", "pickup", "building", "nature", "food", "tile"] as const;
+export type AssetKind = (typeof ASSET_KINDS)[number];
+
+/** How a body moves: picks the clip fallbacks and the crowd motion (bob, waddle, hover). */
+export const BODY_PLANS = ["biped", "quadruped", "flyer", "blob", "wheeled", "static"] as const;
+export type BodyPlan = (typeof BODY_PLANS)[number];
+
+/** Licences we accept. Anything else is refused at load (permissive only). */
+export const LICENSES = ["CC0-1.0"] as const;
+
+const NAME = /^[a-z][a-z0-9_]{0,47}$/;
+const LIBRARY_ID = /^style\.[a-z0-9]+\.[a-z][a-z0-9_]{0,47}$/;
+const SHA256 = /^[0-9a-f]{64}$/;
+
+export const packSchema = z
+  .object({
+    id: z.string().regex(NAME),
+    title: z.string().min(1),
+    author: z.string().min(1),
+    /** The pack's official page, where the licence is stated. */
+    page: z.string().url(),
+    license: z.enum(LICENSES),
+    licenseUrl: z.string().url(),
+    /** How the licence was verified, and when. */
+    verified: z.object({ on: z.string().regex(/^\d{4}-\d{2}-\d{2}$/), how: z.string().min(10) }).strict(),
+    /** Where the files come from: one official archive, or per-file mirrors that state the same licence. */
+    download: z.discriminatedUnion("kind", [
+      z.object({ kind: z.literal("zip"), url: z.string().url(), sha256: z.string().regex(SHA256).optional() }).strict(),
+      z.object({ kind: z.literal("files"), host: z.string().url(), note: z.string().min(10) }).strict(),
+    ]),
+  })
+  .strict();
+
+/** Where one asset's file is: a path inside the pack archive, or a direct URL (files packs) with its source page. */
+const sourceSchema = z.union([
+  z
+    .object({
+      pack: z.string().regex(NAME),
+      path: z.string().min(1).refine((p) => !p.includes(".."), "paths stay inside the archive"),
+      sha256: z.string().regex(SHA256).optional(),
+    })
+    .strict(),
+  z
+    .object({
+      pack: z.string().regex(NAME),
+      url: z.string().url(),
+      /** The per-model page that states the licence. */
+      page: z.string().url(),
+      sha256: z.string().regex(SHA256).optional(),
+    })
+    .strict(),
+  /** Built from primitives at load (gems, cells): no file, no licence question. */
+  z.object({ procedural: z.string().regex(NAME) }).strict(),
+  /** Another library entry dressed with an appearance (e.g. a monster truck is the truck on big wheels). */
+  z.object({ base: z.string().regex(LIBRARY_ID), appearance: appearanceSchema }).strict(),
+  /**
+   * The voxel style: another entry's file rebuilt as voxels at library build time, `res` voxels
+   * tall (greedy-meshed, occlusion baked per face, each voxel riding its bone so the clips still play).
+   */
+  z.object({ voxelize: z.string().regex(LIBRARY_ID), res: z.number().int().min(4).max(96) }).strict(),
+]);
+
+const PX = z.number().int().min(0).max(4096);
+const HEX = z.string().regex(/^#[0-9a-f]{6}$/);
+
+/**
+ * How the library build cuts a pixel-style sprite out of its source file.
+ * The build applies these, then snaps every pixel to the style's palette
+ * with all-or-nothing alpha, so sprites from different packs read as one
+ * game and stay crisp when the runtime scales them (in the Net Forge asset pipeline).
+ */
+export const spriteSchema = z
+  .object({
+    /** Cut from the source first, px [x, y, w, h] (a prop or a tree out of a tilemap). */
+    crop: z.tuple([PX, PX, PX, PX]).optional(),
+    /** A background colour the build turns transparent. */
+    key: HEX.optional(),
+    /** Rectangles cleared before the crop, px [x, y, w, h] (a neighbour poking into it). */
+    clear: z.array(z.tuple([PX, PX, PX, PX])).max(8).optional(),
+    /**
+     * The pack's thick outline colour: the build strips it where it touches
+     * the outside and redraws a 1 px outline, so the sprite is its silhouette
+     * and not a dark tile (Tiny Dungeon and Pixel Platformer pad to the edge).
+     */
+    outline: HEX.optional(),
+    /** Lights itself (fire, gems, magic): the night does not darken it. */
+    glow: z.boolean().optional(),
+  })
+  .strict();
+export type SpriteDef = z.output<typeof spriteSchema>;
+
+export const assetSchema = z
+  .object({
+    id: z.string().regex(LIBRARY_ID, 'library ids look like "style.lowpoly.truck"'),
+    kind: z.enum(ASSET_KINDS),
+    plan: z.enum(BODY_PLANS),
+    /** Shared rig and clip set (rigs.ts), for animated models. */
+    rig: z.string().regex(NAME).optional(),
+    source: sourceSchema,
+    /** Height in metres the model is scaled to (sprites: tiles tall). */
+    height: z.number().positive().max(60),
+    /** One line the model reads when it picks assets. Plain, no franchise names. */
+    line: z.string().min(3).max(90),
+    /** Search words: what a creator might call it. */
+    tags: z.array(z.string().regex(/^[a-z0-9 -]+$/)).min(1).max(16),
+    /** Old ids that still resolve here (drafts written before the library). */
+    aliases: z.array(z.string().regex(LIBRARY_ID)).default([]),
+    /** Yaw that turns the model to face -z (the runtime's forward), radians. */
+    yaw: z.number().min(-Math.PI * 2).max(Math.PI * 2).default(0),
+    /** 2D styles: how the build cuts the sprite (absent: the whole file). */
+    sprite: spriteSchema.optional(),
+  })
+  .strict();
+
+export const styleManifestSchema = z
+  .object({
+    style: z.enum(LIBRARY_STYLES),
+    /** "3d" models (glTF) or "2d" sprites (PNG). */
+    dimension: z.enum(["3d", "2d"]),
+    /** Palette the style's generated art is locked to (AssetGenerator). */
+    palette: z.array(z.string().regex(/^#[0-9a-f]{6}$/)).min(4).max(32),
+    assets: z.array(assetSchema).min(1),
+  })
+  .strict();
+
+export const galleryEntrySchema = z
+  .object({
+    /** Stable id of the example, lower_snake_case. */
+    id: z.string().regex(NAME),
+    name: z.string().min(2).max(32),
+    /** One short line. */
+    line: z.string().min(3).max(60),
+    model: z.string().regex(LIBRARY_ID),
+    appearance: appearanceSchema.optional(),
+    /** Thumbnail path under the library's thumbs/ folder. */
+    thumb: z.string().regex(/^[a-z0-9_/.-]+\.(png|webp)$/),
+  })
+  .strict();
+
+export const gallerySchema = z.partialRecord(z.enum(LIBRARY_STYLES), z.array(galleryEntrySchema));
+
+/** Sound ids: "audio.sfx.hit", "audio.music.battle_theme_a". */
+export const SOUND_ID = /^audio\.(sfx|music)\.[a-z][a-z0-9_]{0,47}$/;
+/** Formats every browser decodes (Ogg Vorbis: Chrome, Firefox, Safari 17+; MP3: all). */
+export const SOUND_FORMATS = ["ogg", "mp3"] as const;
+
+/**
+ * One sound in the audio section (manifest/audio.json): a sound effect a
+ * FeelKit cue plays, or a music loop. Same rules as models: a pack with a
+ * verified CC0 licence, bytes pinned by sha256, files never in git.
+ */
+export const soundSchema = z
+  .object({
+    id: z.string().regex(SOUND_ID, 'sound ids look like "audio.sfx.hit" or "audio.music.<name>"'),
+    kind: z.enum(["sfx", "music"]),
+    /** The FeelKit cue this effect plays by default (hit, kill, levelUp, ...). */
+    cue: z.string().regex(/^[a-z][a-zA-Z0-9]{0,31}$/).optional(),
+    /** Mix level: the sample's gain so a default mix sits well (1 = as recorded). */
+    gain: z.number().positive().max(8).default(1),
+    line: z.string().min(3).max(90),
+    tags: z.array(z.string().regex(/^[a-z0-9 -]+$/)).min(1).max(16),
+    source: z.union([
+      z
+        .object({
+          pack: z.string().regex(NAME),
+          path: z.string().min(1).refine((p) => !p.includes(".."), "paths stay inside the archive"),
+          sha256: z.string().regex(SHA256),
+        })
+        .strict(),
+      z.object({ pack: z.string().regex(NAME), url: z.string().url(), page: z.string().url(), sha256: z.string().regex(SHA256) }).strict(),
+    ]),
+  })
+  .strict()
+  .refine((s) => SOUND_FORMATS.some((f) => ("path" in s.source ? s.source.path : s.source.url).toLowerCase().endsWith(`.${f}`)), "sounds are .ogg or .mp3")
+  .refine((s) => s.kind === (s.id.split(".")[1] ?? ""), "a sound's kind matches its id (audio.sfx.* or audio.music.*)");
+
+export const audioManifestSchema = z.object({ sounds: z.array(soundSchema).min(1) }).strict();
+
+export type SoundDef = z.output<typeof soundSchema>;
+export type AudioManifest = z.output<typeof audioManifestSchema>;
+export type PackDef = z.output<typeof packSchema>;
+export type AssetDef = z.output<typeof assetSchema>;
+export type AssetSource = AssetDef["source"];
+export type StyleManifest = z.output<typeof styleManifestSchema>;
+export type GalleryEntry = z.output<typeof galleryEntrySchema>;

package/src/three/animator.ts

@@ -0,0 +1,85 @@
+/**
+ * Character animation: the engine runtime's AnimatedCharacter (skinned
+ * glTF, locomotion crossfades, ground-speed playback) driven through the
+ * library's shared rigs. The rig maps the canonical clips (idle, walk, run,
+ * attack, shoot, hit, die) to whatever each pack calls them, so templates
+ * never deal in file clip names.
+ */
+import { AnimatedCharacter } from "@netforge/engine/runtime";
+import type { AnimationClip, Object3D } from "three/webgpu";
+import { clipFor, type Clip, type RigDef } from "../rigs.js";
+
+export interface CharacterAnimator {
+  /** Ground speed in m/s: picks idle, walk or run and matches playback rate. */
+  setSpeed(mps: number): void;
+  /** Play a canonical clip; `once` returns to locomotion when it ends; `hold` stays on its last frame. False when the rig has no such clip. */
+  play(clip: Clip, opts?: { once?: boolean; hold?: boolean }): boolean;
+  update(dt: number): void;
+  /** The file clip playing now, or null. */
+  readonly playing: string | null;
+  dispose(): void;
+}
+
+/** A model with no clips: every call is a no-op. */
+export class StaticAnimator implements CharacterAnimator {
+  readonly playing = null;
+  setSpeed(): void {}
+  play(): boolean {
+    return false;
+  }
+  update(): void {}
+  dispose(): void {}
+}
+
+/** CharacterAnimator over the engine's AnimatedCharacter. */
+export class RigAnimator implements CharacterAnimator {
+  readonly character: AnimatedCharacter;
+  private readonly names: string[];
+  private held = false;
+
+  constructor(root: Object3D, clips: readonly AnimationClip[], private readonly rig: RigDef) {
+    this.names = clips.map((c) => c.name);
+    const pick = (c: Clip) => clipFor(rig, c, this.names) ?? undefined;
+    const idle = pick("idle");
+    const walk = pick("walk");
+    const run = pick("run");
+    this.character = new AnimatedCharacter(root, clips, {
+      clips: { ...(idle ? { idle } : {}), ...(walk ? { walk } : {}), ...(run ? { run } : {}) },
+      walkSpeed: rig.walkSpeed,
+      runSpeed: rig.runSpeed,
+    });
+  }
+
+  get playing(): string | null {
+    return this.character.playing;
+  }
+
+  setSpeed(mps: number): void {
+    if (!this.held) this.character.setSpeed(mps);
+  }
+
+  play(clip: Clip, opts: { once?: boolean; hold?: boolean } = {}): boolean {
+    const name = clipFor(this.rig, clip, this.names);
+    if (!name) return false;
+    if (opts.hold) {
+      this.held = true;
+      return this.character.play(name, { loop: "once" });
+    }
+    this.held = false;
+    if (opts.once) return this.character.oneShot(name);
+    if (clip === "idle" || clip === "walk" || clip === "run") {
+      // Back to locomotion: the engine picks idle, walk or run from the ground speed.
+      this.character.setSpeed(0);
+      return true;
+    }
+    return this.character.play(name);
+  }
+
+  update(dt: number): void {
+    this.character.update(dt);
+  }
+
+  dispose(): void {
+    this.character.dispose();
+  }
+}

package/src/three/client.ts

@@ -0,0 +1,191 @@
+/**
+ * The library on the client: resolve a library id (and a look) to something
+ * drawable. Models load through the engine runtime's AssetLoader (meshopt
+ * and KTX2 decoding, one fetch per id) unless a ModelSource is given.
+ * Every method rejects when the file is missing (offline with no library
+ * built, or a bad base URL); templates catch that and keep their primitive
+ * shapes, so a game always draws.
+ *
+ * Network: one GET per distinct library id, cached for the session. No
+ * chain reads.
+ */
+import type { AppearanceDef } from "@netforge/engine";
+import { AssetLoader, markSprite, markSpriteMaterial, SPRITE_TEXEL, spriteBillboardNode } from "@netforge/engine/runtime";
+import type { RendererHandle } from "@netforge/engine/runtime";
+import { Color, DoubleSide, Group, Mesh, MeshStandardNodeMaterial, NearestFilter, Object3D, PlaneGeometry, SRGBColorSpace, TextureLoader } from "three/webgpu";
+import { float, texture, uv, vec2, vec3, vec4 } from "three/tsl";
+import { resolveLook, type ResolvedLook } from "../look.js";
+import { assetPath, libraryUrl } from "../paths.js";
+import { restyleId } from "../restyle.js";
+import { RIGS } from "../rigs.js";
+import { RigAnimator, StaticAnimator, type CharacterAnimator } from "./animator.js";
+import { bakeCrowd, poseModel, type CrowdModel } from "./crowd.js";
+import { proceduralAsset } from "./parts.js";
+import { prepareModel, type LoadedModel, type PreparedModel } from "./prepare.js";
+
+/** Anything that can load a glTF by library id (the engine's AssetLoader fits). */
+export interface ModelSource {
+  load(id: string): Promise<LoadedModel>;
+}
+
+export interface LibraryClientOptions {
+  /** Base URL of the built library: "./library" next to the page in dev, `<CDN>/ipfs/<cid>` in production. */
+  readonly baseUrl: string;
+  /** Where basis_transcoder.js/.wasm are served, for KTX2 textures. */
+  readonly transcoderPath?: string;
+  readonly source?: ModelSource;
+  /**
+   * The game's art style (game({ style })): a model id from another style
+   * draws this style's model of the same name when the style stocks one
+   * (`style.lowpoly.ghost` -> `style.ps1.ghost`).
+   */
+  readonly style?: string;
+}
+
+/**
+ * Pixel scale of a sprite asked to stand `wanted` m tall: 1 (its own
+ * pixels) for anything near its natural size, 2 for the big ones (bosses,
+ * trees), so the picture keeps one or two pixel sizes and never a smear.
+ */
+export function spriteMultiple(wanted: number, natural: number): number {
+  return natural > 0 && wanted / natural >= 2.2 ? 2 : 1;
+}
+
+export interface CharacterInstance extends PreparedModel {
+  readonly animator: CharacterAnimator;
+  readonly look: ResolvedLook;
+}
+
+export class LibraryClient {
+  private readonly source: ModelSource;
+  private readonly crowds = new Map<string, Promise<CrowdModel>>();
+
+  constructor(handle: RendererHandle | null, private readonly opts: LibraryClientOptions) {
+    if (opts.source) this.source = opts.source;
+    else {
+      if (!handle) throw new Error("LibraryClient needs a renderer or a ModelSource");
+      const loader = new AssetLoader(handle.renderer, { resolve: (id) => this.url(id), transcoderPath: opts.transcoderPath ?? `${opts.baseUrl.replace(/\/+$/, "")}/basis/` });
+      this.source = { load: (id) => loader.load(id) };
+    }
+  }
+
+  /** The URL a library id is fetched from. Throws for ids with no file. */
+  url(id: string): string {
+    const look = resolveLook(id);
+    const path = assetPath(look.asset);
+    if (!path) throw new Error(`${id} has no file (procedural or variant)`);
+    return libraryUrl(this.opts.baseUrl, path);
+  }
+
+  private async loaded(look: ResolvedLook): Promise<LoadedModel> {
+    return this.source.load(look.asset.id);
+  }
+
+  private isSprite(look: ResolvedLook): boolean {
+    return assetPath(look.asset)?.endsWith(".png") ?? false;
+  }
+
+  /**
+   * A 2D sprite as an upright plane, feet at y = 0, in metres at
+   * SPRITE_TEXEL per source pixel (times a whole multiple), pixels kept
+   * crisp. Marked for billboarding (crowds and characters face the camera).
+   * Lit like the scene but carrying its own colour as emissive, so a sprite
+   * reads at night; `glow` sprites (fire, gems) light themselves fully.
+   */
+  private async sprite(look: ResolvedLook, height?: number, hero = false): Promise<{ geometry: PlaneGeometry; material: MeshStandardNodeMaterial; height: number }> {
+    const tex = await new TextureLoader().loadAsync(this.url(look.asset.id));
+    tex.magFilter = NearestFilter;
+    tex.minFilter = NearestFilter;
+    tex.generateMipmaps = false;
+    tex.colorSpace = SRGBColorSpace;
+    const img = tex.image as { width: number; height: number };
+    const natural = img.height * SPRITE_TEXEL;
+    // A character (a player) stands about twice as tall as the 16 px crowd, in whole pixel multiples, so a player finds themself at once.
+    const k = Math.max(hero ? Math.max(1, Math.round(32 / img.height)) : 1, spriteMultiple((height ?? look.asset.height) * look.scale, natural));
+    const h = natural * k;
+    const geometry = new PlaneGeometry(img.width * SPRITE_TEXEL * k, h);
+    geometry.translate(0, h / 2, 0);
+    markSprite(geometry);
+    const material = new MeshStandardNodeMaterial({ map: tex, emissiveMap: tex, side: DoubleSide, roughness: 1, metalness: 0 });
+    // As a node, not `alphaTest`: NodeMaterial.clone() drops `alphaTest` (three r186), and templates clone crowd materials.
+    material.alphaTestNode = float(0.5);
+    material.emissive.setRGB(1, 1, 1);
+    material.emissiveIntensity = look.asset.sprite?.glow ? 1 : hero ? 0.6 : 0.45;
+    if (hero) {
+      // The player: full colour (no tint) and a 1 px ember rim where the silhouette meets the clear, the brightest thing on screen.
+      const t = texture(tex);
+      const step = vec2(1 / Math.max(1, img.width), 1 / Math.max(1, img.height));
+      const at = (dx: number, dy: number) => texture(tex, uv().add(step.mul(vec2(dx, dy)))).a;
+      const edge = t.a.greaterThan(0.5).and(at(1, 0).min(at(-1, 0)).min(at(0, 1)).min(at(0, -1)).lessThan(0.5));
+      const rim = vec3(1, 0.86, 0.35);
+      // Unlit: its own colours whatever the lantern at its feet does (lit, it washed out to white).
+      material.colorNode = vec4(vec3(0), t.a);
+      material.emissiveNode = edge.select(rim.mul(0.85), t.rgb.mul(0.65));
+    } else if (look.tint !== null) material.color.setHex(look.tint).lerp(new Color(1, 1, 1), 0.5);
+    markSpriteMaterial(material);
+    return { geometry, material, height: h };
+  }
+
+  /** An animated character for the scene (players, bosses, a few dozen at most). */
+  async character(modelId: string, look?: AppearanceDef, opts: { height?: number } = {}): Promise<CharacterInstance> {
+    const l = resolveLook(restyleId(modelId, this.opts.style), look);
+    const src = l.asset.source;
+    if ("procedural" in src) {
+      const p = proceduralAsset(src.procedural);
+      if (!p) throw new Error(`unknown procedural asset ${src.procedural}`);
+      const root = new Group();
+      const mesh = new Mesh(p.geometry, p.material);
+      root.add(mesh);
+      return { root, model: mesh, height: 0.5, width: 0.5, depth: 0.5, hand: null, animator: new StaticAnimator(), look: l };
+    }
+    if (this.isSprite(l)) {
+      const s = await this.sprite(l, opts.height, true);
+      const root = new Group();
+      // One character, so it faces the camera from its own node (crowds billboard in AnimatedCrowd).
+      s.material.positionNode = spriteBillboardNode();
+      const mesh = new Mesh(s.geometry, s.material);
+      root.add(mesh);
+      return { root, model: mesh, height: s.height, width: s.height, depth: 0.05, hand: null, animator: new StaticAnimator(), look: l };
+    }
+    const loaded = await this.loaded(l);
+    const prepared = prepareModel(loaded, l, opts);
+    const rig = l.asset.rig ? RIGS[l.asset.rig] : undefined;
+    const animator = rig && loaded.animations.length ? new RigAnimator(prepared.model, loaded.animations, rig) : new StaticAnimator();
+    return { ...prepared, animator, look: l };
+  }
+
+  /** A static prop (trees, buildings, held weapons). */
+  async prop(modelId: string, look?: AppearanceDef, opts: { height?: number } = {}): Promise<Object3D> {
+    return (await this.character(modelId, look, opts)).root;
+  }
+
+  /** Static instanced parts for crowds. Cached per model, look and height. */
+  crowd(modelId: string, look?: AppearanceDef, opts: { height?: number } = {}): Promise<CrowdModel> {
+    const l = resolveLook(restyleId(modelId, this.opts.style), look);
+    const key = `${l.key}|${opts.height ?? "-"}`;
+    let p = this.crowds.get(key);
+    if (!p) {
+      p = this.buildCrowd(l, opts);
+      p.catch(() => this.crowds.delete(key));
+      this.crowds.set(key, p);
+    }
+    return p;
+  }
+
+  private async buildCrowd(l: ResolvedLook, opts: { height?: number }): Promise<CrowdModel> {
+    const src = l.asset.source;
+    if ("procedural" in src) {
+      const p = proceduralAsset(src.procedural);
+      if (!p) throw new Error(`unknown procedural asset ${src.procedural}`);
+      return { parts: [{ geometry: p.geometry, material: p.material }], height: 0.5, triangles: 0 };
+    }
+    if (this.isSprite(l)) {
+      const s = await this.sprite(l, opts.height);
+      return { parts: [{ geometry: s.geometry, material: s.material }], height: s.height, triangles: 2 };
+    }
+    const loaded = await this.loaded(l);
+    const prepared = prepareModel(loaded, l, opts);
+    poseModel(prepared, loaded.animations, l.asset.rig ? RIGS[l.asset.rig] : undefined);
+    return bakeCrowd(prepared);
+  }
+}