@nano133/nanoterra 0.2.0 → 0.3.0

package/dist/character/preview.js

@@ -0,0 +1,112 @@
+import * as THREE from "three";
+import { createCharacter } from "./create.js";
+function defaultBody(record) {
+    return () => {
+        const c = createCharacter({ record, reducedMotion: true });
+        return {
+            object: c.object,
+            dress(look) {
+                const body = look.change?.body;
+                if (body && (look.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(options = {}) {
+    const size = options.size ?? 112;
+    const makeBody = options.body ?? defaultBody(options.record);
+    const keyOf = options.key ?? ((l) => JSON.stringify(l));
+    const cache = new Map();
+    let renderer = null;
+    let failed = false;
+    let disposed = false;
+    let queue = 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() {
+        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) {
+        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/dist/character/sockets.d.ts

@@ -0,0 +1,37 @@
+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 names of the sockets. */
+export declare const SOCKETS: readonly ["head", "hand", "back"];
+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 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 declare const HAND_HOLD: Readonly<THREE.Quaternion>;
+/** 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 declare function socketFrame(spec: BaseSpec, look: SocketLook, name: SocketName): SocketFrame;
+/** Puts a socket object on its bone (from `bones`) at its frame. The object keeps its children: a hung item moves with it. */
+export declare function placeSocket(socket: THREE.Object3D, bones: Partial<Record<BoneName, THREE.Object3D>>, spec: BaseSpec, look: SocketLook, name: SocketName): THREE.Object3D<THREE.Object3DEventMap>;
+export declare const isSocketName: (v: unknown) => v is SocketName;

package/dist/character/sockets.js

@@ -0,0 +1,66 @@
+import * as THREE from "three";
+import { BUILD_FACTORS } from "./make.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"];
+/** 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));
+/**
+ * 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, look, name) {
+    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, bones, spec, look, name) {
+    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) => typeof v === "string" && SOCKETS.includes(v);

package/dist/model/check.d.ts

@@ -0,0 +1,59 @@
+import type { ModelLimits } from "./limits.js";
+export type ModelRule = "file" | "size" | "embedded" | "extensions" | "lights" | "motion" | "triangles" | "textures" | "draws" | "zone" | "markers" | "time";
+/** One thing wrong with the model: `fix` is one plain sentence or two, for the creator. */
+export type ModelProblem = {
+    rule: ModelRule;
+    fix: string;
+};
+export type Vec3 = [number, number, number];
+export type TextureFact = {
+    type: "image/png" | "image/jpeg" | "image/webp" | "image/ktx2";
+    width: number;
+    height: number;
+    bytes: number;
+};
+export type ModelFacts = {
+    bytes: number;
+    /** Triangles drawn (every instance counted; the `mesh` markers, as `nano_collide`, left out). Null when not counted. */
+    triangles: number | null;
+    textures: TextureFact[];
+    /**
+     * Draws: each part (glTF primitive) of each drawn mesh instance is one draw call, the `mesh` markers left out. Null when not counted.
+     * (A game may join parts or draw an ink outline; this counts the file as it is.)
+     */
+    draws: number | null;
+    /** The materials that the drawn parts use (a part with no material uses the default one, which counts once). */
+    materials: number;
+    /**
+     * The model's box in its own axes (metres), every drawn mesh and every `mesh` marker in it. Null when not measured. When the limits name an
+     * `anchor` and the file has it, the box, the reach and the zone are measured from the anchor's point (`anchor`), not the file's origin.
+     */
+    bounds: {
+        min: Vec3;
+        max: Vec3;
+    } | null;
+    /** The farthest drawn point from the y axis (x and z together, metres), the `mesh` markers in it. Null when not measured. */
+    reach: number | null;
+    /** True: the box and the reach come from every vertex. False: past the work cap, from each instance's box (larger, never smaller). */
+    exactBounds: boolean;
+    /** Where each marker that the file has stands (its node's origin, in the model's axes). */
+    markers: Record<string, Vec3>;
+    /** The anchor's point in the file's axes (the limits' `anchor` marker), or null: the file's origin is the attach point. */
+    anchor: Vec3 | null;
+    nodes: number;
+    meshes: number;
+    extensions: string[];
+};
+/** `advice`: plain lines that would make the model lighter (never a failure: `ok` does not read them). */
+export type ModelCheck = {
+    ok: boolean;
+    problems: ModelProblem[];
+    facts: ModelFacts;
+    advice: string[];
+};
+/** The picture's type and size from its bytes (never from the file's word for it), or null. */
+export declare function sniffTexture(b: Uint8Array): Omit<TextureFact, "bytes"> | null;
+/** Checks a .glb against `limits`. Never throws: a file that cannot be read answers a problem. */
+export declare function checkModel(input: Uint8Array, limits: ModelLimits): ModelCheck;
+/** One short line of what was measured: "12,000 triangles, 3 textures, 1.2 MB, 20.0 x 15.0 x 10.0 m". */
+export declare function modelSummary(f: ModelFacts): string;