@starcried/starlite-vrm 0.0.0-stage → 0.1.0-alpha.2

package/dist/default-idle.d.ts

@@ -0,0 +1,2 @@
+/** Approved six-second motion; embedded in the runtime, with no asset request. */
+export declare function defaultIdleBytes(): ArrayBuffer;

package/dist/default-idle.js

@@ -0,0 +1,5 @@
+import { defaultIdleBase64 } from "./default-idle-data.js";
+/** Approved six-second motion; embedded in the runtime, with no asset request. */
+export function defaultIdleBytes() {
+    return Uint8Array.from(atob(defaultIdleBase64), value => value.charCodeAt(0)).buffer;
+}

package/dist/embedded.d.ts

@@ -0,0 +1,11 @@
+import { AnimationClip } from "three";
+import type { GLTF } from "three/addons/loaders/GLTFLoader.js";
+import type { VRM } from "@pixiv/three-vrm";
+type Json = Record<string, any>;
+/** Capture model-local to normalized rig calibration before rotateVRM0 or applying a pose. */
+export declare function prepareEmbeddedAnimations(gltf: GLTF, vrm: VRM, json: Json, signal?: AbortSignal): Promise<{
+    clips: AnimationClip[];
+    eyeClips: ReadonlySet<string>;
+    applyMorphs(): void;
+}>;
+export {};

package/dist/embedded.js

@@ -0,0 +1,154 @@
+import { AnimationClip, InterpolateDiscrete, InterpolateLinear, Interpolant, Matrix3, Matrix4, NumberKeyframeTrack, Object3D, PropertyBinding, Quaternion, Vector3 } from "three";
+import { embeddedAnimationCatalog } from "./inspect.js";
+/** Capture model-local to normalized rig calibration before rotateVRM0 or applying a pose. */
+export async function prepareEmbeddedAnimations(gltf, vrm, json, signal) {
+    const catalog = embeddedAnimationCatalog(json);
+    const rawBones = new Map();
+    for (const [name, raw] of Object.entries(vrm.humanoid.rawHumanBones ?? {})) {
+        if (!raw)
+            continue;
+        const normalized = vrm.humanoid.normalizedHumanBones[name]?.node;
+        if (!normalized)
+            continue;
+        raw.node.updateWorldMatrix(true, false);
+        normalized.updateWorldMatrix(true, false);
+        const parentMatrix = raw.node.parent?.matrixWorld ?? new Matrix4();
+        const normalizedParent = normalized.parent?.matrixWorld ?? new Matrix4();
+        const parent = new Quaternion();
+        parentMatrix.decompose(new Vector3(), parent, new Vector3());
+        rawBones.set(raw.node, { normalized, rest: raw.node.quaternion.clone(), parent, translation: normalizedParent.clone().invert().multiply(parentMatrix), hips: name === "hips", eye: name === "leftEye" || name === "rightEye" });
+    }
+    const proxies = new Map();
+    const registered = new Map();
+    for (const expression of vrm.expressionManager?.expressions ?? []) {
+        for (const bind of expression.binds) {
+            const morph = bind;
+            if (!morph.primitives || morph.index === undefined)
+                continue;
+            for (const mesh of morph.primitives) {
+                const indices = registered.get(mesh) ?? new Set();
+                indices.add(morph.index);
+                registered.set(mesh, indices);
+            }
+        }
+    }
+    const clips = [];
+    const eyeClips = new Set();
+    for (const [clipIndex, entry] of catalog.entries()) {
+        if (clipIndex > 0)
+            await new Promise(resolve => setTimeout(resolve, 0));
+        signal?.throwIfAborted();
+        const source = gltf.animations[clipIndex];
+        if (!source)
+            throw new Error("embedded animation did not load");
+        const animation = json.animations[clipIndex];
+        const expressions = animation.extras?.starlite?.expressions;
+        if (expressions !== undefined && (!expressions || typeof expressions !== "object" || Array.isArray(expressions) || Object.keys(expressions).length > 64))
+            throw new Error("invalid embedded expression tracks");
+        const tracks = [];
+        for (const sourceTrack of source.tracks) {
+            const parsed = PropertyBinding.parseTrackName(sourceTrack.name);
+            const node = PropertyBinding.findNode(gltf.scene, parsed.nodeName);
+            if (!node)
+                throw new Error("embedded animation targets a missing node");
+            const raw = rawBones.get(node);
+            if (raw && parsed.propertyName === "quaternion") {
+                if (raw.eye)
+                    eyeClips.add(entry.name);
+                const track = sourceTrack.clone();
+                track.name = raw.normalized.uuid + ".quaternion";
+                const before = raw.parent, after = raw.rest.clone().invert().multiply(raw.parent.clone().invert());
+                const q = new Quaternion();
+                for (let offset = 0; offset < track.values.length; offset += 4)
+                    q.fromArray(track.values, offset).premultiply(before).multiply(after).toArray(track.values, offset);
+                tracks.push(track);
+            }
+            else if (raw?.hips && parsed.propertyName === "position") {
+                const track = sourceTrack.clone();
+                track.name = raw.normalized.uuid + ".position";
+                const cubic = isCubic(track), derivative = new Matrix3().setFromMatrix4(raw.translation), vector = new Vector3();
+                for (let offset = 0; offset < track.values.length; offset += 3) {
+                    vector.fromArray(track.values, offset);
+                    if (cubic && Math.floor(offset / 3) % 3 !== 1)
+                        vector.applyMatrix3(derivative);
+                    else
+                        vector.applyMatrix4(raw.translation);
+                    vector.toArray(track.values, offset);
+                }
+                tracks.push(track);
+            }
+            else if (parsed.propertyName === "morphTargetInfluences") {
+                // Named samplers preserve expression-driven blink/ear recipes; standard
+                // mesh weights remain in authored files for other glTF viewers.
+                if (expressions !== undefined)
+                    continue;
+                const mesh = node;
+                if (!mesh.morphTargetInfluences)
+                    throw new Error("embedded animation has invalid morph targets");
+                let proxy = proxies.get(mesh);
+                if (!proxy) {
+                    const proxyNode = new Object3D();
+                    const indices = registered.get(mesh) ?? new Set();
+                    proxyNode.weights = mesh.morphTargetInfluences.map((value, index) => indices.has(index) ? 0 : value);
+                    gltf.scene.add(proxyNode);
+                    proxy = { node: proxyNode, mesh, registered: indices };
+                    proxies.set(mesh, proxy);
+                }
+                const cubic = isCubic(sourceTrack), width = sourceTrack.getValueSize() / (cubic ? 3 : 1);
+                if (width !== mesh.morphTargetInfluences.length)
+                    throw new Error("embedded morph track size does not match mesh");
+                for (let index = 0; index < width; index++) {
+                    const track = new NumberKeyframeTrack(proxy.node.uuid + ".weights[" + index + "]", sourceTrack.times.slice(), sourceTrack.values.filter((_, offset) => offset % width === index));
+                    track.createInterpolant = sourceTrack.createInterpolant;
+                    tracks.push(track);
+                }
+            }
+            else {
+                const track = sourceTrack.clone();
+                track.name = node.uuid + "." + parsed.propertyName + (parsed.propertyIndex !== undefined ? "[" + parsed.propertyIndex + "]" : "");
+                tracks.push(track);
+            }
+        }
+        if (expressions !== undefined) {
+            for (const [name, samplerIndex] of Object.entries(expressions)) {
+                const expression = vrm.expressionManager?.getExpression(name);
+                const sampler = Number.isSafeInteger(samplerIndex) ? animation.samplers[samplerIndex] : undefined;
+                if (!expression || !sampler || json.accessors[sampler.output]?.type !== "SCALAR" || json.accessors[sampler.output]?.componentType !== 5126)
+                    throw new Error("invalid embedded expression sampler");
+                const times = await gltf.parser.getDependency("accessor", sampler.input);
+                const values = await gltf.parser.getDependency("accessor", sampler.output);
+                const cubic = sampler.interpolation === "CUBICSPLINE";
+                if (times.itemSize !== 1 || values.itemSize !== 1 || values.count !== times.count * (cubic ? 3 : 1))
+                    throw new Error("invalid embedded expression sampler size");
+                signal?.throwIfAborted();
+                const target = /^VRMExpression_blink(?:Left|Right)?$/.test(expression.name) ? expression.name : expression.uuid;
+                const track = new NumberKeyframeTrack(target + ".weight", Array.from({ length: times.count }, (_, index) => times.getX(index)), Array.from({ length: values.count }, (_, index) => values.getX(index)), sampler.interpolation === "STEP" ? InterpolateDiscrete : InterpolateLinear);
+                if (cubic)
+                    track.createInterpolant = scalarCubicFactory;
+                tracks.push(track);
+            }
+        }
+        if (!tracks.length || tracks.some(track => Array.from(track.values).some(value => !Number.isFinite(value))))
+            throw new Error("embedded animation has invalid tracks");
+        clips.push(new AnimationClip(entry.name, entry.durationMs / 1000, tracks));
+    }
+    return {
+        clips, eyeClips,
+        applyMorphs() {
+            for (const { node, mesh, registered: indices } of proxies.values())
+                for (const [index, value] of node.weights.entries())
+                    mesh.morphTargetInfluences[index] = indices.has(index) ? Math.min(1, mesh.morphTargetInfluences[index] + value) : value;
+        },
+    };
+}
+function isCubic(track) { return Boolean(track.createInterpolant.isInterpolantFactoryMethodGLTFCubicSpline); }
+class ScalarCubicInterpolant extends Interpolant {
+    copySampleValue_(index) { this.resultBuffer[0] = this.sampleValues[index * 3 + 1]; return this.resultBuffer; }
+    interpolate_(index, start, time, end) {
+        const duration = end - start, t = (time - start) / duration, t2 = t * t, t3 = t2 * t;
+        const left = (index - 1) * 3, right = index * 3, values = this.sampleValues;
+        this.resultBuffer[0] = (2 * t3 - 3 * t2 + 1) * values[left + 1] + (t3 - 2 * t2 + t) * duration * values[left + 2] + (-2 * t3 + 3 * t2) * values[right + 1] + (t3 - t2) * duration * values[right];
+        return this.resultBuffer;
+    }
+}
+const scalarCubicFactory = Object.assign(function (result) { return new ScalarCubicInterpolant(this.times, this.values, 1, result); }, { isInterpolantFactoryMethodGLTFCubicSpline: true });

package/dist/gaze.d.ts

@@ -0,0 +1,28 @@
+import { type Object3D, type PerspectiveCamera } from "three";
+import type { VRMLookAt } from "@pixiv/three-vrm";
+import type { VrmWidgetConfig } from "./types.js";
+/** Pointer projection and angle limits are independent of avatar scale and VRM version. */
+export declare class PointerGaze {
+    #private;
+    readonly limits: NonNullable<VrmWidgetConfig["gaze"]>;
+    constructor(limits?: NonNullable<VrmWidgetConfig["gaze"]>);
+    move(x: number, y: number, rect: {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    }, viewport?: {
+        width: number;
+        height: number;
+    }): void;
+    reset(): void;
+    /** Remove the last additive correction before the animation mixer samples. */
+    restoreHead(): void;
+    get headAngles(): {
+        yawDegrees: number;
+        pitchDegrees: number;
+    };
+    /** Normalized humanoid correction precedes the single humanoid update. */
+    updateHead(head: Object3D | null, camera: PerspectiveCamera, delta: number, authored: boolean): void;
+    update(lookAt: VRMLookAt, camera: PerspectiveCamera, delta: number, authored: boolean): void;
+}

package/dist/gaze.js

@@ -0,0 +1,102 @@
+import { Vector2, Vector3, Quaternion, MathUtils } from "three";
+/** Pointer projection and angle limits are independent of avatar scale and VRM version. */
+export class PointerGaze {
+    limits;
+    #pointer = new Vector2();
+    #head = new Vector3();
+    #target = new Vector3();
+    #scratch = new Vector3();
+    #headBase = new Quaternion();
+    #parent = new Quaternion();
+    #rotation = new Quaternion();
+    #pitchRotation = new Quaternion();
+    #posedHead;
+    #headYaw = 0;
+    #headPitch = 0;
+    #rect = { left: 0, top: 0, width: 1, height: 1 };
+    #viewport = { width: 1, height: 1 };
+    #tracking = false;
+    #yaw = 0;
+    #pitch = 0;
+    constructor(limits = {}) {
+        this.limits = limits;
+    }
+    move(x, y, rect, viewport = { width: rect.left + rect.width, height: rect.top + rect.height }) {
+        if (![x, y, rect.left, rect.top, rect.width, rect.height, viewport.width, viewport.height].every(Number.isFinite) || rect.width <= 0 || rect.height <= 0 || viewport.width <= 0 || viewport.height <= 0)
+            return;
+        this.#pointer.set(x, y);
+        this.#rect = rect;
+        this.#viewport = viewport;
+        this.#tracking = true;
+    }
+    reset() { this.#tracking = false; }
+    /** Remove the last additive correction before the animation mixer samples. */
+    restoreHead() {
+        if (this.#posedHead)
+            this.#posedHead.quaternion.copy(this.#headBase);
+        this.#posedHead = undefined;
+    }
+    get headAngles() {
+        return { yawDegrees: this.#headYaw, pitchDegrees: this.#headPitch };
+    }
+    #offset(camera, position) {
+        if (!this.#tracking)
+            return new Vector2();
+        const projected = this.#scratch.copy(position).project(camera);
+        const eyeX = this.#rect.left + (projected.x + 1) * this.#rect.width / 2;
+        const eyeY = this.#rect.top + (1 - projected.y) * this.#rect.height / 2;
+        const dx = this.#pointer.x - eyeX, dy = eyeY - this.#pointer.y;
+        return new Vector2(MathUtils.clamp(dx / Math.max(this.#rect.width / 2, dx < 0 ? eyeX : this.#viewport.width - eyeX), -1, 1), MathUtils.clamp(dy / Math.max(this.#rect.height / 2, dy > 0 ? eyeY : this.#viewport.height - eyeY), -1, 1));
+    }
+    /** Normalized humanoid correction precedes the single humanoid update. */
+    updateHead(head, camera, delta, authored) {
+        this.restoreHead();
+        if (!head || authored) {
+            this.#headYaw = 0;
+            this.#headPitch = 0;
+            return;
+        }
+        head.getWorldPosition(this.#head);
+        const offset = this.#offset(camera, this.#head);
+        const blend = 1 - Math.exp(-Math.max(0, delta) / ((this.limits.smoothingMs ?? 100) / 1000));
+        this.#headYaw += (offset.x * (this.limits.maxYawDegrees ?? 25) * .6 - this.#headYaw) * blend;
+        this.#headPitch += (offset.y * (this.limits.maxPitchDegrees ?? 15) * .6 - this.#headPitch) * blend;
+        this.#headBase.copy(head.quaternion);
+        this.#posedHead = head;
+        this.#rotation.setFromAxisAngle(this.#scratch.setFromMatrixColumn(camera.matrixWorld, 1), MathUtils.degToRad(this.#headYaw));
+        this.#pitchRotation.setFromAxisAngle(this.#scratch.setFromMatrixColumn(camera.matrixWorld, 0), -MathUtils.degToRad(this.#headPitch));
+        this.#rotation.multiply(this.#pitchRotation);
+        if (head.parent)
+            head.parent.getWorldQuaternion(this.#parent);
+        else
+            this.#parent.identity();
+        this.#rotation.premultiply(this.#parent.clone().invert()).multiply(this.#parent);
+        head.quaternion.premultiply(this.#rotation);
+    }
+    update(lookAt, camera, delta, authored) {
+        lookAt.autoUpdate = false;
+        if (authored) {
+            this.#yaw = lookAt.yaw;
+            this.#pitch = lookAt.pitch;
+            return;
+        }
+        lookAt.humanoid.getRawBoneNode("head")?.updateWorldMatrix(true, false);
+        lookAt.getLookAtWorldPosition(this.#head);
+        const yawLimit = this.limits.maxYawDegrees ?? 25, pitchLimit = this.limits.maxPitchDegrees ?? 15;
+        this.#target.copy(camera.position);
+        if (this.#tracking) {
+            const { x, y } = this.#offset(camera, this.#head);
+            const distance = camera.position.distanceTo(this.#head);
+            this.#target.addScaledVector(this.#scratch.setFromMatrixColumn(camera.matrixWorld, 0), distance * Math.tan(MathUtils.degToRad(x * yawLimit)));
+            this.#target.addScaledVector(this.#scratch.setFromMatrixColumn(camera.matrixWorld, 1), distance / Math.cos(MathUtils.degToRad(x * yawLimit)) * Math.tan(MathUtils.degToRad(y * pitchLimit)));
+        }
+        lookAt.lookAt(this.#target);
+        const yaw = Math.max(-yawLimit, Math.min(yawLimit, lookAt.yaw));
+        const pitch = Math.max(-pitchLimit, Math.min(pitchLimit, lookAt.pitch));
+        const blend = 1 - Math.exp(-Math.max(0, delta) / ((this.limits.smoothingMs ?? 100) / 1000));
+        this.#yaw += (yaw - this.#yaw) * blend;
+        this.#pitch += (pitch - this.#pitch) * blend;
+        lookAt.yaw = Math.max(-yawLimit, Math.min(yawLimit, this.#yaw));
+        lookAt.pitch = Math.max(-pitchLimit, Math.min(pitchLimit, this.#pitch));
+    }
+}

package/dist/host-motion.d.ts

@@ -0,0 +1,14 @@
+import { Object3D, type PerspectiveCamera } from "three";
+import type { VRMSpringBoneManager } from "@pixiv/three-vrm";
+/** Window movement exists outside the canvas. Feed an equivalent bounded world
+ * translation to the actual VRM solver, then remove it before drawing. */
+export declare class HostMotion {
+    #private;
+    readonly root: Object3D;
+    readonly manager?: VRMSpringBoneManager | undefined;
+    constructor(root: Object3D, manager?: VRMSpringBoneManager | undefined);
+    setPosition(x: number, y: number): void;
+    suspend(): void;
+    update(delta: number, camera: PerspectiveCamera, height: number, beforePhysics?: () => void): void;
+    destroy(): void;
+}

package/dist/host-motion.js

@@ -0,0 +1,97 @@
+import { MathUtils, Object3D, Vector3 } from "three";
+/** Window movement exists outside the canvas. Feed an equivalent bounded world
+ * translation to the actual VRM solver, then remove it before drawing. */
+export class HostMotion {
+    root;
+    manager;
+    #last;
+    #pending = new Vector3();
+    #offset = new Vector3();
+    #position = new Vector3();
+    #movement = new Vector3();
+    #up = new Vector3();
+    #centers = new Map();
+    #originals = new Map();
+    constructor(root, manager) {
+        this.root = root;
+        this.manager = manager;
+        root.updateMatrixWorld(true);
+        for (const joint of [...(manager?.joints ?? [])]) {
+            if (!joint.center)
+                continue;
+            const original = joint.center;
+            let proxy = this.#centers.get(original);
+            if (!proxy) {
+                proxy = new Object3D();
+                proxy.matrixAutoUpdate = false;
+                proxy.matrix.copy(original.matrixWorld);
+                proxy.updateMatrixWorld(true);
+                this.#centers.set(original, proxy);
+            }
+            this.#originals.set(joint, original);
+            // Public remove/add invalidates the manager's dependency ordering.
+            manager.deleteJoint(joint);
+            joint.center = proxy;
+            manager.addJoint(joint);
+        }
+        if (this.#originals.size)
+            manager?.reset();
+    }
+    setPosition(x, y) {
+        if (![x, y].every(Number.isFinite) || Math.max(Math.abs(x), Math.abs(y)) > 65536)
+            throw new Error("invalid host position");
+        if (this.#last) {
+            this.#pending.x += x - this.#last[0];
+            this.#pending.y += y - this.#last[1];
+        }
+        this.#last = [x, y];
+    }
+    suspend() { this.#last = undefined; this.#pending.set(0, 0, 0); }
+    update(delta, camera, height, beforePhysics) {
+        if (!this.manager) {
+            beforePhysics?.();
+            return;
+        }
+        if (delta > 0) {
+            const depth = Math.max(.1, camera.position.distanceTo(this.root.position));
+            const metresPerPixel = 2 * depth * Math.tan(MathUtils.degToRad(camera.fov / 2)) / Math.max(1, height);
+            this.#movement.setFromMatrixColumn(camera.matrixWorld, 0).multiplyScalar(this.#pending.x * metresPerPixel * .35);
+            this.#up.setFromMatrixColumn(camera.matrixWorld, 1).multiplyScalar(-this.#pending.y * metresPerPixel * .35);
+            this.#movement.add(this.#up).clampLength(0, .08);
+            this.#pending.set(0, 0, 0);
+            this.#offset.add(this.#movement);
+        }
+        this.#position.copy(this.root.position);
+        this.root.position.add(this.#offset);
+        this.root.updateMatrixWorld(true);
+        for (const [original, proxy] of this.#centers) {
+            proxy.matrix.copy(original.matrixWorld);
+            proxy.matrix.elements[12] -= this.#offset.x;
+            proxy.matrix.elements[13] -= this.#offset.y;
+            proxy.matrix.elements[14] -= this.#offset.z;
+            proxy.updateMatrixWorld(true);
+        }
+        // A rest-pose capture must see the same translated world as the solver's
+        // retained tails. Drawing-space captures after a drag would reapply the
+        // whole host offset on every expression change, flipping the ears.
+        // This also applies at delta zero: pose sampling can still refresh a rest.
+        try {
+            beforePhysics?.();
+            this.manager.update(delta);
+        }
+        finally {
+            this.root.position.copy(this.#position);
+            this.root.updateMatrixWorld(true);
+        }
+    }
+    destroy() {
+        for (const [joint, original] of this.#originals) {
+            this.manager?.deleteJoint(joint);
+            joint.center = original;
+            this.manager?.addJoint(joint);
+        }
+        this.#originals.clear();
+        this.#centers.clear();
+        this.suspend();
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+import { type MountOptions } from "@starcried/starlite-core";
+import type { VrmController, VrmWidgetConfig } from "./types.js";
+export type * from "./types.js";
+export { validateVrmWidgetConfig } from "./config.js";
+export declare function mountModelWidget(host: HTMLElement, config: VrmWidgetConfig, options?: MountOptions): Promise<VrmController>;
+export declare const mountVrmWidget: typeof mountModelWidget;