@nano133/nanoterra 0.2.0 → 0.3.0

package/dist/model/index.d.ts

@@ -0,0 +1,2 @@
+export { checkModel, modelSummary, sniffTexture, type ModelCheck, type ModelFacts, type ModelProblem, type ModelRule, type TextureFact, type Vec3 } from "./check.js";
+export { BACK_ITEM, COSMETIC_LIMITS, HAND_ITEM, HEAD_ITEM, ISLAND_MODEL, PLAIN_EXTENSIONS, type MarkerRule, type ModelLimits, type ZoneBox, type ZoneDisc } from "./limits.js";

package/dist/model/index.js

@@ -0,0 +1,5 @@
+// "@nano133/nanoterra/model": the 3D model check. Pure: no Three.js, no network, no DOM. It reads a .glb from its bytes and says what is
+// wrong with it (with a fix for each), what it measured and how to make it lighter, against a preset of limits: an island model, or a
+// cosmetic for one of the character's three sockets (head, hand, back).
+export { checkModel, modelSummary, sniffTexture } from "./check.js";
+export { BACK_ITEM, COSMETIC_LIMITS, HAND_ITEM, HEAD_ITEM, ISLAND_MODEL, PLAIN_EXTENSIONS } from "./limits.js";

package/dist/model/limits.d.ts

@@ -0,0 +1,103 @@
+/** A named node the model must (or may) have. `empty`: a node with no mesh (a point, as `nano_door`); `mesh`: a node with a mesh that is never drawn (a collider). */
+export type MarkerRule = {
+    name: string;
+    required: boolean;
+    kind: "empty" | "mesh"; /** A `mesh` marker's own triangle limit (it is not counted in `maxTriangles`). */
+    maxTriangles?: number; /** What the marker is for, in plain words, for a fix line. */
+    purpose: string;
+};
+export type ZoneBox = {
+    width: number;
+    depth: number;
+    height: number;
+    below: number;
+};
+export type ZoneDisc = {
+    radius: number;
+    height: number;
+    below: number;
+};
+export type ModelLimits = {
+    /** What the model is, for a fix line ("island model"). */
+    what: string;
+    /** The whole .glb, in bytes. */
+    maxBytes: number;
+    /** The JSON chunk, in bytes (the model's description; the data is in the BIN chunk). */
+    maxJsonBytes: number;
+    /** Triangles drawn, every mesh instance counted, the `mesh` markers left out. */
+    maxTriangles: number;
+    /** Draw calls: each part (glTF primitive) of each drawn mesh instance. Left out: no limit. */
+    maxDraws?: number;
+    /** Images in the file. */
+    maxTextures: number;
+    /** The longest side of each image, in pixels. */
+    maxTextureSide: number;
+    /**
+     * The build zone, in metres, in the model's own axes (glTF: +Y up). A box: x from -width/2 to width/2, z from -depth/2
+     * to depth/2. A disc: every point at most `radius` from the y axis (x and z together). Both: y from -below to height.
+     * The model's origin is the middle of the plot, on the ground.
+     */
+    zone: ZoneBox | ZoneDisc;
+    markers: readonly MarkerRule[];
+    /**
+     * A marker whose origin is the attach point (a hand item's `grip_R`): when the file has it, the zone is measured from it, not from the
+     * file's origin. It should be one of `markers` too (so a misspelt name gets a fix line).
+     */
+    anchor?: string;
+    /** The glTF extensions the file may use (plain data only). Every other one is refused. */
+    extensions: readonly string[];
+    /** Animations, skins and morph targets: refused unless allowed. When allowed, the zone is checked in the rest pose only. */
+    allowAnimations: boolean;
+    allowSkins: boolean;
+    allowMorphTargets: boolean;
+    /** Caps on the description, so a hostile file costs little to read. */
+    maxNodes: number;
+    maxMeshes: number;
+    maxPrimitives: number;
+    maxAccessors: number;
+    maxBufferViews: number;
+    maxMaterials: number;
+    /** The node tree's depth. */
+    maxDepth: number;
+    /** Vertex reads for the exact zone check (every rotated instance reads its vertices); past it, the box of each instance is used (larger, never smaller). */
+    maxVertexWork: number;
+    /** The whole check ends by then (ms). */
+    maxMs: number;
+};
+/** The texture compression and material extensions three.js reads as plain data. */
+export declare const PLAIN_EXTENSIONS: readonly ["KHR_texture_transform", "KHR_texture_basisu", "EXT_texture_webp", "KHR_mesh_quantization", "KHR_materials_emissive_strength", "KHR_materials_unlit", "KHR_materials_ior", "KHR_materials_specular", "KHR_materials_clearcoat", "KHR_materials_sheen", "KHR_materials_transmission", "KHR_materials_volume", "KHR_materials_iridescence", "KHR_materials_anisotropy", "KHR_materials_dispersion", "KHR_xmp_json_ld"];
+/**
+ * A creator's island model (the creator islands gameplan, phase 2; Wes approved it on 2026-10-27): the entry of their
+ * game on their plot. 5 MB, 50,000 triangles, 8 textures of at most 1,024 px, inside a disc of 10 m radius (20 m across)
+ * and 18 m high on the plot's middle: the plot's free middle (PLOT_FREE_R in app/nanoterra/wheel/plots.ts; Wes chose the
+ * disc over a 24 x 24 m box on 2026-10-28, as the box reached the gates' standing places); an empty `nano_door` where Play stands, an optional empty `nano_spawn` (the arrival point) and an
+ * optional simple `nano_collide` mesh. No lights, no scripts, nothing outside the file. A still model for now.
+ */
+export declare const ISLAND_MODEL: ModelLimits;
+/**
+ * A worn thing on the character's head socket (@nano133/nanoterra/character, `socket("head")`; Wes approved the cosmetic limits on
+ * 2026-10-28). The origin is the socket's point, the middle of the hat frame of the Classic's head, in metres for a character
+ * 2.29 m tall (the socket scales it to every other head). The zone is 0.9 x 0.9 m and 0.8 m high, from 0.1 m below the origin.
+ * 3,000 triangles, 1 texture of at most 512 px, 2 draws, 300 KB. Rigid: no skin, no animation (it rides its bone).
+ */
+export declare const HEAD_ITEM: ModelLimits;
+/**
+ * A worn thing in the character's right hand (`socket("hand")`). Its attach point is its `grip_R` marker (an empty node where the right
+ * hand holds it), else the file's origin; a `grip_L` marker (where a left hand would hold it) is allowed. The zone is 0.96 x 0.68 m and
+ * 1.6 m long, from 1.17 m below the grip to 0.43 m above it: a tool held near its top, as a shovel by its T-handle (Wes chose this zone on
+ * 2026-10-28 over the first 0.4 x 0.4 m from 0.3 m below, which the example shovel did not fit). 3,000 triangles, 1 texture of at most
+ * 512 px, 2 draws, 300 KB.
+ */
+export declare const HAND_ITEM: ModelLimits;
+/**
+ * A worn thing on the character's back (`socket("back")`). The origin is the socket's point, on the back of the torso at the chest's
+ * height; the side that touches the body is at the origin and the bulk goes back (-Z). The zone is 1.0 m wide, 0.6 m deep (its middle at
+ * the origin) and 1.2 m high, from 0.6 m below. 4,000 triangles, 1 texture of at most 512 px, 2 draws, 400 KB.
+ */
+export declare const BACK_ITEM: ModelLimits;
+/** The cosmetic preset of each socket. */
+export declare const COSMETIC_LIMITS: {
+    readonly head: ModelLimits;
+    readonly hand: ModelLimits;
+    readonly back: ModelLimits;
+};

package/dist/model/limits.js

@@ -0,0 +1,132 @@
+// The limits a 3D model is checked against (@nano133/nanoterra/model; the README's "Model check"; on nano133.com
+// docs/agents/launch.md, "The island model"). The checker (check.ts) is general: it takes one of these objects, so each
+// kind of model (an island, a cosmetic on each socket) is a preset here with the same code. Pure data: no network, no DOM.
+/** The texture compression and material extensions three.js reads as plain data. */
+export const PLAIN_EXTENSIONS = [
+    "KHR_texture_transform",
+    "KHR_texture_basisu",
+    "EXT_texture_webp",
+    "KHR_mesh_quantization",
+    "KHR_materials_emissive_strength",
+    "KHR_materials_unlit",
+    "KHR_materials_ior",
+    "KHR_materials_specular",
+    "KHR_materials_clearcoat",
+    "KHR_materials_sheen",
+    "KHR_materials_transmission",
+    "KHR_materials_volume",
+    "KHR_materials_iridescence",
+    "KHR_materials_anisotropy",
+    "KHR_materials_dispersion",
+    "KHR_xmp_json_ld",
+];
+/**
+ * A creator's island model (the creator islands gameplan, phase 2; Wes approved it on 2026-10-27): the entry of their
+ * game on their plot. 5 MB, 50,000 triangles, 8 textures of at most 1,024 px, inside a disc of 10 m radius (20 m across)
+ * and 18 m high on the plot's middle: the plot's free middle (PLOT_FREE_R in app/nanoterra/wheel/plots.ts; Wes chose the
+ * disc over a 24 x 24 m box on 2026-10-28, as the box reached the gates' standing places); an empty `nano_door` where Play stands, an optional empty `nano_spawn` (the arrival point) and an
+ * optional simple `nano_collide` mesh. No lights, no scripts, nothing outside the file. A still model for now.
+ */
+export const ISLAND_MODEL = {
+    what: "island model",
+    maxBytes: 5 * 1024 * 1024,
+    maxJsonBytes: 1024 * 1024,
+    maxTriangles: 50_000,
+    maxTextures: 8,
+    maxTextureSide: 1024,
+    zone: { radius: 10, height: 18, below: 0 },
+    markers: [
+        { name: "nano_door", required: true, kind: "empty", purpose: "where Play stands" },
+        { name: "nano_spawn", required: false, kind: "empty", purpose: "where players arrive" },
+        { name: "nano_collide", required: false, kind: "mesh", maxTriangles: 5_000, purpose: "the simple shape players walk on" },
+    ],
+    extensions: PLAIN_EXTENSIONS,
+    allowAnimations: false,
+    allowSkins: false,
+    allowMorphTargets: false,
+    maxNodes: 4096,
+    maxMeshes: 1024,
+    maxPrimitives: 4096,
+    maxAccessors: 16_384,
+    maxBufferViews: 16_384,
+    maxMaterials: 256,
+    maxDepth: 64,
+    maxVertexWork: 4_000_000,
+    maxMs: 2_000,
+};
+/**
+ * The caps on the description of a cosmetic: a worn thing is small, so a file far past these is not one (and costs little to refuse).
+ */
+const COSMETIC_CAPS = {
+    maxJsonBytes: 256 * 1024,
+    extensions: PLAIN_EXTENSIONS,
+    allowAnimations: false,
+    allowSkins: false,
+    allowMorphTargets: false,
+    maxNodes: 256,
+    maxMeshes: 32,
+    maxPrimitives: 64,
+    maxAccessors: 1024,
+    maxBufferViews: 1024,
+    maxMaterials: 16,
+    maxDepth: 32,
+    maxVertexWork: 500_000,
+    maxMs: 1_000,
+};
+/**
+ * A worn thing on the character's head socket (@nano133/nanoterra/character, `socket("head")`; Wes approved the cosmetic limits on
+ * 2026-10-28). The origin is the socket's point, the middle of the hat frame of the Classic's head, in metres for a character
+ * 2.29 m tall (the socket scales it to every other head). The zone is 0.9 x 0.9 m and 0.8 m high, from 0.1 m below the origin.
+ * 3,000 triangles, 1 texture of at most 512 px, 2 draws, 300 KB. Rigid: no skin, no animation (it rides its bone).
+ */
+export const HEAD_ITEM = {
+    ...COSMETIC_CAPS,
+    what: "head item",
+    maxBytes: 300 * 1024,
+    maxTriangles: 3_000,
+    maxDraws: 2,
+    maxTextures: 1,
+    maxTextureSide: 512,
+    zone: { width: 0.9, depth: 0.9, height: 0.7, below: 0.1 },
+    markers: [],
+};
+/**
+ * A worn thing in the character's right hand (`socket("hand")`). Its attach point is its `grip_R` marker (an empty node where the right
+ * hand holds it), else the file's origin; a `grip_L` marker (where a left hand would hold it) is allowed. The zone is 0.96 x 0.68 m and
+ * 1.6 m long, from 1.17 m below the grip to 0.43 m above it: a tool held near its top, as a shovel by its T-handle (Wes chose this zone on
+ * 2026-10-28 over the first 0.4 x 0.4 m from 0.3 m below, which the example shovel did not fit). 3,000 triangles, 1 texture of at most
+ * 512 px, 2 draws, 300 KB.
+ */
+export const HAND_ITEM = {
+    ...COSMETIC_CAPS,
+    what: "hand item",
+    maxBytes: 300 * 1024,
+    maxTriangles: 3_000,
+    maxDraws: 2,
+    maxTextures: 1,
+    maxTextureSide: 512,
+    zone: { width: 0.96, depth: 0.68, height: 0.43, below: 1.17 },
+    markers: [
+        { name: "grip_R", required: false, kind: "empty", purpose: "where the right hand holds it" },
+        { name: "grip_L", required: false, kind: "empty", purpose: "where a left hand would hold it" },
+    ],
+    anchor: "grip_R",
+};
+/**
+ * A worn thing on the character's back (`socket("back")`). The origin is the socket's point, on the back of the torso at the chest's
+ * height; the side that touches the body is at the origin and the bulk goes back (-Z). The zone is 1.0 m wide, 0.6 m deep (its middle at
+ * the origin) and 1.2 m high, from 0.6 m below. 4,000 triangles, 1 texture of at most 512 px, 2 draws, 400 KB.
+ */
+export const BACK_ITEM = {
+    ...COSMETIC_CAPS,
+    what: "back item",
+    maxBytes: 400 * 1024,
+    maxTriangles: 4_000,
+    maxDraws: 2,
+    maxTextures: 1,
+    maxTextureSide: 512,
+    zone: { width: 1.0, depth: 0.6, height: 0.6, below: 0.6 },
+    markers: [],
+};
+/** The cosmetic preset of each socket. */
+export const COSMETIC_LIMITS = { head: HEAD_ITEM, hand: HAND_ITEM, back: BACK_ITEM };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nano133/nanoterra",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Nanoterra for a creator's game, in one package: the player's sign-in ticket, the player's character (a toon body on the island's skeleton) and the looks ladder.",
   "type": "module",
   "main": "dist/index.js",
@@ -11,6 +11,7 @@
     "./character/record": { "types": "./dist/character/pure.d.ts", "import": "./dist/character/pure.js" },
     "./ticket": { "types": "./dist/ticket/index.d.ts", "import": "./dist/ticket/index.js" },
     "./looks": { "types": "./dist/looks/index.d.ts", "import": "./dist/looks/index.js" },
+    "./model": { "types": "./dist/model/index.d.ts", "import": "./dist/model/index.js" },
     "./admin": { "types": "./dist/admin/index.d.ts", "import": "./dist/admin/index.js" },
     "./admin/conformance": { "types": "./dist/admin/conformance.d.ts", "import": "./dist/admin/conformance.js" },
     "./admin/d1": { "types": "./dist/admin/adapters/d1.d.ts", "import": "./dist/admin/adapters/d1.js" },
@@ -44,5 +45,5 @@
   },
   "homepage": "https://nano133.com/build/nanoterra",
   "license": "MIT",
-  "keywords": ["nano", "xno", "nanoterra", "sign in", "ticket", "character", "avatar", "three", "three.js", "toon", "looks", "cosmetics"]
+  "keywords": ["nano", "gltf", "glb", "model check", "xno", "nanoterra", "sign in", "ticket", "character", "avatar", "three", "three.js", "toon", "looks", "cosmetics"]
 }

package/src/admin/panel/index.ts

@@ -11,7 +11,7 @@ export type { MountedAdmin, MountOptions } from "./mount.js";
 export { ApiError, createApi } from "./api.js";
 export type { Api } from "./api.js";
 export { gameCard } from "./gameCard.js";
-export { lookPicture, shelfView } from "./shelf.js";
+export { lookPicture, previewPicture, shelfView } from "./shelf.js";
 export { DEFAULT_LOGINS_NOTE, signinsCard } from "./signins.js";
 export type { ShelfData } from "./shelf.js";
 export { aiPrompt, centsOf, changeText, ownedIds, shelfStats, soldText } from "./shelfData.js";

package/src/admin/panel/shelf.ts

@@ -45,6 +45,30 @@ export function lookPicture(l: Look): Element {
   );
 }
 
+/**
+ * A Shelf picture that shows the look on the real character. `load` gives the drawing function (a look to a PNG address, or null), and is
+ * called once, the first time a picture is asked for: let it import your preview file dynamically, so Three.js loads only when the Shelf
+ * opens (this file never imports it; the game starter's src/client/admin.ts shows how). Until the picture is drawn, and when it cannot be (no WebGL, a failure), the flat picture stays.
+ * `@nano133/nanoterra/character` has `createLookPreview` to make the drawing function.
+ */
+export function previewPicture(load: () => Promise<(l: Look) => Promise<string | null>>, fallback: (l: Look) => Element = lookPicture, size = 64): (l: Look) => Element {
+  let ready: Promise<((l: Look) => Promise<string | null>) | null> | null = null;
+  return (l) => {
+    const box = h("span", { class: "shelf-preview" }, fallback(l));
+    ready ??= load().catch(() => null);
+    const look: Look = { ...l, change: { ...l.change }, ...(l.slots ? { slots: { ...l.slots } } : {}) };
+    void ready
+      .then((render) => (render ? render(look) : null))
+      .then((src) => {
+        if (!src) return;
+        const img = h("img", { src, width: size, height: size, alt: `${l.name || "A look"} on the character` }) as HTMLImageElement;
+        box.replaceChildren(img);
+      })
+      .catch(() => undefined);
+    return box;
+  };
+}
+
 const clone = (ls: readonly Look[]): Look[] => ls.map((l) => ({ id: l.id, name: l.name, priceUsd: l.priceUsd, change: { ...l.change }, ...(l.slots ? { slots: { ...l.slots } } : {}) }));
 
 /** "wings ember, trail #ffcf5a" */

package/src/admin/panel/style.css

@@ -264,6 +264,15 @@
   background: #e8f3fb;
 }
 
+.n133-admin .shelf-preview {
+  display: grid;
+  place-items: center;
+}
+
+.n133-admin .shelf-preview img {
+  display: block;
+}
+
 .n133-admin .shelf-text {
   display: grid;
   min-width: 0;

package/src/character/bases/bee.ts

@@ -30,11 +30,13 @@ export const bee: BaseSpec = {
     addFace(c);
     if (!c.headOnly) {
       c.addBody(G.cone8, mtx(0, 0.72, -0.5, -Math.PI / 2 + 0.25, 0, 0, 0.1, 0.32, 0.1), "stripe", "hips");
-      // The wings: a bone at each shoulder blade; a long wing and a short one on it.
-      for (const [s, name] of [[1, "wing_L"], [-1, "wing_R"]] as const) {
-        c.b.bone(name, "chest", [s * 0.12, 1.4, -0.3]);
-        c.add(SPH_S, mtx(s * 0.3, 1.78, -0.4, 0.2, 0, s * 1.15, 0.4, 0.04, 0.22), "wing", name);
-        c.add(SPH_S, mtx(s * 0.36, 1.52, -0.42, 0.15, 0, s * 0.8, 0.28, 0.035, 0.15), "wing", name);
+      // The wings: a bone at each shoulder blade; a long wing and a short one on it. A back item covers them (`hideWings`): no wing, no bone.
+      if (!c.hideWings) {
+        for (const [s, name] of [[1, "wing_L"], [-1, "wing_R"]] as const) {
+          c.b.bone(name, "chest", [s * 0.12, 1.4, -0.3]);
+          c.add(SPH_S, mtx(s * 0.3, 1.78, -0.4, 0.2, 0, s * 1.15, 0.4, 0.04, 0.22), "wing", name);
+          c.add(SPH_S, mtx(s * 0.36, 1.52, -0.42, 0.15, 0, s * 0.8, 0.28, 0.035, 0.15), "wing", name);
+        }
       }
     }
     limbs(c, bee.limbs);

package/src/character/bases/spec.ts

@@ -14,5 +14,9 @@ export type BaseSpec = {
   limbs: Limbs;
   /** Where a hat sits: the hat frame's centre height (a Classic hat is built for 1.83) and its scale. */
   hat: { y: number; z?: number; s: readonly [number, number, number] };
+  /** The hand socket's place from the middle of the drawn right hand, when it is not that middle (sockets.ts). */
+  handAt?: readonly [number, number, number];
+  /** The back socket: its height (left out: the chest bone's, 1.12) and its depth (left out: the torso's radius there, behind). */
+  back?: { y: number; z?: number };
   build(c: Ctx): void;
 };

package/src/character/create.ts

@@ -7,11 +7,14 @@ import { buildWith, paintCharacter, type Made } from "./make.js";
 import { makePose, MAX_DT, type Motion } from "./pose.js";
 import { clean, DEFAULT_RECORD, resolve, toLegacy, withLegacy, type CharColors, type LookRecord } from "./record.js";
 import type { BoneName } from "./skeleton.js";
+import type { WornAdapter } from "./ctx.js";
+import { isSocketName, placeSocket, SOCKETS, type SocketName } from "./sockets.js";
 import { followCanvas, inkMaterial, makeRamp, toonMaterial } from "./toon.js";
 
 // createCharacter: the character as ONE object for a plain Three.js game. It builds the player's record (record.ts) with the kit (make.ts), binds it
 // to the island's skeleton (assemble.ts), gives it the toon material and the ink line (toon.ts) and plays the island's idle, walk, run, jump and wave
-// on it (pose.ts, solver.ts) from the numbers the game gives each frame. The body only: a worn item is the host's (ctx.ts `WornAdapter`).
+// on it (pose.ts, solver.ts) from the numbers the game gives each frame. A worn item is the host's (ctx.ts `WornAdapter`): its shapes merge into the
+// body, or its own model hangs on one of the three sockets (sockets.ts), which stay on the new bones after a rebuild.
 // The blob shadow is a part of the body (a disc on the skeleton's shadow bone): it lies on the ground under the character in a jump and shrinks.
 
 /** The character's height in metres at the record's normal size: from the soles to the top of the hair (the Classic base). Another base, hair or size is not this tall: measure it with a Box3. */
@@ -33,6 +36,8 @@ export type CharacterOptions = {
   quality?: Quality;
   /** Starts with the walk's swing and bob off, as the island does for a player who asks for less motion. */
   reducedMotion?: boolean;
+  /** Worn things (ctx.ts `WornAdapter`): shapes merged into the body, or a model on a socket. Change them with `setWorn`. */
+  worn?: readonly WornAdapter[];
 };
 
 export interface Character {
@@ -63,6 +68,17 @@ export interface Character {
   setLook(next: LookRecord | Look): void;
   /** Paints these colours over the record's, or none (`null`): the record's own come back. It builds no geometry. */
   setColors(colors: Partial<CharColors> | null): void;
+  /**
+   * An attach point: "head" (at the base's hat frame, scaled with the head), "hand" (in the right hand, on grip_R) or "back" (on the chest,
+   * behind). Add your own object to it and it follows the bone. It is the same object for the character's whole life: a new base, hair or
+   * clothes (a rebuild) moves it, with what hangs on it, to the new bones and to the new base's frame. An unknown name throws.
+   */
+  socket(name: SocketName): THREE.Object3D;
+  /**
+   * Changes the worn things. Shapes that merge (`add`) and the hair's fit build new geometry; a thing that only hangs a model on a socket
+   * builds none. The objects of the things that are no longer worn come off their socket (the game frees them: the character never does).
+   */
+  setWorn(worn: readonly WornAdapter[]): void;
   /**
    * Frees the geometries, materials and textures that the character made, and takes `object` out of its parent. Later calls to the other methods do
    * nothing.
@@ -85,6 +101,22 @@ function checkColors(colors: unknown): Partial<CharColors> {
   return out;
 }
 
+/** A worn thing that changes the body's geometry: its own shapes, or what it does to the hair, the badge, the tail or the wings. */
+const merges = (w: WornAdapter) => !!(w.add || w.fit || w.hidesBadge || w.hideTail || w.hideWings);
+
+function checkWorn(worn: unknown): readonly WornAdapter[] {
+  if (!Array.isArray(worn)) throw new TypeError("@nano133/nanoterra: worn must be a list of worn things");
+  worn.forEach((w: unknown, i) => {
+    const v = w as WornAdapter | null;
+    if (typeof v !== "object" || v === null) throw new TypeError(`@nano133/nanoterra: worn[${i}] is not an object`);
+    if (v.add !== undefined && typeof v.add !== "function") throw new TypeError(`@nano133/nanoterra: worn[${i}].add must be a function`);
+    if (v.socket !== undefined && !isSocketName(v.socket)) throw new TypeError(`@nano133/nanoterra: worn[${i}].socket must be one of ${SOCKETS.join(", ")}, not ${JSON.stringify(v.socket)}`);
+    if ((v.object === undefined) !== (v.socket === undefined)) throw new TypeError(`@nano133/nanoterra: worn[${i}] needs both a socket and an object, or neither`);
+    if (v.object !== undefined && !(v.object as THREE.Object3D)?.isObject3D) throw new TypeError(`@nano133/nanoterra: worn[${i}].object must be a THREE.Object3D`);
+  });
+  return [...worn];
+}
+
 const frozen = (rec: LookRecord): Readonly<LookRecord> => Object.freeze({ ...clean(rec) });
 
 /** A record from a record or five colours; `from`: the record the five colours go into. Throws a TypeError that says what is wrong. */
@@ -110,6 +142,15 @@ export function createCharacter(options: CharacterOptions = {}): Character {
   }
   let record: LookRecord = opts.record !== undefined ? recordOf(opts.record, null) : opts.look !== undefined ? recordOf(opts.look, null) : { ...DEFAULT_RECORD };
   let over: Partial<CharColors> | null = opts.colors === undefined ? null : checkColors(opts.colors);
+  let worn: readonly WornAdapter[] = checkWorn(opts.worn ?? []);
+  /** The three sockets: made once, moved to the new bones on every rebuild. */
+  const sockets = Object.fromEntries(
+    SOCKETS.map((n) => {
+      const g = new THREE.Group();
+      g.name = `socket-${n}`;
+      return [n, g];
+    }),
+  ) as Record<SocketName, THREE.Group>;
 
   const ramp = makeRamp();
   const toon = toonMaterial(ramp);
@@ -125,7 +166,10 @@ export function createCharacter(options: CharacterOptions = {}): Character {
   type Rig = { made: Made; a: Assembled; pose: ReturnType<typeof makePose> };
   const colorsNow = (): CharColors => ({ ...resolve(record).colors, ...over });
   function build(): Rig {
-    const made = buildWith(BASE_SPECS[resolve(record).base], resolve(record));
+    const look = resolve(record);
+    const spec = BASE_SPECS[look.base];
+    const merged = worn.filter(merges);
+    const made = buildWith(spec, look, merged.length ? { worn: merged } : {});
     paintCharacter(made, colorsNow());
     const a = assemble(made, { toon, ink: ink ?? toon });
     a.mesh.name = "character-toon";
@@ -139,10 +183,16 @@ export function createCharacter(options: CharacterOptions = {}): Character {
     a.group.scale.setScalar(HEIGHTS[record.height] ?? 1);
     object.add(a.group);
     const pose = makePose(a.list, a.bones as Record<BoneName, THREE.Bone>, unit);
+    for (const n of SOCKETS) placeSocket(sockets[n], a.bones, spec, look, n);
     return { made, a, pose };
   }
   let rig = build();
   rig.pose.rest(reducedMotion);
+  /** Hangs each worn model on its socket (in the order of the list). */
+  const hang = () => {
+    for (const w of worn) if (w.object && w.socket) sockets[w.socket].add(w.object);
+  };
+  hang();
 
   /** Frees a rig's geometry and skeleton. A rig that is replaced also leaves the object; a character that is disposed keeps its (dead) meshes, as it always did. */
   const free = (r: Rig, replaced: boolean) => {
@@ -201,10 +251,31 @@ export function createCharacter(options: CharacterOptions = {}): Character {
       over = colors === null ? null : checkColors(colors);
       paintCharacter(rig.made, colorsNow());
     },
+    socket(name) {
+      if (!isSocketName(name)) throw new TypeError(`@nano133/nanoterra: there is no socket ${JSON.stringify(name)} (the sockets are ${SOCKETS.join(", ")})`);
+      return sockets[name];
+    },
+    setWorn(next) {
+      if (disposed) return;
+      const to = checkWorn(next);
+      const rebuild = worn.some(merges) || to.some(merges);
+      for (const w of worn) if (w.object && !to.some((x) => x.object === w.object)) w.object.removeFromParent();
+      worn = to;
+      if (rebuild) {
+        const was = rig;
+        rig = build();
+        Object.assign(rig.pose.state, was.pose.state);
+        rig.pose.rest(reducedMotion);
+        free(was, true);
+      }
+      hang();
+    },
     dispose() {
       if (disposed) return;
       disposed = true;
       object.removeFromParent();
+      // The sockets leave the dead bones; what hangs on them is the game's.
+      for (const n of SOCKETS) sockets[n].removeFromParent();
       free(rig, false);
       toon.dispose();
       ink?.dispose();

package/src/character/ctx.ts

@@ -2,6 +2,7 @@ import * as THREE from "three";
 import type { Builder, Paint, Weights } from "./build.js";
 import type { Limbs } from "./limbs.js";
 import type { CharLook } from "./record.js";
+import type { SocketName } from "./sockets.js";
 
 // What a part gets to build with: the builder, the look, the size factors and the paint of each body segment (clothes.ts).
 
@@ -57,9 +58,21 @@ export type HatPart = { fit: HairFit; add(c: Ctx): void };
  * island's adapter (the shop's hats, scarves, packs, tops, buddies and blades, each fitted to every base) builds these; a game may bring its own.
  * `add` puts the thing's shapes and bones into the build after the body, in order, through the same context as the body's (`c.add`, `c.addHead`,
  * `c.b.bone`). A head item also says what it does to the hair (`fit`); the first that does decides. `hidesBadge`: the chest badge would poke through it.
- * `hideTail`: a back item (a cape, a pack, a plush) or a pinafore covers a base's tail.
+ * `hideTail`: a back item (a cape, a pack, a plush) or a pinafore covers a base's tail. `hideWings`: a back item covers a base's wings (the Bee's).
+ *
+ * A thing with its own model (a .glb, say) names a `socket` ("head", "hand" or "back", sockets.ts) and gives its `object`: `createCharacter`
+ * hangs the object on that socket (its own draws: 1 or 2 more for each thing) and still reads `fit`, `hidesBadge`, `hideTail` and `hideWings`. The game
+ * owns the object: the character never frees it. `add` is then optional (a thing can have both: merged shapes and a model).
  */
-export type WornAdapter = { fit?: HairFit; hidesBadge?: boolean; hideTail?: boolean; add(c: Ctx): void };
+export type WornAdapter = {
+  fit?: HairFit;
+  hidesBadge?: boolean;
+  hideTail?: boolean;
+  hideWings?: boolean;
+  add?(c: Ctx): void;
+  socket?: SocketName;
+  object?: THREE.Object3D;
+};
 /** A worn thing, by its older name (the same type as `WornAdapter`). */
 export type WornPart = WornAdapter;
 
@@ -79,6 +92,8 @@ export type Ctx = {
   hidesBadge: boolean;
   /** A worn back item covers the base's tail (a Critter's). */
   hideTail: boolean;
+  /** A worn back item covers the base's wings (a Bee's). */
+  hideWings: boolean;
   /** The base's arms and legs (a worn cuff follows the arm). */
   limbs: Limbs;
   /** Only the head and what sits on it (the pictures of faces and hats). */

package/src/character/index.ts

@@ -27,3 +27,5 @@ export * from "./edit.js";
 export * from "./look.js";
 export { createCharacter, HEIGHT, RADIUS, type Character, type CharacterOptions, type Quality } from "./create.js";
 export { WAVE_SECONDS, MAX_DT, type Motion } from "./pose.js";
+export { createLookPreview, type LookPreview, type LookPreviewOptions, type PreviewBody } from "./preview.js";
+export { SOCKETS, HAND_HOLD, socketFrame, placeSocket, isSocketName, type SocketName, type SocketFrame, type SocketLook } from "./sockets.js";

package/src/character/make.ts

@@ -47,6 +47,7 @@ export function makeContext(spec: BaseSpec, look: CharLook, b: Builder, opts: Ma
     fit: worn.find((w) => w.fit)?.fit ?? NO_FIT,
     hidesBadge: worn.some((w) => w.hidesBadge),
     hideTail: worn.some((w) => w.hideTail),
+    hideWings: worn.some((w) => w.hideWings),
     limbs: spec.limbs,
     headOnly,
     add,
@@ -69,7 +70,7 @@ export function buildWith(spec: BaseSpec, look: CharLook, opts: MakeOptions = {}
     // The shadow: a flat dark disc on its own bone, which stays on the floor under a hop.
     c.addBody(new THREE.CircleGeometry(0.62, 20), mtx(0, 0.02, 0, -Math.PI / 2), "shadow", "shadow", false);
   }
-  for (const w of wornOf(opts)) w.add(c);
+  for (const w of wornOf(opts)) w.add?.(c);
   return { ...b.finish(), toonTris: b.p.length / 9, inkTris: b.ip.length / 9, look };
 }
 export type Made = ReturnType<typeof buildWith>;