@starcried/starlite-vrm 0.1.0-alpha.2 → 0.1.0-alpha.3

package/README.md

@@ -39,6 +39,24 @@ const controller = await mountModelWidget(host, {
 
 ## 进阶
 
+`adjustments` 为当前模型提供可选的姿态与跟随校准，例如：
+
+```js
+controller.setModelAdjustments({
+  idle: { armLiftDegrees: 10, palmTwistDegrees: 5, wristLiftDegrees: 8, handCurl: 0.2, elbowBendDegrees: 8 },
+  gaze: { headStrength: 0.8, eyeStrength: 1, smoothingMs: 120 },
+});
+```
+
+相同对象也可作为挂载配置的 `adjustments`。该方法整体替换当前调节，`{}` 恢复原样；实时调节不重新加载模型、不重启动作。双臂抬高范围为 −30～45°，掌心扭转和手腕抬高均为 −45～45°，肘部弯曲为 −20～45°；掌心调节左右对称；手腕抬高在前臂弯曲平面调整手部方向，正值向上折，不移动腕部位置，不改变上臂、前臂或掌心扭转的方向约定。手部张合为 0～1，省略时保留原动作，0 张开、1 握拳，仅处理已映射的标准手指。姿态调节只作用于程序内置 Idle，不改模型自带动作或外部 VRMA。头眼跟随强度各为 0～2，默认 1；0 停用对应跟随，仍尊重现有限角和前景动作方向。平滑时间为 20～1000 ms，省略时沿用 `gaze.smoothingMs`。模型缺少眼球绑定时，调节不能生成眼球跟随。
+
+`0.1.0-alpha.3` 提供 `performance: {show: true}`（默认关闭），也可用
+`controller.setPerformanceVisible?.(true)` 即时切换。含义和测量边界见
+[性能预算](https://github.com/StarCried/starlite/blob/main/docs/performance.md)。
+Node 侧 `@starcried/starlite-vrm/inspect` 返回 `capabilities` 与逻辑 `metrics`；
+`VrmInspectionError.code/details` 提供受控原因及缺失骨骼名，不回显模型路径或外部 URI。
+见[兼容说明](https://github.com/StarCried/starlite/blob/main/docs/model-compatibility.md)。
+
 [动作、句库、相机与性能配置](https://github.com/StarCried/starlite/blob/main/docs/configuration.md) · [构建博客资源](https://github.com/StarCried/starlite/blob/main/docs/examples/prepare-vrm.cjs) · [Hexo 插件](https://github.com/StarCried/starlite/blob/main/packages/hexo/README.md) · [开发与验证](https://github.com/StarCried/starlite/blob/main/docs/development.md)
 
 配置 CSP 的网站须为模型内嵌贴图允许适用的 `img-src blob:` 和 `connect-src blob:`。独立网页若要在手机上避免加载运行时，须在检查屏宽后动态导入；上例的静态导入会下载 JS。

package/dist/adjustments.d.ts

@@ -0,0 +1,14 @@
+import { AnimationClip, type Object3D } from "three";
+import type { VRMHumanoid, VRMPose } from "@pixiv/three-vrm";
+import type { ModelAdjustments } from "./types.js";
+type Idle = NonNullable<ModelAdjustments["idle"]>;
+/** A controller-owned derivative of the program Idle; authored clips never enter here. */
+export declare class AdjustableIdle {
+    #private;
+    readonly clip: AnimationClip;
+    constructor(source: AnimationClip, root: Object3D, humanoid: Pick<VRMHumanoid, "getNormalizedBoneNode">, metaVersion?: "0" | "1");
+    update(idle?: Idle): void;
+    /** Refresh stopped/paused neutral without sampling or resetting the live mixer. */
+    neutralPose(pose: VRMPose): VRMPose;
+}
+export {};

package/dist/adjustments.js

@@ -0,0 +1,106 @@
+import { AnimationClip, MathUtils, PropertyBinding, Quaternion, Vector3 } from "three";
+/** A controller-owned derivative of the program Idle; authored clips never enter here. */
+export class AdjustableIdle {
+    clip;
+    #targets = [];
+    #basis;
+    constructor(source, root, humanoid, metaVersion = "1") {
+        // Match createVRMAnimationClip: VRM0 faces -Z, so its normalized rig's
+        // X/Z rotation axes are the opposite of VRM1's character-space axes.
+        this.#basis = metaVersion === "0" ? -1 : 1;
+        const bones = new Map();
+        for (const [side, sign] of [["left", 1], ["right", -1]]) {
+            const add = (suffix, kind, joint) => {
+                const bone = (side + suffix), node = humanoid.getNormalizedBoneNode(bone);
+                if (node)
+                    bones.set(node, { bone, side: sign, kind, ...(joint ? { joint } : {}) });
+            };
+            add("UpperArm", "arm");
+            add("LowerArm", "elbow");
+            add("Hand", "palm");
+            for (const finger of ["Index", "Middle", "Ring", "Little"]) {
+                for (const joint of ["Proximal", "Intermediate", "Distal"])
+                    add(finger + joint, "finger", joint);
+            }
+            for (const joint of ["Metacarpal", "Proximal", "Distal"])
+                add("Thumb" + joint, "thumb", joint);
+        }
+        const tracks = source.tracks.map(track => {
+            const parsed = PropertyBinding.parseTrackName(track.name);
+            const node = PropertyBinding.findNode(root, parsed.nodeName);
+            const bone = node ? bones.get(node) : undefined;
+            if (!bone || parsed.propertyName !== "quaternion" || track.getValueSize() !== 4 || track.ValueTypeName !== "quaternion")
+                return track;
+            const copy = track.clone();
+            this.#targets.push({ ...bone, source: track, track: copy });
+            return copy;
+        });
+        this.clip = new AnimationClip(source.name, source.duration, tracks, source.blendMode);
+    }
+    update(idle = {}) {
+        const rotation = new Quaternion(), correction = new Quaternion(), wrist = new Quaternion(), motion = new Quaternion(), initial = new Quaternion(), axis = new Vector3();
+        for (const target of this.#targets) {
+            const { source, track, side, kind } = target;
+            track.values.set(source.values);
+            const degrees = kind === "arm" ? idle.armLiftDegrees ?? 0
+                : kind === "palm" ? idle.palmTwistDegrees ?? 0 : kind === "elbow" ? idle.elbowBendDegrees ?? 0 : 0;
+            const hand = kind === "finger" || kind === "thumb";
+            const wristDegrees = kind === "palm" ? idle.wristLiftDegrees ?? 0 : 0;
+            if ((!hand && !degrees && !wristDegrees) || (hand && idle.handCurl === undefined))
+                continue;
+            if (hand) {
+                initial.fromArray(source.values, 0).invert();
+                // The four fingers curl towards the palm. The thumb has its own
+                // opposition and flexion recipe rather than sharing their bend axis.
+                const curl = idle.handCurl;
+                if (kind === "finger") {
+                    const bend = target.joint === "Proximal" ? 70 : target.joint === "Intermediate" ? 90 : 60;
+                    correction.setFromAxisAngle(axis.set(0, 0, -side * this.#basis), MathUtils.degToRad(bend * curl));
+                }
+                else if (target.joint === "Metacarpal") {
+                    correction.setFromAxisAngle(axis.set(0, side, 0), MathUtils.degToRad(35 * curl));
+                    correction.multiply(rotation.setFromAxisAngle(axis.set(0, 0, -side * this.#basis), MathUtils.degToRad(15 * curl)));
+                }
+                else {
+                    correction.setFromAxisAngle(axis.set(0, 0, -side * this.#basis), MathUtils.degToRad((target.joint === "Proximal" ? 45 : 65) * curl));
+                }
+            }
+            else {
+                // A rotation axis is an axial vector: mirroring left/right across X
+                // keeps its X sign and reverses Y/Z. Opposite palm-X signs would
+                // turn one palm inward and the other outward.
+                axis.set(kind === "palm" ? this.#basis : 0, kind === "elbow" ? -side : 0, kind === "arm" ? side * this.#basis : 0);
+                correction.setFromAxisAngle(axis, MathUtils.degToRad(degrees));
+                if (kind === "palm")
+                    wrist.setFromAxisAngle(axis.set(0, 0, side * this.#basis), MathUtils.degToRad(wristDegrees));
+            }
+            for (let at = 0; at < source.values.length; at += 4) {
+                rotation.fromArray(source.values, at);
+                if (hand) {
+                    // Keep the source motion around its first sample, including tiny
+                    // breathing changes, while replacing only the static finger pose.
+                    motion.copy(initial).multiply(rotation);
+                    rotation.copy(correction).multiply(motion);
+                }
+                else if (kind === "palm") {
+                    // Bend in the forearm's frame before applying the palm-local twist,
+                    // so changing palm direction does not rotate the wrist-lift axis.
+                    rotation.premultiply(wrist).multiply(correction);
+                }
+                else if (kind === "arm")
+                    rotation.premultiply(correction);
+                else
+                    rotation.multiply(correction);
+                rotation.normalize().toArray(track.values, at);
+            }
+        }
+    }
+    /** Refresh stopped/paused neutral without sampling or resetting the live mixer. */
+    neutralPose(pose) {
+        const result = { ...pose };
+        for (const { bone, track } of this.#targets) {
+            result[bone] = { ...result[bone], rotation: Array.from(track.values.slice(0, 4)) };
+        }
+        return result;
+    }
+}

package/dist/config.cjs

@@ -20,6 +20,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var config_exports = {};
 __export(config_exports, {
   validateCharacterProfile: () => validateCharacterProfile,
+  validateModelAdjustments: () => validateModelAdjustments,
   validateVrmWidgetConfig: () => validateVrmWidgetConfig
 });
 module.exports = __toCommonJS(config_exports);
@@ -61,12 +62,40 @@ function resolveDialogueSentences(input, animations, field) {
   return { ...lines ? { lines } : {}, linesByAnimation };
 }
 
+// ../core/dist/performance.js
+function validatePerformanceConfig(value) {
+  if (value === void 0)
+    return;
+  if (!value || typeof value !== "object" || Array.isArray(value) || Object.keys(value).some((key) => key !== "show") || "show" in value && value.show !== void 0 && typeof value.show !== "boolean") {
+    throw new Error("performance must be an object with an optional boolean show");
+  }
+}
+
 // src/config.ts
 function finite(value, min, max) {
   return typeof value === "number" && Number.isFinite(value) && value >= min && value <= max;
 }
+function validateModelAdjustments(input) {
+  const object = (value) => Boolean(value && typeof value === "object" && !Array.isArray(value));
+  if (!object(input) || Object.keys(input).some((key) => key !== "idle" && key !== "gaze")) throw new Error("invalid model adjustments");
+  const groups = {
+    idle: { armLiftDegrees: [-30, 45], palmTwistDegrees: [-45, 45], wristLiftDegrees: [-45, 45], handCurl: [0, 1], elbowBendDegrees: [-20, 45] },
+    gaze: { headStrength: [0, 2], eyeStrength: [0, 2], smoothingMs: [20, 1e3] }
+  };
+  for (const [group, limits] of Object.entries(groups)) {
+    const values = input[group];
+    if (values === void 0) continue;
+    if (!object(values)) throw new Error(`invalid model adjustments.${group}`);
+    for (const [key, value] of Object.entries(values)) {
+      const range = Object.hasOwn(limits, key) ? limits[key] : void 0;
+      if (!range || value !== void 0 && !finite(value, range[0], range[1])) throw new Error(`invalid model adjustments.${group}.${key}`);
+    }
+  }
+}
 function validateVrmWidgetConfig(config) {
   if (!config || config.backend !== void 0 && config.backend !== "vrm") throw new Error("invalid VRM backend");
+  if (config.adjustments !== void 0) validateModelAdjustments(config.adjustments);
+  validatePerformanceConfig(config.performance);
   if (config.interactions?.passThrough !== void 0 && typeof config.interactions.passThrough !== "boolean") throw new Error("interactions.passThrough must be boolean");
   if (config.interactions?.passThrough && config.interactions.drag) throw new Error("passThrough and drag cannot both be enabled");
   for (const key of ["model", "fallback"]) if (typeof config[key] !== "string" || !config[key].trim()) throw new Error(`${key} is required`);
@@ -148,5 +177,6 @@ function validateCharacterProfile(input) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   validateCharacterProfile,
+  validateModelAdjustments,
   validateVrmWidgetConfig
 });

package/dist/config.d.ts

@@ -1,3 +1,4 @@
-import type { CharacterProfile, VrmWidgetConfig } from "./types.js";
+import type { CharacterProfile, ModelAdjustments, VrmWidgetConfig } from "./types.js";
+export declare function validateModelAdjustments(input: unknown): asserts input is ModelAdjustments;
 export declare function validateVrmWidgetConfig(config: VrmWidgetConfig): void;
 export declare function validateCharacterProfile(input: unknown): asserts input is CharacterProfile;

package/dist/config.js

@@ -1,10 +1,34 @@
-import { resolveDialogueSentences } from "@starcried/starlite-core";
+import { resolveDialogueSentences, validatePerformanceConfig } from "@starcried/starlite-core";
 function finite(value, min, max) {
     return typeof value === "number" && Number.isFinite(value) && value >= min && value <= max;
 }
+export function validateModelAdjustments(input) {
+    const object = (value) => Boolean(value && typeof value === "object" && !Array.isArray(value));
+    if (!object(input) || Object.keys(input).some(key => key !== "idle" && key !== "gaze"))
+        throw new Error("invalid model adjustments");
+    const groups = {
+        idle: { armLiftDegrees: [-30, 45], palmTwistDegrees: [-45, 45], wristLiftDegrees: [-45, 45], handCurl: [0, 1], elbowBendDegrees: [-20, 45] },
+        gaze: { headStrength: [0, 2], eyeStrength: [0, 2], smoothingMs: [20, 1000] },
+    };
+    for (const [group, limits] of Object.entries(groups)) {
+        const values = input[group];
+        if (values === undefined)
+            continue;
+        if (!object(values))
+            throw new Error(`invalid model adjustments.${group}`);
+        for (const [key, value] of Object.entries(values)) {
+            const range = Object.hasOwn(limits, key) ? limits[key] : undefined;
+            if (!range || (value !== undefined && !finite(value, range[0], range[1])))
+                throw new Error(`invalid model adjustments.${group}.${key}`);
+        }
+    }
+}
 export function validateVrmWidgetConfig(config) {
     if (!config || (config.backend !== undefined && config.backend !== "vrm"))
         throw new Error("invalid VRM backend");
+    if (config.adjustments !== undefined)
+        validateModelAdjustments(config.adjustments);
+    validatePerformanceConfig(config.performance);
     if (config.interactions?.passThrough !== undefined && typeof config.interactions.passThrough !== "boolean")
         throw new Error("interactions.passThrough must be boolean");
     if (config.interactions?.passThrough && config.interactions.drag)

package/dist/gaze.d.ts

@@ -1,11 +1,12 @@
 import { type Object3D, type PerspectiveCamera } from "three";
 import type { VRMLookAt } from "@pixiv/three-vrm";
-import type { VrmWidgetConfig } from "./types.js";
+import type { ModelAdjustments, 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"]>);
+    setAdjustments(adjustments?: ModelAdjustments["gaze"]): void;
     move(x: number, y: number, rect: {
         left: number;
         top: number;

package/dist/gaze.js

@@ -18,9 +18,11 @@ export class PointerGaze {
     #tracking = false;
     #yaw = 0;
     #pitch = 0;
+    #adjustments = {};
     constructor(limits = {}) {
         this.limits = limits;
     }
+    setAdjustments(adjustments = {}) { this.#adjustments = { ...adjustments }; }
     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;
@@ -51,16 +53,17 @@ export class PointerGaze {
     /** Normalized humanoid correction precedes the single humanoid update. */
     updateHead(head, camera, delta, authored) {
         this.restoreHead();
-        if (!head || authored) {
+        if (!head || authored || this.#adjustments.headStrength === 0) {
             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;
+        const blend = 1 - Math.exp(-Math.max(0, delta) / ((this.#adjustments.smoothingMs ?? this.limits.smoothingMs ?? 100) / 1000));
+        const yawLimit = this.limits.maxYawDegrees ?? 25, pitchLimit = this.limits.maxPitchDegrees ?? 15, strength = this.#adjustments.headStrength ?? 1;
+        this.#headYaw += (MathUtils.clamp(offset.x * yawLimit * .6 * strength, -yawLimit, yawLimit) - this.#headYaw) * blend;
+        this.#headPitch += (MathUtils.clamp(offset.y * pitchLimit * .6 * strength, -pitchLimit, pitchLimit) - this.#headPitch) * blend;
         this.#headBase.copy(head.quaternion);
         this.#posedHead = head;
         this.#rotation.setFromAxisAngle(this.#scratch.setFromMatrixColumn(camera.matrixWorld, 1), MathUtils.degToRad(this.#headYaw));
@@ -80,12 +83,20 @@ export class PointerGaze {
             this.#pitch = lookAt.pitch;
             return;
         }
+        if (this.#adjustments.eyeStrength === 0) {
+            this.#yaw = 0;
+            this.#pitch = 0;
+            lookAt.yaw = 0;
+            lookAt.pitch = 0;
+            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 offset = this.#offset(camera, this.#head), strength = this.#adjustments.eyeStrength ?? 1;
+            const x = MathUtils.clamp(offset.x * strength, -1, 1), y = MathUtils.clamp(offset.y * strength, -1, 1);
             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)));
@@ -93,7 +104,7 @@ export class PointerGaze {
         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));
+        const blend = 1 - Math.exp(-Math.max(0, delta) / ((this.#adjustments.smoothingMs ?? 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));

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 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 { QuickSettingsMenu, type QuickSettingsOptions, type QuickSettingItem } from "@starcried/starlite-core";
+export { validateModelAdjustments, validateVrmWidgetConfig } from "./config.js";
 export declare function mountModelWidget(host: HTMLElement, config: VrmWidgetConfig, options?: MountOptions): Promise<VrmController>;
 export declare const mountVrmWidget: typeof mountModelWidget;