@nano133/nanoterra 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.3.0 (2026-10-28)
+
+- **Sockets** (`@nano133/nanoterra/character`): three attach points on the character, `c.socket("head" | "hand" | "back")`, each a `THREE.Object3D` on a bone
+  (`head`, `grip_R`, `chest`) that follows the walk, the run, the jump and the wave. The head socket sits at the base's hat frame and scales with it and the head's
+  size; the hand socket is in the middle of the drawn right hand (a wide build or base draws its hands further out than the bone) and holds a thing pointing
+  forward (`HAND_HOLD`); the back socket is on the back of the torso at the chest. A socket is the same object for the character's whole life: a rebuild (a new
+  base, hair or clothes) moves it, with what hangs on it, to the new bones. New: `SOCKETS`, `socketFrame`, `placeSocket`, `isSocketName`, `HAND_HOLD`, the types
+  `SocketName`, `SocketFrame`, `SocketLook`; `BaseSpec` may set `handAt` and `back`.
+- **A model on a socket**: `WornAdapter` takes an optional `socket` and `object` (and `add` is now optional). `createCharacter({ worn })` and `c.setWorn(worn)`
+  hang each object on its socket; a model on a socket builds no geometry, and its `fit`, `hidesBadge`, `hideTail` and the new `hideWings` (a back item takes the Bee's wings off, shapes and bones, as `hideTail` takes a tail off) still apply. The character never frees an
+  object that the game hung: `setWorn` takes the old ones off, and `dispose` takes the sockets off the dead bones.
+- **`@nano133/nanoterra/model`**: the 3D model check, moved here from nano133.com (`app/launch/model`, which now keeps the same code). `checkModel(bytes,
+  limits)` reads a `.glb` from its bytes, never throws, and answers the problems with a fix each, the facts and, new, **advice** (a large PNG or JPEG, 32-bit
+  positions, parts that share a material). New facts: `draws` (each part of each drawn mesh instance), `materials`, `anchor`. New limits: `maxDraws`, and
+  `anchor` (a marker whose origin is the attach point: the zone is measured from it). The cosmetic presets of Wes's table (2026-10-28): `HEAD_ITEM`,
+  `HAND_ITEM` (its anchor is `grip_R`; `grip_L` is allowed; the zone is 0.96 x 0.68 m, from 1.17 m below the grip to 0.43 m above: Wes's choice A of 2026-10-28, so that a shovel held by its T-handle fits), `BACK_ITEM`, and `COSMETIC_LIMITS` by socket; `ISLAND_MODEL` is the island's (a disc of 10 m
+  radius, 18 m high). A misspelt marker with capitals in its name (`Grip_R`) now gets its rename line too. A fix line gives a zone's number with two decimals when one is not exact (1.17 m), and as before otherwise (the island's 20.0 m).
+
+- **The Shelf's pictures on the real character**: `createLookPreview` (in `@nano133/nanoterra/character`) draws a look on a character (the game's own
+  `body`, else the package's character with its shirt in the look's colour) with one shared offscreen WebGL renderer, one picture at a time, kept by the
+  look's text; with no WebGL it answers null. `previewPicture(load)` (in `@nano133/nanoterra/admin/panel`, which still loads no Three.js) is a Shelf
+  `lookPicture` that shows the flat picture first and the drawn one when it is ready; `load` is called once, so a game imports its preview file only when
+  the Shelf opens. New CSS: `.shelf-preview`.
+
 ## 0.2.0 (2026-10-27)
 
 - **Slots** on a look (`@nano133/nanoterra/looks`, and the Shelf of `/admin/panel`): `slots?: Record<string, string>`, what a game defines for itself (a pair of wings, a trail colour). Names are 1 to 24

package/README.md

@@ -60,10 +60,11 @@ Each path loads only what it needs. A page that reads a ticket loads no Three.js
 | `@nano133/nanoterra/character/record` | the character's **record**: pack, unpack, check, `fromLegacy`, `toLegacy`, `diceRecord`, the lists | no | 4.4 kB (all), 1.9 kB (pack, unpack and the two legacy calls) |
 | `@nano133/nanoterra/ticket` | read and check a sign-in ticket | no | 4.7 kB (all), 3.1 kB (`readTicket` alone) |
 | `@nano133/nanoterra/looks` | the looks ladder | no | 1.9 kB (all), 0.9 kB (`checkLooks` alone) |
-| `@nano133/nanoterra/character` | the builder and `createCharacter` (it includes the record) | yes | 20.4 kB (all), 17.8 kB (`createCharacter` alone) |
+| `@nano133/nanoterra/character` | the builder and `createCharacter` (it includes the record), with the three sockets | yes | 21.8 kB (all, with the sockets and `createLookPreview` of 0.3.0; 20.4 kB on 0.2.0), 17.8 kB (`createCharacter` alone, measured on 0.2.0) |
+| `@nano133/nanoterra/model` | the 3D model check: a `.glb` against the island's limits or a cosmetic's (since 0.3.0) | no | 8.8 kB |
 | `@nano133/nanoterra/admin` | the admin of a game: the guard, the handler, the store type (server code; since 0.2.0) | no | 3.7 kB |
 | `@nano133/nanoterra/admin/d1`, `/admin/firestore` | the admin store for D1 (the starter's tables) or Firestore (a small interface, no Firebase dependency): `createD1Store`, `createFirestoreStore` (since 0.2.0) | no | 1.5 kB each |
-| `@nano133/nanoterra/admin/panel` | the admin page, drawn in the browser into one element, and its stylesheet `@nano133/nanoterra/admin/style.css` (since 0.2.0) | no | 8.5 kB + 2.4 kB of CSS |
+| `@nano133/nanoterra/admin/panel` | the admin page, drawn in the browser into one element, and its stylesheet `@nano133/nanoterra/admin/style.css` (since 0.2.0) | no | 10.6 kB on 0.3.0 (8.5 kB measured on 0.2.0) + 2.4 kB of CSS |
 | `@nano133/nanoterra/admin/conformance` | test cases that a game runs against its own admin (a dev dependency in practice; since 0.2.0) | no | n/a |
 
 Measured 2026-10-26: `esbuild --bundle --minify --format=esm --external:three`, then `gzip -9`, without Three.js.
@@ -85,7 +86,7 @@ c.dispose();
 
 | Call | What it does |
 |---|---|
-| `createCharacter({ record?, look?, colors?, quality?, reducedMotion? })` | Builds a character. `record` is the player's whole character (see "The record"). `look` is the five colours `{ skin, hair, shirt, pants, shoes }` of a player whose ticket has no record: the Classic body in those colours (read only when `record` is left out). Neither: the island's first look. `colors` paints colours over the record's (any `"#rrggbb"`: a shop dye is not on the island's lists). `quality` is `"high"` (default) or `"low"`. Something that is not good throws a `TypeError` that names the part and the value. |
+| `createCharacter({ record?, look?, colors?, quality?, reducedMotion?, worn? })` | Builds a character. `record` is the player's whole character (see "The record"). `look` is the five colours `{ skin, hair, shirt, pants, shoes }` of a player whose ticket has no record: the Classic body in those colours (read only when `record` is left out). Neither: the island's first look. `colors` paints colours over the record's (any `"#rrggbb"`: a shop dye is not on the island's lists). `quality` is `"high"` (default) or `"low"`. Something that is not good throws a `TypeError` that names the part and the value. |
 | `c.object` | A `THREE.Group`: feet at y = 0, facing +Z. Add it to your scene; move it with `position`, turn it with `rotation.y`. It holds the skinned meshes **and the blob shadow** (a disc in the body). |
 | `c.update(dt, { speed, airborne, verticalSpeed })` | One frame. `dt` is in **seconds** (a frame longer than 0.05 s counts as 0.05 s). Idle, walk, run and jump come from your numbers. Every field is optional. See "Motion". |
 | `c.wave()` | Waves the left arm for 1.8 s (`WAVE_SECONDS`), as the island does. |
@@ -93,7 +94,9 @@ c.dispose();
 | `c.setColors(colors \| null)` | Paints these colours over the record's; `null` gives the record's own back. No new geometry. |
 | `c.record`, `c.look` | The record now (a frozen copy), and its five colours (the older view). |
 | `c.reducedMotion` | A boolean you may change: true turns off the swing of the arms and legs and the bob, and makes the wave still. Set it from `prefers-reduced-motion`. |
-| `c.dispose()` | Frees the geometries, materials and textures that the character made. The other calls do nothing after it. |
+| `c.socket(name)` | An attach point, a `THREE.Object3D` on a bone: `"head"`, `"hand"` or `"back"`. Add your own object to it and it follows the bone. It is the same object for the character's whole life: a rebuild moves it, with what hangs on it, to the new bones (since 0.3.0; see "Worn things and sockets"). |
+| `c.setWorn(worn)` | The worn things (`WornAdapter`): shapes merged into the body, or a model on a socket. A model on a socket builds no geometry; the objects of things no longer worn come off their socket (since 0.3.0). |
+| `c.dispose()` | Frees the geometries, materials and textures that the character made. The other calls do nothing after it. It never frees an object that you hung on a socket: that is yours. |
 
 Also exported from `/character`: `HEIGHT`, `RADIUS`, `WAVE_SECONDS`, `buildCharacter` and `assemble` (the pieces `createCharacter` uses: the geometry, the skinned meshes on the island's 28-bone skeleton), `BASE_IDS`, the lists, and everything of `/character/record`.
 
@@ -171,15 +174,62 @@ a player's choice of body never changes a rule. nano133.com's island and room do
 - The ink line is a second draw of the same skinned mesh, with its back faces, pushed out along its normal in screen space, so it keeps one width in pixels (2.6). Use `WebGLRenderer`: the ink is a GLSL `ShaderMaterial`.
 - Frame rate has not been measured on a real phone by this package. nano133.com's island draws a room of twelve of these characters at 60 frames a second on a throttled phone profile.
 
-## Worn items (the next version)
+## Worn things and sockets
 
-**Versions 0.1.0 and 0.2.0 draw the body only**, as `@nano133/character` 0.1.0 did. The island's 14 shop items (hats, scarves, packs, tops, a buddy, a blade) are
-fitted to every base by nano133.com's own code, and are not in this package yet. The builder takes them through **one small interface**,
-`WornAdapter` (what it needs of a worn thing: its shapes and bones through `add(ctx)`, what it does to the hair, `hidesBadge`, `hideTail`), so a game
-may bring its own, and the island brings its adapter the same way.
+A worn thing reaches the builder through **one small interface**, `WornAdapter`. It has two ways, and a thing may use both:
 
-A player's item ids come in the sign-in answer (`ticket.items` here, `character.items` in the code exchange). A later version (0.2.0) adds the item art so
-that a game can draw them with one call. Until then a game may ignore the ids or draw its own things.
+- **Merged shapes** (`add(ctx)`, and what it does to the hair `fit`, `hidesBadge`, `hideTail`, `hideWings`): the thing's shapes go into the body's own buffers, so it
+  **adds no draw**. nano133.com fits the island's 14 shop items (hats, scarves, packs, tops, a buddy, a blade) to every base this way, with its own code.
+- **A model on a socket** (`socket` and `object`, since 0.3.0): your own `THREE.Object3D` (a `.glb` you loaded, say) hangs on one of the character's three
+  attach points and follows its bone. It costs **its own draws** (1 or 2 for each thing). The character never frees it: you load it and you free it.
+
+```ts
+const c = createCharacter({ record });
+const shovel = (await new GLTFLoader().loadAsync("/looks/shovel.glb")).scene;
+c.setWorn([{ socket: "hand", object: shovel }]); // or: c.socket("hand").add(shovel)
+c.setLook(otherRecord); // another base: the shovel moves to the new hand
+c.setWorn([]); // the shovel comes off; free its geometry and materials yourself
+```
+
+| Socket | Bone | Where | Its axes |
+|---|---|---|---|
+| `"head"` | `head` | the base's hat frame (`BASE_SPECS[base].hat`: about the middle of the head), scaled by the hat frame and the head's size | the character's: +Y up, +Z forward. A thing made round the middle of the Classic's head (radius 0.42 m) fits every head |
+| `"hand"` | `grip_R` | the middle of the drawn right hand (a wide build or base draws its hands further out than the bone) | `HAND_HOLD`: a thing modelled standing up (+Y) with its grip at the origin is held pointing forward, its front (+Z) up |
+| `"back"` | `chest` | on the back of the torso at the chest's height (`BASE_SPECS[base].back`, else the torso's radius at 1.12) | the character's: the side that touches the body at the origin, the bulk towards -Z. Give the thing `hideTail: true` and `hideWings: true` to take a Critter's tail and a Bee's wings off under it |
+
+`socketFrame(spec, look, name)` gives a socket's bone, place, turn and scale for a base and a look, and `placeSocket(object, bones, spec, look, name)`
+puts an object there: a host that uses `buildCharacter` and `assemble` (not `createCharacter`) makes its own sockets with them. Check a socket model
+with the presets of `@nano133/nanoterra/model` (`HEAD_ITEM`, `HAND_ITEM`, `BACK_ITEM`) before you ship it.
+
+A player's item ids come in the sign-in answer (`ticket.items` here, `character.items` in the code exchange). The island's item art is not in this package;
+a game may ignore the ids or draw its own things.
+
+## Model check (`@nano133/nanoterra/model`; since 0.3.0)
+
+`checkModel(bytes, limits)` reads a `.glb` (binary glTF 2.0) from its bytes and answers `{ ok, problems, facts, advice }`. It is pure (no Three.js, no
+network, no DOM) and it never throws: a file that cannot be read answers a problem. The file comes from a stranger, so every read is bounded (no size in the
+file is trusted, the work has a cap and a time limit).
+
+- `problems`: each `{ rule, fix }`, the fix in one or two plain sentences for the creator. Rules: `file`, `size`, `embedded`, `extensions`, `lights`,
+  `motion`, `triangles`, `textures`, `draws`, `zone`, `markers`, `time`.
+- `facts`: the bytes, the triangles, the **draws** (each part of each drawn mesh instance), the **materials** the parts use, the textures (their type and size,
+  read from the picture itself), the box and the reach, the markers, the anchor.
+- `advice`: lines that are never a failure: a large PNG or JPEG (KTX2 makes it smaller), 32-bit positions (`KHR_mesh_quantization` halves them),
+  parts that share a material (joining them saves draws).
+- `modelSummary(facts)`: one short line ("646 triangles, 0 textures, 49 KB, 0.5 x 0.4 x 1.0 m").
+
+The presets (`limits.ts`; a game may make its own `ModelLimits`). The cosmetic numbers are Wes's of 2026-10-28 (the hand zone his second choice that day, so that a shovel held by its T-handle fits); the zone is in metres for a character 2.29 m
+tall, its origin the socket's point (a hand item's `grip_R` marker when it has one):
+
+| Preset | Zone (w x d x h) | Triangles | Textures | Draws | File |
+|---|---|---|---|---|---|
+| `HEAD_ITEM` | 0.9 x 0.9 x 0.8, from 0.1 below the socket | 3,000 | 1 of 512 px | 2 | 300 KB |
+| `HAND_ITEM` | 0.96 x 0.68 x 1.6, from 1.17 below the grip to 0.43 above (a tool held near its top) | 3,000 | 1 of 512 px | 2 | 300 KB |
+| `BACK_ITEM` | 1.0 x 0.6 x 1.2, from 0.6 below the socket | 4,000 | 1 of 512 px | 2 | 400 KB |
+| `ISLAND_MODEL` | a disc of 10 m radius, 18 m high, from the ground | 50,000 | 8 of 1,024 px | no limit | 5 MB |
+
+Every preset refuses skins, animations, morph targets, lights, external files and compressed meshes (Draco, meshopt): a worn thing is rigid on its socket.
+`COSMETIC_LIMITS` gives the preset of each socket by its name. The island preset is nano133.com's (its "Launch my game" check uses this same code).
 
 ## The sign-in ticket
 
@@ -509,6 +559,25 @@ The panel draws: the **Game** card (the two switches), what is still off (the st
 sign-in; a wrong wallet, a Nanoterra sign-in and a missing owner address each get their own screen and see no data. Options: `api` (the handler's base path), `noAddressHelp`,
 `lookPicture(look)` (your own picture of a look for the Shelf), `repoHelp`, and `fetch`.
 
+**The Shelf's pictures on the real character** (since 0.3.0). The panel has no Three.js, so it takes the pictures from you, lazily:
+
+```ts
+// admin.ts
+import { mountAdmin, previewPicture } from "@nano133/nanoterra/admin/panel";
+mountAdmin(el, { looks, signIn, signOut, lookPicture: previewPicture(() => import("./lookPreview").then((m) => m.render)) });
+
+// lookPreview.ts (loaded only when the Shelf shows a look)
+import { createLookPreview } from "@nano133/nanoterra/character";
+const preview = createLookPreview({ body: () => yourDressedCharacter() }); // left out: the package's character, its shirt in the look's colour
+export const render = (look) => preview.render(look);
+```
+
+`previewPicture(load)` shows the flat picture at once and puts the drawn one in its place when it is ready; with no WebGL, or when `load` fails, the
+flat picture stays. `createLookPreview({ size?, body?, record?, background?, key? })` draws each look once with ONE shared offscreen WebGL renderer
+(one context for the whole Shelf; a page may have about 16), one picture at a time, and keeps each picture (a PNG data URL) by the look's text.
+`body()` gives `{ object, dress(look), dispose() }`: your own character dressed in the look (a hat, a model that loads: `dress` may return a promise).
+`dispose()` frees the renderer and its context. The page's Content-Security-Policy must allow `img-src data:`.
+
 **The Shelf never writes.** It edits a draft in the owner's browser and gives text to copy (`looks.json`, or a message for an AI assistant): there is no call in the panel that
 changes a look, a price or an order, and a test proves that editing the Shelf sends no request. A change of looks is a change of your repository. The **Game** card writes only the
 two settings. The stylesheet is scoped under `.n133-admin`, so it cannot leak into your page; to theme it set `--n133-ink`, `--n133-ink-soft`, `--n133-paper`, `--n133-line`,
@@ -531,7 +600,8 @@ The wallet sign-in stays yours (`signIn`), because only your game can start a re
 
 ## What it does NOT do yet
 
-- Worn items (see above): 0.2.0.
+- The island's item art (see "Worn things and sockets"): a game brings its own things.
+- A pose for a held thing: the arms swing free, so a two-handed thing (a `grip_L` as well as a `grip_R`) is held in the right hand only.
 - The katana, the saya, the headband and the dojo look of the island's Ananos game. (The skeleton keeps their bones, with no vertices.)
 - First-person arms, swimming, climbing, sitting and the room's other moves: only idle, walk, run, jump and wave.
 - Shared geometry for many characters at once, and a react-three-fiber wrapper.

package/ai/SPEC.md

@@ -107,5 +107,9 @@ export const LOOKS = checkLooks(rawLooksJson); // throws with the first mistake
 ## 8. Do not
 
 - Do not edit the geometry, the skeleton or the toon and ink materials.
-- Do not add worn items, the katana, the headband or other brands' art: 0.1.0 has none of them (a later version adds the item art).
+- Do not add the katana, the headband or other brands' art. A game's own worn model goes on a socket (`c.socket("head" | "hand" | "back")` or
+  `c.setWorn([{ socket, object }])`), and is checked first with `checkModel(bytes, HAND_ITEM)` (or `HEAD_ITEM`, `BACK_ITEM`) from `@nano133/nanoterra/model`.
+  A hand thing has an empty `grip_R` node where the hand holds it and stays inside 0.96 x 0.68 m, from 1.17 m below that grip to 0.43 m above. A back
+  thing gives `hideTail: true` and `hideWings: true`, so a tail or wings do not poke through it.
+  The game loads the model and frees it; the character never does.
 - Do not use a look or a record for a game's rules, a score or a payment: it is display only.

package/dist/admin/panel/index.d.ts

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

@@ -8,6 +8,6 @@
 export { mountAdmin } from "./mount.js";
 export { ApiError, createApi } 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 { aiPrompt, centsOf, changeText, ownedIds, shelfStats, soldText } from "./shelfData.js";

package/dist/admin/panel/shelf.d.ts

@@ -7,6 +7,13 @@ export type ShelfData = {
 };
 /** A small flat picture of a look: the body in its colour and the hat in its colour. (The game draws the real character; a game can give its own picture.) */
 export declare 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 declare function previewPicture(load: () => Promise<(l: Look) => Promise<string | null>>, fallback?: (l: Look) => Element, size?: number): (l: Look) => Element;
 /**
  * The screen. `looks` is the game's looks now (its looks.json): the draft starts from them. `update` hands the screen fresh numbers (after the page reloads
  * the summary) and keeps the draft. `picture` draws a look (default: the flat picture above). `repoHelp` is what to tell a game that has no repository set.

package/dist/admin/panel/shelf.js

@@ -30,6 +30,30 @@ export function lookPicture(l) {
     };
     return svg("svg", { viewBox: "0 0 64 72", width: 56, height: 63, role: "img", "aria-label": `${l.name}: ${l.change.hat ?? "no hat"}` }, shape("rect", { x: 23, y: 61, width: 7, height: 9, rx: 2, fill: "#3a3f5c" }), shape("rect", { x: 34, y: 61, width: 7, height: 9, rx: 2, fill: "#3a3f5c" }), shape("rect", { x: 16, y: 37, width: 32, height: 28, rx: 12, fill: l.change.body }), shape("circle", { cx: 32, cy: 26, r: 13, fill: "#f2c9a0" }), svg("circle", { cx: 27, cy: 27, r: 1.7, fill: INK }), svg("circle", { cx: 37, cy: 27, r: 1.7, fill: INK }), ...(hat ? hats[hat] : []));
 }
+/**
+ * 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, fallback = lookPicture, size = 64) {
+    let ready = null;
+    return (l) => {
+        const box = h("span", { class: "shelf-preview" }, fallback(l));
+        ready ??= load().catch(() => null);
+        const 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` });
+            box.replaceChildren(img);
+        })
+            .catch(() => undefined);
+        return box;
+    };
+}
 const clone = (ls) => ls.map((l) => ({ id: l.id, name: l.name, priceUsd: l.priceUsd, change: { ...l.change }, ...(l.slots ? { slots: { ...l.slots } } : {}) }));
 /** "wings ember, trail #ffcf5a" */
 const slotsText = (l) => Object.entries(l.slots ?? {}).map(([k, v]) => `${k} ${v}`).join(", ");

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. */

package/dist/character/preview.d.ts

@@ -0,0 +1,32 @@
+import * as THREE from "three";
+import type { LookRecord } from "./record.js";
+/** What draws one look: the game's own character dressed in it (its hat, its models), or by default the package's character. */
+export type PreviewBody<L> = {
+    object: THREE.Object3D;
+    /** Puts the look on. A promise waits (a model that loads). */
+    dress(look: L): void | Promise<void>;
+    /** Frees what the body made. */
+    dispose(): void;
+};
+export type LookPreviewOptions<L> = {
+    /** The picture's side in CSS pixels (default 112); it is drawn at twice that for a sharp screen. */
+    size?: number;
+    /** A body for the next picture. Left out: the package's character in `record` (else the island's first look), its shirt in the look's body colour. */
+    body?: () => PreviewBody<L>;
+    /** The record of the default body. */
+    record?: LookRecord;
+    /** The background (default: none, a clear picture). */
+    background?: THREE.ColorRepresentation | null;
+    /** The key of a look in the cache (default: its JSON text). */
+    key?: (look: L) => string;
+};
+export type LookPreview<L> = {
+    /** A PNG data URL of the look on the character, or null when the page has no WebGL or the drawing failed. */
+    render(look: L): Promise<string | null>;
+    /** How many pictures are kept. */
+    readonly cached: number;
+    /** Frees the renderer (and its WebGL context) and the cache. `render` answers null after it. */
+    dispose(): void;
+};
+/** A picture maker. Make one for a page and keep it: it holds one WebGL context while it lives. */
+export declare function createLookPreview<L>(options?: LookPreviewOptions<L>): LookPreview<L>;