@nano133/nanoterra 0.1.0 → 0.3.0

package/src/admin/store.ts

@@ -0,0 +1,98 @@
+// 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.
+
+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 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/src/admin/summary.ts

@@ -0,0 +1,103 @@
+// 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";
+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 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: string): number => {
+  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: readonly { amountRaw: string; usd: string }[]): Money {
+  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: string, expiresAt: number, now: number): string => (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: readonly OrderRow[], now: number): Omit<AdminOrder, "look">[] {
+  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: readonly { player: string; lookId: string; at: number }[]): StoreSummary["players"] {
+  const players = new Map<string, { player: string; looks: { id: string; at: number }[] }>();
+  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: readonly OrderRow[], owned: readonly { player: string; lookId: string; at: number }[], rate: StoreSummary["rate"], now: number): StoreSummary {
+  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 as keyof typeof counts]++;
+  }
+  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: unknown, at: unknown): StoreSummary["rate"] {
+  if (typeof value !== "string" || typeof at !== "number") return null;
+  try {
+    const v: unknown = JSON.parse(value);
+    if (!v || typeof v !== "object") return null;
+    const { usd, sources } = v as { usd?: unknown; sources?: unknown };
+    if (typeof usd !== "number" || !Number.isFinite(usd) || !Array.isArray(sources) || !sources.every((s) => typeof s === "string")) return null;
+    return { usd, sources: sources as string[], at };
+  } catch {
+    return null;
+  }
+}

package/src/admin/switches.ts

@@ -0,0 +1,74 @@
+// 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.
+
+/** 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 const isCharacter = (v: unknown): v is Character => v === "nanoterra" || v === "own";
+export const isSigninChoice = (v: unknown): v is "exchange" | "none" => v === "exchange" || v === "none";
+export const isSignin = (v: unknown): v is Signin => v === "exchange" || v === "ticket" || v === "none";
+/** The sign-in switch is on for any way but "none". */
+export const signinOn = (s: Signin): boolean => 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: unknown): { ok: true; patch: GamePatch } | { ok: false; error: string } {
+  if (!body || typeof body !== "object" || Array.isArray(body)) return { ok: false, error: 'Send an object with "character" or "signin".' };
+  const patch: GamePatch = {};
+  for (const [key, value] of Object.entries(body as Record<string, unknown>)) {
+    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: { character?: unknown; signin?: unknown }, defaults: GameSettings): GameState {
+  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) },
+  };
+}
+
+/** One switch of the card: its title, and one plain sentence for each state. */
+export type SwitchId = "character" | "signin";
+export const SWITCHES: Record<SwitchId, { title: string; on: string; off: string }> = {
+  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: SwitchId, s: GameSettings): boolean => (id === "character" ? s.character === "nanoterra" : signinOn(s.signin));
+export const pressOf = (id: SwitchId, s: GameSettings): GamePatch => (id === "character" ? { character: s.character === "nanoterra" ? "own" : "nanoterra" } : { signin: signinOn(s.signin) ? "none" : "exchange" });

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>;