@nano133/nanoterra 0.2.0 → 0.3.0

package/src/character/preview.ts

@@ -0,0 +1,148 @@
+import * as THREE from "three";
+import { createCharacter, type Character } from "./create.js";
+import type { LookRecord } from "./record.js";
+
+// A picture of a look on the real character, for the Shelf of /admin (or any page): the character is built and dressed once, one frame is
+// drawn with ONE shared offscreen WebGL renderer, and the picture (a PNG data URL) is kept by the look's text, so the same look is drawn
+// once. Pictures are drawn one at a time. With no WebGL, `render` answers null and the page keeps its flat picture.
+//
+// The Shelf (`@nano133/nanoterra/admin/panel`) has no Three.js: give it `previewPicture(load)`, where `load` imports your preview file
+// dynamically, so this file loads only when the Shelf opens (the game starter's src/client/admin.ts does it).
+
+/** 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;
+};
+
+/** The look as the starter's looks.json has it: a body colour that paints the shirt (the body when there is no top). */
+type ColourLook = { priceUsd?: number; change?: { body?: string } };
+
+function defaultBody<L>(record: LookRecord | undefined): () => PreviewBody<L> {
+  return () => {
+    const c: Character = createCharacter({ record, reducedMotion: true });
+    return {
+      object: c.object,
+      dress(look) {
+        const body = (look as ColourLook).change?.body;
+        if (body && ((look as ColourLook).priceUsd ?? 1) > 0) c.setColors({ shirt: body });
+      },
+      dispose: () => c.dispose(),
+    };
+  };
+}
+
+/** A picture maker. Make one for a page and keep it: it holds one WebGL context while it lives. */
+export function createLookPreview<L>(options: LookPreviewOptions<L> = {}): LookPreview<L> {
+  const size = options.size ?? 112;
+  const makeBody = options.body ?? defaultBody<L>(options.record);
+  const keyOf = options.key ?? ((l: L) => JSON.stringify(l));
+  const cache = new Map<string, Promise<string | null>>();
+  let renderer: THREE.WebGLRenderer | null = null;
+  let failed = false;
+  let disposed = false;
+  let queue: Promise<unknown> = Promise.resolve();
+
+  const scene = new THREE.Scene();
+  if (options.background != null) scene.background = new THREE.Color(options.background);
+  scene.add(new THREE.HemisphereLight("#ffffff", "#8a8f9e", 1.6));
+  const sun = new THREE.DirectionalLight("#ffffff", 1.6);
+  sun.position.set(2, 4, 5);
+  scene.add(sun);
+  const camera = new THREE.PerspectiveCamera(30, 1, 0.05, 50);
+
+  function getRenderer(): THREE.WebGLRenderer | null {
+    if (renderer || failed) return renderer;
+    try {
+      // three makes its own canvas (in a page); with no page or no WebGL this throws, and the answer is null.
+      renderer = new THREE.WebGLRenderer({ antialias: true, alpha: true, preserveDrawingBuffer: true });
+      renderer.setPixelRatio(1);
+      renderer.setSize(size * 2, size * 2, false);
+      renderer.setClearColor(0x000000, 0);
+    } catch {
+      failed = true;
+      renderer = null;
+    }
+    return renderer;
+  }
+
+  async function draw(look: L): Promise<string | null> {
+    if (disposed) return null;
+    const r = getRenderer();
+    if (!r) return null;
+    const body = makeBody();
+    try {
+      await body.dress(look);
+      if (disposed) return null;
+      scene.add(body.object);
+      // Frame the whole character (with what it holds) from the front, a little from its right and above.
+      body.object.updateMatrixWorld(true);
+      const box = new THREE.Box3().setFromObject(body.object);
+      const sphere = box.getBoundingSphere(new THREE.Sphere());
+      const dir = new THREE.Vector3(-0.6, 0.15, 1).normalize();
+      const dist = sphere.radius / Math.sin(THREE.MathUtils.degToRad(camera.fov / 2)) * 1.02;
+      camera.position.copy(sphere.center).addScaledVector(dir, dist);
+      camera.lookAt(sphere.center);
+      camera.near = Math.max(0.01, dist - sphere.radius * 2);
+      camera.far = dist + sphere.radius * 2;
+      camera.updateProjectionMatrix();
+      r.render(scene, camera);
+      return r.domElement.toDataURL("image/png");
+    } catch {
+      return null;
+    } finally {
+      scene.remove(body.object);
+      body.dispose();
+    }
+  }
+
+  return {
+    render(look) {
+      if (disposed) return Promise.resolve(null);
+      const key = keyOf(look);
+      const hit = cache.get(key);
+      if (hit) return hit;
+      // One at a time: the renderer and the scene are shared.
+      const p = queue.then(() => draw(look));
+      queue = p.catch(() => null);
+      cache.set(key, p);
+      return p;
+    },
+    get cached() {
+      return cache.size;
+    },
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      cache.clear();
+      renderer?.dispose();
+      renderer?.forceContextLoss();
+      renderer = null;
+    },
+  };
+}

package/src/character/sockets.ts

@@ -0,0 +1,81 @@
+import * as THREE from "three";
+import type { BaseSpec } from "./bases/spec.js";
+import { BUILD_FACTORS } from "./make.js";
+import type { BoneName } from "./skeleton.js";
+
+// The character's three attach points (sockets): the head, the right hand and the back. A socket is a THREE.Object3D on one bone of the
+// island's skeleton, so a thing hung on it follows the walk, the run, the jump and the wave, and costs its own draws (a model of the game's,
+// a .glb say). A worn thing that is merged into the body's geometry (ctx.ts `WornAdapter.add`) adds no draw and needs no socket.
+//
+// Each socket's place depends on the base and on the look (the build widens the body and moves the hands out; the head's size scales the
+// head). `socketFrame` works it out; `createCharacter` keeps its sockets on the new bones after a rebuild (a new base, hair or clothes).
+
+/** The names of the sockets. */
+export const SOCKETS = ["head", "hand", "back"] as const;
+export type SocketName = (typeof SOCKETS)[number];
+
+/** Where a socket sits: its bone, and its place, turn and scale in that bone's space (the units of the character's own space). */
+export type SocketFrame = { bone: BoneName; position: THREE.Vector3; quaternion: THREE.Quaternion; scale: THREE.Vector3 };
+
+/** The head bone's rest height. */
+const HEAD_BONE_Y = 1.5;
+/** The chest bone's rest height. */
+const CHEST_BONE_Y = 1.12;
+
+/**
+ * The hand's hold: a hand item is modelled standing up (+Y), its grip at the origin, its front at +Z. The hand holds it pointing forward,
+ * as a torch is held out: the item's +Y along the character's forward (+Z), its front (+Z) up, its +X to the character's right (-X).
+ */
+export const HAND_HOLD = Object.freeze(new THREE.Quaternion().setFromAxisAngle(new THREE.Vector3(0, 1, 1).normalize(), Math.PI));
+
+/** What `socketFrame` reads of a look: its build and its head's size. */
+export type SocketLook = { build: keyof typeof BUILD_FACTORS; head: number };
+
+/**
+ * A socket's frame on a base for a look.
+ *  - "head": on the head bone, at the base's hat frame (`spec.hat`), scaled by the hat frame and the head's size: a thing made for the
+ *    Classic's head, round the middle of the head (the game starter's hats are made so), fits every head.
+ *  - "hand": on grip_R, in the middle of the right hand (the hands of a wide body are drawn further out than their bone), turned by
+ *    `HAND_HOLD`.
+ *  - "back": on the chest bone, on the back of the torso (`spec.back`, else the chest's height and the torso's radius there); its axes are the
+ *    character's, so a back item is modelled with the side that touches the body at the origin and its bulk towards -Z.
+ */
+export function socketFrame(spec: BaseSpec, look: SocketLook, name: SocketName): SocketFrame {
+  const t = BUILD_FACTORS[look.build] ?? BUILD_FACTORS.regular;
+  const hs = look.head;
+  if (name === "head") {
+    const h = spec.hat;
+    return {
+      bone: "head",
+      position: new THREE.Vector3(0, (h.y - HEAD_BONE_Y) * hs, (h.z ?? 0) * hs),
+      quaternion: new THREE.Quaternion(),
+      scale: new THREE.Vector3(h.s[0] * hs, h.s[1] * hs, h.s[2] * hs),
+    };
+  }
+  if (name === "hand") {
+    // limbs.ts draws the hand at 0.47 + 0.45 (torso - 1) + armOut from the middle; the bone stays at 0.47.
+    const out = 0.45 * (t.torso - 1) + (spec.limbs.armOut ?? 0);
+    const at = spec.handAt ?? [0, 0, 0];
+    return { bone: "grip_R", position: new THREE.Vector3(-out + at[0], at[1], at[2]), quaternion: HAND_HOLD.clone(), scale: new THREE.Vector3(1, 1, 1) };
+  }
+  if (name === "back") {
+    const y = spec.back?.y ?? CHEST_BONE_Y;
+    const z = spec.back?.z ?? -spec.torsoR(y) * t.torso;
+    return { bone: "chest", position: new THREE.Vector3(0, y - CHEST_BONE_Y, z), quaternion: new THREE.Quaternion(), scale: new THREE.Vector3(1, 1, 1) };
+  }
+  throw new TypeError(`@nano133/nanoterra: there is no socket ${JSON.stringify(name)} (the sockets are ${SOCKETS.join(", ")})`);
+}
+
+/** Puts a socket object on its bone (from `bones`) at its frame. The object keeps its children: a hung item moves with it. */
+export function placeSocket(socket: THREE.Object3D, bones: Partial<Record<BoneName, THREE.Object3D>>, spec: BaseSpec, look: SocketLook, name: SocketName) {
+  const f = socketFrame(spec, look, name);
+  const bone = bones[f.bone];
+  if (!bone) throw new TypeError(`@nano133/nanoterra: the skeleton has no bone ${f.bone} for the socket ${name}`);
+  socket.position.copy(f.position);
+  socket.quaternion.copy(f.quaternion);
+  socket.scale.copy(f.scale);
+  bone.add(socket);
+  return socket;
+}
+
+export const isSocketName = (v: unknown): v is SocketName => typeof v === "string" && (SOCKETS as readonly string[]).includes(v);