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

package/dist/config.cjs

@@ -19,11 +19,35 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/config.ts
 var config_exports = {};
 __export(config_exports, {
+  BUILTIN_ANIMATIONS: () => BUILTIN_ANIMATIONS,
+  isBuiltinAnimation: () => isBuiltinAnimation,
   validateCharacterProfile: () => validateCharacterProfile,
+  validateEnvironmentLighting: () => validateEnvironmentLighting,
+  validateModelAdjustments: () => validateModelAdjustments,
   validateVrmWidgetConfig: () => validateVrmWidgetConfig
 });
 module.exports = __toCommonJS(config_exports);
 
+// ../core/dist/locale.js
+function validateLocale(value) {
+  if (value !== void 0 && value !== "zh-CN" && value !== "en") {
+    throw new Error("locale must be zh-CN or en");
+  }
+}
+
+// ../core/dist/environment-lighting.js
+function validateEnvironmentLighting(input) {
+  if (!input || typeof input !== "object" || Array.isArray(input))
+    throw new Error("environmentLighting must be an object");
+  const value = input;
+  if (Object.keys(value).some((key) => key !== "color" && key !== "strength" && key !== "brightness") || typeof value.color !== "string" || !/^#[0-9a-f]{6}$/iu.test(value.color))
+    throw new Error("environmentLighting.color must be #RRGGBB");
+  if (value.strength !== void 0 && (typeof value.strength !== "number" || !Number.isFinite(value.strength) || value.strength < 0 || value.strength > 2))
+    throw new Error("environmentLighting.strength must be between 0 and 2");
+  if (value.brightness !== void 0 && (typeof value.brightness !== "number" || !Number.isFinite(value.brightness) || value.brightness < 0.8 || value.brightness > 1.1))
+    throw new Error("environmentLighting.brightness must be between 0.8 and 1.1");
+}
+
 // ../core/dist/dialogue.js
 function resolveDialogueSentences(input, animations, field) {
   const resolve = (value, path) => {
@@ -61,12 +85,53 @@ 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/builtin-motion-catalog.ts
+var BUILTIN_ANIMATIONS = [
+  { name: "StarLiteIdle", durationMs: 6e3 },
+  { name: "StarLiteCuriousPeek", durationMs: 2100 },
+  { name: "StarLiteHappyWave", durationMs: 4600 },
+  { name: "StarLiteSleepyStartle", durationMs: 5500 }
+];
+function isBuiltinAnimation(name) {
+  return BUILTIN_ANIMATIONS.some((animation) => animation.name === name);
+}
+
 // 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");
+  validateLocale(config.locale);
+  if (config.adjustments !== void 0) validateModelAdjustments(config.adjustments);
+  validatePerformanceConfig(config.performance);
+  if (config.environmentLighting !== void 0) validateEnvironmentLighting(config.environmentLighting);
   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`);
@@ -102,11 +167,11 @@ function validateVrmWidgetConfig(config) {
     names.add(name);
   }
   for (const animation of animations) {
-    if (!animation || typeof animation.name !== "string" || !animation.name.trim() || animation.name.length > 128 || names.has(animation.name) || typeof animation.url !== "string" || !animation.url.trim()) throw new Error("invalid or duplicate animation");
+    if (!animation || typeof animation.name !== "string" || !animation.name.trim() || animation.name.length > 128 || names.has(animation.name) || animation.name !== "StarLiteIdle" && isBuiltinAnimation(animation.name) || typeof animation.url !== "string" || !animation.url.trim()) throw new Error("invalid or duplicate animation");
     if (animation.durationMs !== void 0 && !finite(animation.durationMs, 1, 6e5)) throw new Error("invalid animation duration");
     names.add(animation.name);
   }
-  names.add("StarLiteIdle");
+  for (const { name } of BUILTIN_ANIMATIONS) names.add(name);
   for (const name of config.ambient?.animations ?? []) if (!names.has(name)) throw new Error(`unknown ambient animation: ${name}`);
   if ((config.ambient?.animations?.length ?? 0) > 1) throw new Error("VRM supports one explicitly configured ambient clip");
   if (config.neutralAnimation !== void 0 && !names.has(config.neutralAnimation)) throw new Error("unknown neutral animation");
@@ -147,6 +212,10 @@ function validateCharacterProfile(input) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  BUILTIN_ANIMATIONS,
+  isBuiltinAnimation,
   validateCharacterProfile,
+  validateEnvironmentLighting,
+  validateModelAdjustments,
   validateVrmWidgetConfig
 });

package/dist/config.d.ts

@@ -1,3 +1,6 @@
-import type { CharacterProfile, VrmWidgetConfig } from "./types.js";
+export { validateEnvironmentLighting } from "@starcried/starlite-core";
+export { BUILTIN_ANIMATIONS, isBuiltinAnimation } from "./builtin-motion-catalog.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,40 @@
-import { resolveDialogueSentences } from "@starcried/starlite-core";
+export { validateEnvironmentLighting } from "@starcried/starlite-core";
+import { validateEnvironmentLighting, resolveDialogueSentences, validatePerformanceConfig, validateLocale } from "@starcried/starlite-core";
+import { BUILTIN_ANIMATIONS, isBuiltinAnimation } from "./builtin-motion-catalog.js";
+export { BUILTIN_ANIMATIONS, isBuiltinAnimation } from "./builtin-motion-catalog.js";
 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");
+    validateLocale(config.locale);
+    if (config.adjustments !== undefined)
+        validateModelAdjustments(config.adjustments);
+    validatePerformanceConfig(config.performance);
+    if (config.environmentLighting !== undefined)
+        validateEnvironmentLighting(config.environmentLighting);
     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)
@@ -46,13 +76,14 @@ export function validateVrmWidgetConfig(config) {
         names.add(name);
     }
     for (const animation of animations) {
-        if (!animation || typeof animation.name !== "string" || !animation.name.trim() || animation.name.length > 128 || names.has(animation.name) || typeof animation.url !== "string" || !animation.url.trim())
+        if (!animation || typeof animation.name !== "string" || !animation.name.trim() || animation.name.length > 128 || names.has(animation.name) || (animation.name !== "StarLiteIdle" && isBuiltinAnimation(animation.name)) || typeof animation.url !== "string" || !animation.url.trim())
             throw new Error("invalid or duplicate animation");
         if (animation.durationMs !== undefined && !finite(animation.durationMs, 1, 600000))
             throw new Error("invalid animation duration");
         names.add(animation.name);
     }
-    names.add("StarLiteIdle");
+    for (const { name } of BUILTIN_ANIMATIONS)
+        names.add(name);
     for (const name of config.ambient?.animations ?? [])
         if (!names.has(name))
             throw new Error(`unknown ambient animation: ${name}`);

package/dist/environment-lighting.d.ts

@@ -0,0 +1,12 @@
+import { DirectionalLight, HemisphereLight } from "three";
+import { type EnvironmentLighting } from "@starcried/starlite-core";
+/** Reuses both existing lights; no capture, material changes or extra render work. */
+export declare class EnvironmentLight {
+    #private;
+    readonly light: HemisphereLight;
+    readonly key: DirectionalLight;
+    constructor();
+    set(value: EnvironmentLighting | null, immediate?: boolean): void;
+    snap(): void;
+    update(delta: number): void;
+}

package/dist/environment-lighting.js

@@ -0,0 +1,82 @@
+import { Color, DirectionalLight, HemisphereLight } from "three";
+import { validateEnvironmentLighting } from "@starcried/starlite-core";
+const luminance = (color) => .2126 * color.r + .7152 * color.g + .0722 * color.b;
+const close = (a, b) => Math.abs(a.r - b.r) < 1e-6 && Math.abs(a.g - b.g) < 1e-6 && Math.abs(a.b - b.b) < 1e-6;
+const encodeSrgb = (linear) => linear <= .0031308 ? 12.92 * linear : 1.055 * linear ** (1 / 2.4) - .055;
+/** Reuses both existing lights; no capture, material changes or extra render work. */
+export class EnvironmentLight {
+    light = new HemisphereLight(0xffffff, 0xb6c6d5, .65);
+    key = new DirectionalLight(0xffffff, 2);
+    #baseSky = this.light.color.clone();
+    #baseGround = this.light.groundColor.clone();
+    #sky = this.#baseSky.clone();
+    #ground = this.#baseGround.clone();
+    #settled = true;
+    #ambientIntensity = .65;
+    #keyIntensity = 2;
+    constructor() { this.key.position.set(-3, 4, 2); }
+    set(value, immediate = false) {
+        if (value !== null)
+            validateEnvironmentLighting(value);
+        this.#sky.copy(this.#baseSky);
+        this.#ground.copy(this.#baseGround);
+        this.#ambientIntensity = .65;
+        this.#keyIntensity = 2;
+        const strength = value?.strength ?? 1;
+        if (value && strength > 0) {
+            // Hex is sRGB; Three converts it to linear working space before arithmetic.
+            const color = new Color(value.color), maximum = Math.max(color.r, color.g, color.b);
+            // Preserve the accepted 0–100% curve exactly; higher values amplify
+            // linearly rather than extrapolating the easing polynomial.
+            const response = strength <= 1 ? 1 - (1 - strength) ** 3 : strength;
+            const perceived = Math.min(1, Math.max(0, encodeSrgb(luminance(color))));
+            const automatic = perceived <= .5 ? .8 + .4 * perceived : 1 + .2 * (perceived - .5);
+            const brightness = 1 + ((value.brightness ?? automatic) - 1) * response;
+            let transfer = 0;
+            if (maximum > 0) {
+                // Near-black compression/noise must not become a fully saturated colour.
+                const confidence = Math.min(1, maximum / .02);
+                const saturation = (maximum - Math.min(color.r, color.g, color.b)) / maximum;
+                if (saturation > 0) {
+                    const hue = color.clone().multiplyScalar(1 / maximum);
+                    // Unit-luminance chroma avoids double darkening. The accepted
+                    // peak-2 cap stays exact through 100%, rising to 3 at 200%.
+                    const peak = strength <= 1 ? 2 : 1 + strength;
+                    const mix = Math.min(.65 * response * confidence, (1 - 1 / peak) / (1 - luminance(hue)), .9);
+                    const filter = new Color(0xffffff).lerp(hue, mix);
+                    filter.multiplyScalar(1 / luminance(filter));
+                    this.#sky.multiply(filter);
+                    this.#ground.multiply(filter).multiplyScalar(luminance(this.#baseGround) / luminance(this.#baseGround.clone().multiply(filter)));
+                    transfer = .8 * response * confidence * saturation;
+                }
+            }
+            // Rebalance a bounded amount of key energy into the existing fill. Its
+            // chromatic contribution is visible while the key colour stays white.
+            this.#ambientIntensity = (.65 + transfer) * brightness;
+            this.#keyIntensity = (2 - transfer) * brightness;
+        }
+        this.#settled = false;
+        if (immediate)
+            this.snap();
+    }
+    snap() {
+        this.light.color.copy(this.#sky);
+        this.light.groundColor.copy(this.#ground);
+        this.light.intensity = this.#ambientIntensity;
+        this.key.intensity = this.#keyIntensity;
+        this.#settled = true;
+    }
+    update(delta) {
+        if (this.#settled || !Number.isFinite(delta) || delta <= 0)
+            return;
+        // ~0.5 seconds to settle. No hidden elapsed time or extra animation frame.
+        const alpha = 1 - Math.exp(-Math.min(delta, .1) / .18);
+        this.light.color.lerp(this.#sky, alpha);
+        this.light.groundColor.lerp(this.#ground, alpha);
+        this.light.intensity += (this.#ambientIntensity - this.light.intensity) * alpha;
+        this.key.intensity += (this.#keyIntensity - this.key.intensity) * alpha;
+        if (close(this.light.color, this.#sky) && close(this.light.groundColor, this.#ground)
+            && Math.abs(this.light.intensity - this.#ambientIntensity) < 1e-6 && Math.abs(this.key.intensity - this.#keyIntensity) < 1e-6)
+            this.snap();
+    }
+}

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,9 @@
+export { resolveLocale, type StarLiteLocale } from "@starcried/starlite-core";
 import { type MountOptions } from "@starcried/starlite-core";
+export { BUILTIN_ANIMATIONS } from "./builtin-motion-catalog.js";
 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;