@nano133/nanoterra 0.2.0 → 0.3.1

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

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/input/index.d.ts

@@ -0,0 +1,32 @@
+type Listens = Pick<EventTarget, "addEventListener" | "removeEventListener">;
+/**
+ * Calls `release` each time what is held may be wrong. In it, clear every held key, thumb stick and drag, and any jump or tool that a key press queued.
+ * `keysOnly`, when given, is called when a menu opens (a right click): a menu takes a keyup, but on a touch screen a long press also asks for a menu,
+ * and a thumb that rests on a stick must not lose its walk for that. A menu that your page stopped (`preventDefault`) did not open: nothing is let go.
+ *
+ * After a leave (blur, focus, page hide, the tab hidden or shown), a key REPEAT does not reach your key handlers until a key goes down for the first
+ * time (`repeat` false). The player presses the key again to walk on. A menu is no leave: the held key that a menu took comes back by its repeat.
+ * The repeat is stopped in the capture phase (`stopImmediatePropagation`), so register your own key handlers as usual: they never see it.
+ *
+ * Returns the function that takes the listeners away. `win` and `doc` are given in a test.
+ */
+export declare function releaseWhenLost(release: () => void, keysOnly?: () => void, win?: Listens, doc?: Listens & {
+    hidden?: boolean;
+}): () => void;
+/** A keydown whose keyup may never come (Cmd is down, or it is the Cmd key): it must not go into your held set. */
+export declare const swallowsKeyup: (e: {
+    metaKey?: boolean;
+    key?: string;
+}) => boolean;
+/**
+ * Calls `pause` when the player leaves: the tab or the window is hidden (`visibilitychange`: another tab, a minimized window, a locked phone,
+ * another app on a phone), or the window loses the focus to another window (a real `blur`: not a script's, and not a focus that moves inside
+ * your page into a dialog or a field). It may call `pause` twice for one leave (a blur, then the tab hiding): make `pause` safe to call twice.
+ * Show a Resume key and stop your clock in it; start nothing again until the player taps Resume. Returns the function that takes the listeners away.
+ * `win` and `doc` are given in a test.
+ */
+export declare function pauseWhenLeft(pause: () => void, win?: Listens, doc?: Listens & {
+    hidden?: boolean;
+    hasFocus?: () => boolean;
+}): () => void;
+export {};

package/dist/input/index.js

@@ -0,0 +1,102 @@
+// Held input that a page can no longer trust, and a pause for when the player leaves. For a game that a player walks in with keys, a thumb stick
+// or a drag, in the browser.
+//
+// THE FAULT: the browser sends a key's "up" only to the window that has the focus. A key that is down when the player leaves the page (another
+// tab, another window, a pop-up, Cmd+Tab, another app on a phone) never sends its "up" here. A game that keeps a "held keys" set keeps the key,
+// and the character walks on by itself when the player comes back (nano133.com's own island and rooms had it: "my character is now moving by
+// himself"). The ways that were found:
+//   - the tab or the window changes while a key is down (Cmd+Tab, Ctrl+Tab, Cmd+a number, a click elsewhere)
+//   - on a Mac, a key that is released while Cmd is down sends NO keyup (Cmd+Shift+4 for a picture, Cmd+C, ...)
+//   - a menu of the browser or the system opens (a right click, a long press) and takes the keyup
+//   - a pointer of a thumb stick ends where the page does not get it (the edge of the screen, a system gesture)
+//   - ONE MORE REPEAT of the held key arrives after the page was let go, or the repeats go on when the player comes back: it puts the key back
+//     into the held set, and its keyup went to the other window. A repeat only says that a key was down at some time.
+//
+// `releaseWhenLost(release)` calls your `release` at each of them, and drops key repeats after a leave until a key goes down again. `pauseWhenLeft(pause)`
+// calls your `pause` when the player really left (a free round stops its clock and shows a Resume key). No package: plain browser events.
+//
+// A ROUND THAT COSTS MONEY must not pause: its deadline must not move. Keep `releaseWhenLost` (the character always stops) and leave `pauseWhenLeft` out.
+/**
+ * Calls `release` each time what is held may be wrong. In it, clear every held key, thumb stick and drag, and any jump or tool that a key press queued.
+ * `keysOnly`, when given, is called when a menu opens (a right click): a menu takes a keyup, but on a touch screen a long press also asks for a menu,
+ * and a thumb that rests on a stick must not lose its walk for that. A menu that your page stopped (`preventDefault`) did not open: nothing is let go.
+ *
+ * After a leave (blur, focus, page hide, the tab hidden or shown), a key REPEAT does not reach your key handlers until a key goes down for the first
+ * time (`repeat` false). The player presses the key again to walk on. A menu is no leave: the held key that a menu took comes back by its repeat.
+ * The repeat is stopped in the capture phase (`stopImmediatePropagation`), so register your own key handlers as usual: they never see it.
+ *
+ * Returns the function that takes the listeners away. `win` and `doc` are given in a test.
+ */
+export function releaseWhenLost(release, keysOnly, win = window, doc = document) {
+    // Set by each leave; a key that goes down (not a repeat) ends it. While it is set, repeats do not reach the page's handlers.
+    let stale = false;
+    const lost = () => {
+        stale = true;
+        release();
+    };
+    const hidden = () => {
+        // Either way the page was left for a while: a repeat that comes now may belong to a key that went up elsewhere.
+        stale = true;
+        if (doc.hidden !== false)
+            release();
+    };
+    // Cmd (Meta) going down or up: each key that is released in between sends no keyup. The OS key on Windows is the same key.
+    const meta = (e) => {
+        const k = e;
+        if (k.key === "Meta" || k.key === "OS" || k.metaKey)
+            release();
+        if (e.type !== "keydown")
+            return;
+        if (!k.repeat)
+            stale = false;
+        else if (stale)
+            e.stopImmediatePropagation();
+    };
+    // At the window, after your own handlers: a handler that stopped the menu has done so by now.
+    const menu = (e) => {
+        if (!e.defaultPrevented)
+            keysOnly?.();
+    };
+    const windowEvents = ["blur", "focus", "pagehide"];
+    for (const type of windowEvents)
+        win.addEventListener(type, lost);
+    win.addEventListener("contextmenu", menu);
+    doc.addEventListener("visibilitychange", hidden);
+    // Capture: before your key handler, which then leaves a key with Cmd out (`swallowsKeyup`), and which a stale repeat never reaches.
+    win.addEventListener("keydown", meta, true);
+    win.addEventListener("keyup", meta, true);
+    return () => {
+        for (const type of windowEvents)
+            win.removeEventListener(type, lost);
+        win.removeEventListener("contextmenu", menu);
+        doc.removeEventListener("visibilitychange", hidden);
+        win.removeEventListener("keydown", meta, true);
+        win.removeEventListener("keyup", meta, true);
+    };
+}
+/** A keydown whose keyup may never come (Cmd is down, or it is the Cmd key): it must not go into your held set. */
+export const swallowsKeyup = (e) => !!e.metaKey || e.key === "Meta" || e.key === "OS";
+/**
+ * Calls `pause` when the player leaves: the tab or the window is hidden (`visibilitychange`: another tab, a minimized window, a locked phone,
+ * another app on a phone), or the window loses the focus to another window (a real `blur`: not a script's, and not a focus that moves inside
+ * your page into a dialog or a field). It may call `pause` twice for one leave (a blur, then the tab hiding): make `pause` safe to call twice.
+ * Show a Resume key and stop your clock in it; start nothing again until the player taps Resume. Returns the function that takes the listeners away.
+ * `win` and `doc` are given in a test.
+ */
+export function pauseWhenLeft(pause, win = window, doc = document) {
+    const hidden = () => {
+        if (doc.hidden)
+            pause();
+    };
+    const blur = (e) => {
+        if (!e.isTrusted || doc.hasFocus?.())
+            return;
+        pause();
+    };
+    win.addEventListener("blur", blur);
+    doc.addEventListener("visibilitychange", hidden);
+    return () => {
+        win.removeEventListener("blur", blur);
+        doc.removeEventListener("visibilitychange", hidden);
+    };
+}

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;