@nano133/nanoterra 0.1.0 → 0.3.0

package/dist/admin/store.d.ts

@@ -0,0 +1,121 @@
+import type { GamePatch } from "./switches.js";
+/** Money as the admin page shows it: a count, the XNO text and the US dollars as text. */
+export type Money = {
+    count: number;
+    xno: string;
+    usd: string;
+};
+export type OrderStatus = "open" | "paid" | "expired" | "paid_late";
+export type AdminOrder = {
+    id: string;
+    /** The player's Nano address. */
+    player: string;
+    lookId: string;
+    /** What the player reads for the look (the handler fills it from `lookName`). */
+    look: string;
+    usd: string;
+    xno: string;
+    status: OrderStatus | string;
+    createdAt: number;
+    expiresAt: number;
+    paidAt: number | null;
+    payer: string | null;
+    hash: string | null;
+};
+export type AdminPlayer = {
+    player: string;
+    looks: {
+        id: string;
+        name: string;
+        at: number;
+    }[];
+};
+/** The numbers of the orders and the looks that players own. */
+export type StoreSummary = {
+    counts: {
+        open: number;
+        paid: number;
+        expired: number;
+        paid_late: number;
+    };
+    totals: {
+        paid: Money;
+        paidLate: Money;
+    };
+    /** Newest first, at most 500. `look` is filled by the handler. */
+    orders: Omit<AdminOrder, "look">[];
+    /** Players and the looks that a paid order gave them. `name` is filled by the handler. */
+    players: {
+        player: string;
+        looks: {
+            id: string;
+            at: number;
+        }[];
+    }[];
+    /** The price of XNO in US dollars that the game uses, and where it came from. */
+    rate: {
+        usd: number;
+        sources: string[];
+        at: number;
+    } | null;
+};
+/**
+ * One admin sign-in, as the panel lists it: when, the rough country (two letters, or null when the game did not know it) and a short browser name ("Chrome on macOS").
+ * Nothing else: no address, no IP, no browser text. The game writes these when it makes an admin login; the package only reads them.
+ */
+export type AdminLogin = {
+    at: number;
+    country: string | null;
+    browser: string;
+};
+/** How many sign-ins the panel lists. */
+export declare const ADMIN_LOGINS_SHOWN = 10;
+/**
+ * The game's database, as the handler needs it. An adapter writes ONLY what these calls say: the two settings and, when the game turns it on, the deletion of the admin sessions
+ * (`signOutEverywhere`). Nothing else.
+ * (There is no call that writes a look, a price or an order: the Shelf gives text to copy, and a change of looks is a change of the repository.)
+ */
+export interface AdminStore {
+    /** The settings that /admin has saved. A value that is not a known word is ignored by the handler, so an adapter returns what it holds. */
+    readSettings(): Promise<{
+        character?: unknown;
+        signin?: unknown;
+    }>;
+    /** Saves a checked patch: all of it or none of it. */
+    saveSettings(patch: GamePatch, now: number): Promise<void>;
+    summary(now: number): Promise<StoreSummary>;
+    /**
+     * Optional. The last sign-ins to the admin, newest first, at most `limit`, with only the three things of `AdminLogin`. With it the summary lists them (the "Sign-ins" card).
+     * An adapter that has it must never return more than those three things for a sign-in.
+     */
+    recentLogins?(limit: number): Promise<AdminLogin[]>;
+    /**
+     * Optional. Deletes EVERY admin session (the admin login of the owner, in every browser, this one too) and no other session; returns how many it deleted. With it the handler has
+     * the route `POST {base}/signout-all` and the panel has "Sign out everywhere". An adapter must delete only sessions of the ADMIN scope.
+     */
+    signOutEverywhere?(): Promise<number>;
+}
+/** What the game says about itself on the Status card: only the game knows its address, its test mode and what is still off. */
+export type AdminStatus = {
+    address: string | null;
+    testMode: boolean;
+    /** Whether Turnstile (the bot check) is on. */
+    turnstile?: boolean;
+    /** The names of the Nano nodes that check payments. */
+    nodes?: string[];
+    /** "owner/repo" on GitHub, for the link to looks.json. */
+    repo?: string | null;
+    /** Plain sentences about what is still off. */
+    warnings: string[];
+};
+/** The whole of GET summary. */
+export type AdminSummary = AdminStatus & Omit<StoreSummary, "orders" | "players"> & {
+    orders: AdminOrder[];
+    players: AdminPlayer[];
+    /** Whether the game gave a payment check (POST check). The panel shows "Check payments now" only then. */
+    canCheck: boolean;
+    /** The last admin sign-ins (newest first), when the store can list them. */
+    logins?: AdminLogin[];
+    /** Whether the route "sign out everywhere" exists (the store can do it). */
+    canSignOutEverywhere?: boolean;
+};

package/dist/admin/store.js

@@ -0,0 +1,3 @@
+// What a game gives the admin handler: a store (an adapter for its database) and a status. The package has no database of its own.
+/** How many sign-ins the panel lists. */
+export const ADMIN_LOGINS_SHOWN = 10;

package/dist/admin/summary.d.ts

@@ -0,0 +1,39 @@
+import type { AdminOrder, Money, StoreSummary } from "./store.js";
+/** An order as an adapter reads it: the amount is the raw amount (digits), the times are ms. */
+export type OrderRow = {
+    id: string;
+    player: string;
+    lookId: string;
+    usd: string;
+    amountRaw: string;
+    status: string;
+    createdAt: number;
+    expiresAt: number;
+    paidAt: number | null;
+    payer: string | null;
+    hash: string | null;
+};
+export declare const ORDERS_SHOWN = 500;
+/** Money from rows that are all of one status: the count, the XNO text of the raw sum and the dollars (summed in cents, so 0.1 + 0.2 is 0.30). */
+export declare function moneyOf(rows: readonly {
+    amountRaw: string;
+    usd: string;
+}[]): Money;
+/** Where an order counts: an open order past its expiry counts as expired. */
+export declare const statusOf: (status: string, expiresAt: number, now: number) => string;
+/** The orders as the page lists them: newest first, at most ORDERS_SHOWN, an open one past its expiry read as "expired". */
+export declare function shapeOrders(rows: readonly OrderRow[], now: number): Omit<AdminOrder, "look">[];
+/** The looks that players own, by player (players and their looks in a steady order). */
+export declare function shapePlayers(owned: readonly {
+    player: string;
+    lookId: string;
+    at: number;
+}[]): StoreSummary["players"];
+/** The whole summary from ALL the rows (for a store that reads the rows itself: Firestore, memory). */
+export declare function summarize(rows: readonly OrderRow[], owned: readonly {
+    player: string;
+    lookId: string;
+    at: number;
+}[], rate: StoreSummary["rate"], now: number): StoreSummary;
+/** The `rate` row of the meta table: JSON { usd, sources } kept with the time. Anything that is not that is no rate. */
+export declare function parseRate(value: unknown, at: unknown): StoreSummary["rate"];

package/dist/admin/summary.js

@@ -0,0 +1,85 @@
+// The numbers of the summary from the rows of the orders, the same for every adapter: the counts by status, the totals and the shape of an order.
+// An adapter reads its rows; this file turns them into a `StoreSummary`.
+import { isRawText, xnoText } from "./amount.js";
+export const ORDERS_SHOWN = 500;
+/** Cents from a dollar text like "0.25". Anything that is not plain dollars (a sign, an exponent, hex) counts as 0: a bad row must not change a total. */
+const toCents = (usd) => {
+    if (typeof usd !== "string" || !/^\d{1,9}(\.\d{1,8})?$/.test(usd))
+        return 0;
+    return Math.round(Number(usd) * 100);
+};
+/** Money from rows that are all of one status: the count, the XNO text of the raw sum and the dollars (summed in cents, so 0.1 + 0.2 is 0.30). */
+export function moneyOf(rows) {
+    let raw = 0n;
+    let cents = 0;
+    for (const r of rows) {
+        if (isRawText(r.amountRaw))
+            raw += BigInt(r.amountRaw);
+        cents += toCents(r.usd);
+    }
+    return { count: rows.length, xno: xnoText(raw.toString()), usd: (cents / 100).toFixed(2) };
+}
+/** Where an order counts: an open order past its expiry counts as expired. */
+export const statusOf = (status, expiresAt, now) => (status === "open" && expiresAt < now ? "expired" : status);
+/** The orders as the page lists them: newest first, at most ORDERS_SHOWN, an open one past its expiry read as "expired". */
+export function shapeOrders(rows, now) {
+    return [...rows]
+        .sort((a, b) => b.createdAt - a.createdAt || (a.id < b.id ? -1 : 1))
+        .slice(0, ORDERS_SHOWN)
+        .map((o) => ({
+        id: o.id,
+        player: o.player,
+        lookId: o.lookId,
+        usd: o.usd,
+        xno: isRawText(o.amountRaw) ? xnoText(o.amountRaw) : "0",
+        status: statusOf(o.status, o.expiresAt, now),
+        createdAt: o.createdAt,
+        expiresAt: o.expiresAt,
+        paidAt: o.paidAt,
+        payer: o.payer,
+        hash: o.hash,
+    }));
+}
+/** The looks that players own, by player (players and their looks in a steady order). */
+export function shapePlayers(owned) {
+    const players = new Map();
+    for (const o of [...owned].sort((a, b) => (a.player < b.player ? -1 : a.player > b.player ? 1 : a.at - b.at))) {
+        const p = players.get(o.player) ?? { player: o.player, looks: [] };
+        p.looks.push({ id: o.lookId, at: o.at });
+        players.set(o.player, p);
+    }
+    return [...players.values()];
+}
+/** The whole summary from ALL the rows (for a store that reads the rows itself: Firestore, memory). */
+export function summarize(rows, owned, rate, now) {
+    const counts = { open: 0, paid: 0, expired: 0, paid_late: 0 };
+    for (const o of rows) {
+        const key = statusOf(o.status, o.expiresAt, now);
+        if (Object.hasOwn(counts, key))
+            counts[key]++;
+    }
+    return {
+        counts,
+        totals: { paid: moneyOf(rows.filter((o) => o.status === "paid")), paidLate: moneyOf(rows.filter((o) => o.status === "paid_late")) },
+        orders: shapeOrders(rows, now),
+        players: shapePlayers(owned),
+        rate,
+    };
+}
+/** The `rate` row of the meta table: JSON { usd, sources } kept with the time. Anything that is not that is no rate. */
+export function parseRate(value, at) {
+    if (typeof value !== "string" || typeof at !== "number")
+        return null;
+    try {
+        const v = JSON.parse(value);
+        if (!v || typeof v !== "object")
+            return null;
+        const { usd, sources } = v;
+        if (typeof usd !== "number" || !Number.isFinite(usd) || !Array.isArray(sources) || !sources.every((s) => typeof s === "string"))
+            return null;
+        return { usd, sources: sources, at };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/admin/switches.d.ts

@@ -0,0 +1,58 @@
+/** Which character the player is: Nanoterra's island character (the one the player has there) or the game's own. */
+export type Character = "nanoterra" | "own";
+/** How the game signs a Nanoterra player in: the code exchange, a signed ticket (a game with no server), or not at all. */
+export type Signin = "exchange" | "ticket" | "none";
+export type GameSettings = {
+    character: Character;
+    signin: Signin;
+};
+/** What a press can set: sign-in is on ("exchange": a game with a server) or off ("none"). */
+export type GamePatch = {
+    character?: Character;
+    signin?: "exchange" | "none";
+};
+/** The settings as they are now, and which ones /admin has set (the others still have the game's default). */
+export type GameState = GameSettings & {
+    fromAdmin: {
+        character: boolean;
+        signin: boolean;
+    };
+};
+export declare const isCharacter: (v: unknown) => v is Character;
+export declare const isSigninChoice: (v: unknown) => v is "exchange" | "none";
+export declare const isSignin: (v: unknown) => v is Signin;
+/** The sign-in switch is on for any way but "none". */
+export declare const signinOn: (s: Signin) => boolean;
+/** A request body for a press: only the two known words, at least one. Anything else is refused, with the reason in words. */
+export declare function parsePatch(body: unknown): {
+    ok: true;
+    patch: GamePatch;
+} | {
+    ok: false;
+    error: string;
+};
+/** The settings from what the store kept and the game's defaults. A stored value that is not one of the known words is ignored. */
+export declare function mergeSettings(stored: {
+    character?: unknown;
+    signin?: unknown;
+}, defaults: GameSettings): GameState;
+/** One switch of the card: its title, and one plain sentence for each state. */
+export type SwitchId = "character" | "signin";
+export declare const SWITCHES: Record<SwitchId, {
+    title: string;
+    on: string;
+    off: string;
+}>;
+/**
+ * The character comes through the sign-in: only a player who signs in from Nanoterra brings one. So the character switch is shown with its dependency. With sign-in Off the
+ * card says what a player gets: the island's first character, every player, a player who signed in from Nanoterra before included ("Off means Off"). That is the GAME's page
+ * to do (the starter's src/client/ui/player.ts draws no Nanoterra character while sign-in is Off); the card only says it.
+ */
+export declare const CHARACTER_NEEDS_SIGNIN = "This needs \u201CPlayers can sign in with Nanoterra\u201D to be On: only a player who signs in from Nanoterra brings a character.";
+export declare const CHARACTER_SIGNIN_OFF = "Sign-in from Nanoterra is Off, so every player plays as the island's first character, a player who signed in from Nanoterra before included.";
+/** What to tell the creator under the sign-in switch about Nanoterra's review. A game cannot see that review: it says so. */
+export declare const REVIEW_NOTE = "Your choice is saved here at once. The sign-in word is part of your listing file, and Nanoterra's review decides what Nanoterra shows for a game that is listed. This page cannot see that review. Check it on Nanoterra's launch page (step 6).";
+export declare const REVIEW_LINK = "https://nano133.com/build/nanoterra/launch";
+/** The state of a switch from the settings, and the patch that a press sends (the other state). */
+export declare const stateOf: (id: SwitchId, s: GameSettings) => boolean;
+export declare const pressOf: (id: SwitchId, s: GameSettings) => GamePatch;

package/dist/admin/switches.js

@@ -0,0 +1,61 @@
+// The two switches of the "Game" card in /admin, and the words that say what each does. The handler checks a press with `parsePatch`; the panel
+// draws the card from `SWITCHES`. A switch changes ONLY these two settings; never a look, a price or an order.
+export const isCharacter = (v) => v === "nanoterra" || v === "own";
+export const isSigninChoice = (v) => v === "exchange" || v === "none";
+export const isSignin = (v) => v === "exchange" || v === "ticket" || v === "none";
+/** The sign-in switch is on for any way but "none". */
+export const signinOn = (s) => s !== "none";
+/** A request body for a press: only the two known words, at least one. Anything else is refused, with the reason in words. */
+export function parsePatch(body) {
+    if (!body || typeof body !== "object" || Array.isArray(body))
+        return { ok: false, error: 'Send an object with "character" or "signin".' };
+    const patch = {};
+    for (const [key, value] of Object.entries(body)) {
+        if (key === "character" && isCharacter(value))
+            patch.character = value;
+        else if (key === "signin" && isSigninChoice(value))
+            patch.signin = value;
+        else if (key === "character")
+            return { ok: false, error: '"character" must be "nanoterra" or "own".' };
+        else if (key === "signin")
+            return { ok: false, error: '"signin" must be "exchange" or "none".' };
+        else
+            return { ok: false, error: `"${key}" is not a game switch.` };
+    }
+    if (!Object.keys(patch).length)
+        return { ok: false, error: 'Send "character" or "signin".' };
+    return { ok: true, patch };
+}
+/** The settings from what the store kept and the game's defaults. A stored value that is not one of the known words is ignored. */
+export function mergeSettings(stored, defaults) {
+    return {
+        character: isCharacter(stored.character) ? stored.character : defaults.character,
+        signin: isSigninChoice(stored.signin) ? stored.signin : defaults.signin,
+        fromAdmin: { character: isCharacter(stored.character), signin: isSigninChoice(stored.signin) },
+    };
+}
+export const SWITCHES = {
+    character: {
+        title: "Players use their Nanoterra character",
+        on: "On: a player who signs in from Nanoterra plays as the character they picked there. Anyone else plays as the island's first character.",
+        off: "Off: every player plays as this game's own character.",
+    },
+    signin: {
+        title: "Players can sign in with Nanoterra",
+        on: "On: this game's listing file says players can sign in with Nanoterra, and the game accepts that sign-in.",
+        off: "Off: the listing file says no sign-in, and the game refuses it: a link made before still signs nobody in.",
+    },
+};
+/**
+ * The character comes through the sign-in: only a player who signs in from Nanoterra brings one. So the character switch is shown with its dependency. With sign-in Off the
+ * card says what a player gets: the island's first character, every player, a player who signed in from Nanoterra before included ("Off means Off"). That is the GAME's page
+ * to do (the starter's src/client/ui/player.ts draws no Nanoterra character while sign-in is Off); the card only says it.
+ */
+export const CHARACTER_NEEDS_SIGNIN = "This needs “Players can sign in with Nanoterra” to be On: only a player who signs in from Nanoterra brings a character.";
+export const CHARACTER_SIGNIN_OFF = "Sign-in from Nanoterra is Off, so every player plays as the island's first character, a player who signed in from Nanoterra before included.";
+/** What to tell the creator under the sign-in switch about Nanoterra's review. A game cannot see that review: it says so. */
+export const REVIEW_NOTE = "Your choice is saved here at once. The sign-in word is part of your listing file, and Nanoterra's review decides what Nanoterra shows for a game that is listed. This page cannot see that review. Check it on Nanoterra's launch page (step 6).";
+export const REVIEW_LINK = "https://nano133.com/build/nanoterra/launch";
+/** The state of a switch from the settings, and the patch that a press sends (the other state). */
+export const stateOf = (id, s) => (id === "character" ? s.character === "nanoterra" : signinOn(s.signin));
+export const pressOf = (id, s) => (id === "character" ? { character: s.character === "nanoterra" ? "own" : "nanoterra" } : { signin: signinOn(s.signin) ? "none" : "exchange" });

package/dist/character/bases/bee.js

@@ -27,11 +27,13 @@ export const bee = {
         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"]]) {
-                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"]]) {
+                    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/dist/character/bases/spec.d.ts

@@ -13,5 +13,12 @@ export type BaseSpec = {
         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/dist/character/create.d.ts

@@ -2,6 +2,8 @@ import * as THREE from "three";
 import { type Look } from "./look.js";
 import { type Motion } from "./pose.js";
 import { type CharColors, type LookRecord } from "./record.js";
+import type { WornAdapter } from "./ctx.js";
+import { type SocketName } from "./sockets.js";
 /** 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. */
 export declare const HEIGHT = 2.29;
 /** The radius of the Classic's trunk in metres at the record's normal size: the collider's radius. The hands hang to 0.6 m from the middle. */
@@ -19,6 +21,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 {
     /**
@@ -48,6 +52,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.

package/dist/character/create.js

@@ -6,10 +6,12 @@ import { assertLook, recordProblem } from "./look.js";
 import { buildWith, paintCharacter } from "./make.js";
 import { makePose, MAX_DT } from "./pose.js";
 import { clean, DEFAULT_RECORD, resolve, toLegacy, withLegacy } from "./record.js";
+import { isSocketName, placeSocket, SOCKETS } 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. */
 export const HEIGHT = 2.29;
@@ -32,6 +34,26 @@ function checkColors(colors) {
     }
     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) => !!(w.add || w.fit || w.hidesBadge || w.hideTail || w.hideWings);
+function checkWorn(worn) {
+    if (!Array.isArray(worn))
+        throw new TypeError("@nano133/nanoterra: worn must be a list of worn things");
+    worn.forEach((w, i) => {
+        const v = w;
+        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?.isObject3D)
+            throw new TypeError(`@nano133/nanoterra: worn[${i}].object must be a THREE.Object3D`);
+    });
+    return [...worn];
+}
 const frozen = (rec) => 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. */
 function recordOf(next, from) {
@@ -55,6 +77,13 @@ export function createCharacter(options = {}) {
     }
     let record = opts.record !== undefined ? recordOf(opts.record, null) : opts.look !== undefined ? recordOf(opts.look, null) : { ...DEFAULT_RECORD };
     let over = opts.colors === undefined ? null : checkColors(opts.colors);
+    let worn = 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];
+    }));
     const ramp = makeRamp();
     const toon = toonMaterial(ramp);
     const ink = quality === "high" ? inkMaterial() : null;
@@ -67,7 +96,10 @@ export function createCharacter(options = {}) {
     const unit = () => (HEIGHTS[record.height] ?? 1) * (object.scale.y || 1);
     const colorsNow = () => ({ ...resolve(record).colors, ...over });
     function build() {
-        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";
@@ -82,10 +114,19 @@ export function createCharacter(options = {}) {
         a.group.scale.setScalar(HEIGHTS[record.height] ?? 1);
         object.add(a.group);
         const pose = makePose(a.list, a.bones, 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, replaced) => {
         if (replaced)
@@ -150,11 +191,37 @@ export function createCharacter(options = {}) {
             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/dist/character/ctx.d.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";
 /** A head as an ellipsoid (its middle and its radii in the avatar's space, at rest). A face, a hair and a hat sit on it. `flat`: a flat screen face at this z. */
 export type HeadSpec = {
     c: readonly [number, number, number];
@@ -53,13 +54,20 @@ export type HatPart = {
  * 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;
+    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;
@@ -81,6 +89,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/dist/character/index.d.ts

@@ -34,3 +34,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/dist/character/index.js

@@ -23,3 +23,5 @@ export * from "./edit.js";
 export * from "./look.js";
 export { createCharacter, HEIGHT, RADIUS } from "./create.js";
 export { WAVE_SECONDS, MAX_DT } from "./pose.js";
+export { createLookPreview } from "./preview.js";
+export { SOCKETS, HAND_HOLD, socketFrame, placeSocket, isSocketName } from "./sockets.js";

package/dist/character/make.js

@@ -32,6 +32,7 @@ export function makeContext(spec, look, b, opts = {}) {
         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,
@@ -55,7 +56,7 @@ export function buildWith(spec, look, opts = {}) {
         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);
+        w.add?.(c);
     return { ...b.finish(), toonTris: b.p.length / 9, inkTris: b.ip.length / 9, look };
 }
 /** Paints (or paints again) the character's colours: a colour change needs no new geometry. */