@pixiv/three-vrm-core 2.1.0-beta.3 → 2.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2019-2024 pixiv Inc.
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/lib/three-vrm-core.js

@@ -1,5 +1,5 @@
 /*!
- * @pixiv/three-vrm-core v2.1.0-beta.3
+ * @pixiv/three-vrm-core v2.1.0
  * The implementation of core features of VRM, for @pixiv/three-vrm
  *
  * Copyright (c) 2020-2024 pixiv Inc.

package/lib/three-vrm-core.module.js

@@ -1,5 +1,5 @@
 /*!
- * @pixiv/three-vrm-core v2.1.0-beta.3
+ * @pixiv/three-vrm-core v2.1.0
  * The implementation of core features of VRM, for @pixiv/three-vrm
  *
  * Copyright (c) 2020-2024 pixiv Inc.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pixiv/three-vrm-core",
-  "version": "2.1.0-beta.3",
+  "version": "2.1.0",
   "description": "The implementation of core features of VRM, for @pixiv/three-vrm",
   "license": "MIT",
   "author": "pixiv",
@@ -50,8 +50,8 @@
     ]
   },
   "dependencies": {
-    "@pixiv/types-vrm-0.0": "2.1.0-beta.3",
-    "@pixiv/types-vrmc-vrm-1.0": "2.1.0-beta.3"
+    "@pixiv/types-vrm-0.0": "2.1.0",
+    "@pixiv/types-vrmc-vrm-1.0": "2.1.0"
   },
   "devDependencies": {
     "@types/three": "^0.160.0",
@@ -60,5 +60,6 @@
   "peerDependencies": {
     "@types/three": "^0.160.0",
     "three": "^0.160.0"
-  }
+  },
+  "gitHead": "0d96aeaa6e20baa8158658652179df20a162d8a3"
 }

package/ts3.4/types/VRMCore.d.ts

@@ -0,0 +1,58 @@
+import * as THREE from 'three';
+import { VRMExpressionManager } from './expressions/VRMExpressionManager';
+import { VRMFirstPerson } from './firstPerson/VRMFirstPerson';
+import { VRMHumanoid } from './humanoid/VRMHumanoid';
+import { VRMLookAt } from './lookAt/VRMLookAt';
+import { VRMMeta } from './meta/VRMMeta';
+import { VRMCoreParameters } from './VRMCoreParameters';
+/**
+ * A class that represents a single VRM model.
+ * This class only includes core spec of the VRM (`VRMC_vrm`).
+ */
+export declare class VRMCore {
+    /**
+     * `THREE.Group` that contains the entire VRM.
+     */
+    readonly scene: THREE.Group;
+    /**
+     * Contains meta fields of the VRM.
+     * You might want to refer these license fields before use your VRMs.
+     */
+    readonly meta: VRMMeta;
+    /**
+     * Contains {@link VRMHumanoid} of the VRM.
+     * You can control each bones using {@link VRMHumanoid.getNormalizedBoneNode} or {@link VRMHumanoid.getRawBoneNode}.
+     *
+     * @TODO Add a link to VRM spec
+     */
+    readonly humanoid: VRMHumanoid;
+    /**
+     * Contains {@link VRMExpressionManager} of the VRM.
+     * You might want to control these facial expressions via {@link VRMExpressionManager.setValue}.
+     */
+    readonly expressionManager?: VRMExpressionManager;
+    /**
+     * Contains {@link VRMFirstPerson} of the VRM.
+     * VRMFirstPerson is mostly used for mesh culling for first person view.
+     */
+    readonly firstPerson?: VRMFirstPerson;
+    /**
+     * Contains {@link VRMLookAt} of the VRM.
+     * You might want to use {@link VRMLookAt.target} to control the eye direction of your VRMs.
+     */
+    readonly lookAt?: VRMLookAt;
+    /**
+     * Create a new VRM instance.
+     *
+     * @param params [[VRMParameters]] that represents components of the VRM
+     */
+    constructor(params: VRMCoreParameters);
+    /**
+     * **You need to call this on your update loop.**
+     *
+     * This function updates every VRM components.
+     *
+     * @param delta deltaTime
+     */
+    update(delta: number): void;
+}

package/ts3.4/types/VRMCoreLoaderPlugin.d.ts

@@ -0,0 +1,18 @@
+import { GLTF, GLTFLoaderPlugin, GLTFParser } from 'three/examples/jsm/loaders/GLTFLoader.js';
+import { VRMCoreLoaderPluginOptions } from './VRMCoreLoaderPluginOptions';
+import { VRMExpressionLoaderPlugin } from './expressions/VRMExpressionLoaderPlugin';
+import { VRMFirstPersonLoaderPlugin } from './firstPerson/VRMFirstPersonLoaderPlugin';
+import { VRMHumanoidLoaderPlugin } from './humanoid/VRMHumanoidLoaderPlugin';
+import { VRMMetaLoaderPlugin } from './meta/VRMMetaLoaderPlugin';
+import { VRMLookAtLoaderPlugin } from './lookAt/VRMLookAtLoaderPlugin';
+export declare class VRMCoreLoaderPlugin implements GLTFLoaderPlugin {
+    readonly name: string;
+    readonly parser: GLTFParser;
+    readonly expressionPlugin: VRMExpressionLoaderPlugin;
+    readonly firstPersonPlugin: VRMFirstPersonLoaderPlugin;
+    readonly humanoidPlugin: VRMHumanoidLoaderPlugin;
+    readonly lookAtPlugin: VRMLookAtLoaderPlugin;
+    readonly metaPlugin: VRMMetaLoaderPlugin;
+    constructor(parser: GLTFParser, options?: VRMCoreLoaderPluginOptions);
+    afterRoot(gltf: GLTF): Promise<void>;
+}

package/ts3.4/types/VRMCoreLoaderPluginOptions.d.ts

@@ -0,0 +1,19 @@
+import { VRMExpressionLoaderPlugin } from './expressions/VRMExpressionLoaderPlugin';
+import { VRMFirstPersonLoaderPlugin } from './firstPerson/VRMFirstPersonLoaderPlugin';
+import { VRMHumanoidLoaderPlugin } from './humanoid/VRMHumanoidLoaderPlugin';
+import { VRMLookAtLoaderPlugin } from './lookAt/VRMLookAtLoaderPlugin';
+import { VRMMetaLoaderPlugin } from './meta/VRMMetaLoaderPlugin';
+export interface VRMCoreLoaderPluginOptions {
+    expressionPlugin?: VRMExpressionLoaderPlugin;
+    firstPersonPlugin?: VRMFirstPersonLoaderPlugin;
+    humanoidPlugin?: VRMHumanoidLoaderPlugin;
+    lookAtPlugin?: VRMLookAtLoaderPlugin;
+    metaPlugin?: VRMMetaLoaderPlugin;
+    /**
+     * If assigned, the object will be used as a helper root of every component.
+     * Useful for debug.
+     * Will be overwritten if you use custom loader plugins for each components.
+     */
+    helperRoot?: THREE.Object3D;
+    autoUpdateHumanBones?: boolean;
+}

package/ts3.4/types/VRMCoreParameters.d.ts

@@ -0,0 +1,16 @@
+import { VRMExpressionManager } from './expressions/VRMExpressionManager';
+import { VRMFirstPerson } from './firstPerson/VRMFirstPerson';
+import { VRMHumanoid } from './humanoid/VRMHumanoid';
+import { VRMLookAt } from './lookAt/VRMLookAt';
+import { VRMMeta } from './meta/VRMMeta';
+/**
+ * Parameters for a {@link VRMCore} class.
+ */
+export interface VRMCoreParameters {
+    scene: THREE.Group;
+    meta: VRMMeta;
+    humanoid: VRMHumanoid;
+    expressionManager?: VRMExpressionManager;
+    firstPerson?: VRMFirstPerson;
+    lookAt?: VRMLookAt;
+}

package/ts3.4/types/expressions/VRMExpression.d.ts

@@ -0,0 +1,65 @@
+import * as THREE from 'three';
+import { VRMExpressionBind } from './VRMExpressionBind';
+import { VRMExpressionOverrideType } from './VRMExpressionOverrideType';
+export declare class VRMExpression extends THREE.Object3D {
+    /**
+     * Name of this expression.
+     * Distinguished with `name` since `name` will be conflicted with Object3D.
+     */
+    expressionName: string;
+    /**
+     * The current weight of the expression.
+     */
+    weight: number;
+    /**
+     * Interpret values greater than 0.5 as 1.0, ortherwise 0.0.
+     */
+    isBinary: boolean;
+    /**
+     * Specify how the expression overrides blink expressions.
+     */
+    overrideBlink: VRMExpressionOverrideType;
+    /**
+     * Specify how the expression overrides lookAt expressions.
+     */
+    overrideLookAt: VRMExpressionOverrideType;
+    /**
+     * Specify how the expression overrides mouth expressions.
+     */
+    overrideMouth: VRMExpressionOverrideType;
+    private _binds;
+    readonly type: string | 'VRMExpression';
+    /*
+    * A value represents how much it should override blink expressions.
+    * `0.0` == no override at all, `1.0` == completely block the expressions.
+    */
+    readonly overrideBlinkAmount: number;
+    /*
+    * A value represents how much it should override lookAt expressions.
+    * `0.0` == no override at all, `1.0` == completely block the expressions.
+    */
+    readonly overrideLookAtAmount: number;
+    /*
+    * A value represents how much it should override mouth expressions.
+    * `0.0` == no override at all, `1.0` == completely block the expressions.
+    */
+    readonly overrideMouthAmount: number;
+    constructor(expressionName: string);
+    addBind(bind: VRMExpressionBind): void;
+    /**
+     * Apply weight to every assigned blend shapes.
+     * Should be called every frame.
+     */
+    applyWeight(options?: {
+        /**
+         * Multiplies a value to its weight to apply.
+         * Intended to be used for overriding an expression weight by another expression.
+         * See also: {@link overrideBlink}, {@link overrideLookAt}, {@link overrideMouth}
+         */
+        multiplier?: number;
+    }): void;
+    /**
+     * Clear previously assigned blend shapes.
+     */
+    clearAppliedWeight(): void;
+}

package/ts3.4/types/expressions/VRMExpressionBind.d.ts

@@ -0,0 +1,11 @@
+export interface VRMExpressionBind {
+    /**
+     * Apply a weight to this bind.
+     * Applied weights will be accumulated until {@link clearAppliedWeight} is called.
+     */
+    applyWeight(weight: number): void;
+    /**
+     * Clear previously applied weights.
+     */
+    clearAppliedWeight(): void;
+}

package/ts3.4/types/expressions/VRMExpressionLoaderPlugin.d.ts

@@ -0,0 +1,23 @@
+import * as V0VRM from '@pixiv/types-vrm-0.0';
+import { GLTF, GLTFLoaderPlugin, GLTFParser } from 'three/examples/jsm/loaders/GLTFLoader.js';
+import { VRMExpressionPresetName } from './VRMExpressionPresetName';
+/**
+ * A plugin of GLTFLoader that imports a {@link VRMExpressionManager} from a VRM extension of a GLTF.
+ */
+export declare class VRMExpressionLoaderPlugin implements GLTFLoaderPlugin {
+    static readonly v0v1PresetNameMap: {
+        [v0Name in V0VRM.BlendShapePresetName]?: VRMExpressionPresetName;
+    };
+    readonly parser: GLTFParser;
+    readonly name: string;
+    constructor(parser: GLTFParser);
+    afterRoot(gltf: GLTF): Promise<void>;
+    /**
+     * Import a {@link VRMExpressionManager} from a VRM.
+     *
+     * @param gltf A parsed result of GLTF taken from GLTFLoader
+     */
+    private _import;
+    private _v1Import;
+    private _v0Import;
+}

package/ts3.4/types/expressions/VRMExpressionManager.d.ts

@@ -0,0 +1,124 @@
+import { VRMExpressionPresetName } from './VRMExpressionPresetName';
+import { VRMExpression } from './VRMExpression';
+export declare class VRMExpressionManager {
+    /**
+     * A set of name or preset name of expressions that will be overridden by {@link VRMExpression.overrideBlink}.
+     */
+    blinkExpressionNames: string[];
+    /**
+     * A set of name or preset name of expressions that will be overridden by {@link VRMExpression.overrideLookAt}.
+     */
+    lookAtExpressionNames: string[];
+    /**
+     * A set of name or preset name of expressions that will be overridden by {@link VRMExpression.overrideMouth}.
+     */
+    mouthExpressionNames: string[];
+    /**
+     * A set of {@link VRMExpression}.
+     * When you want to register expressions, use {@link registerExpression}
+     */
+    private _expressions;
+    readonly expressions: VRMExpression[];
+    /**
+     * A map from name to expression.
+     */
+    private _expressionMap;
+    readonly expressionMap: {
+        [name: string]: VRMExpression;
+    };
+    /*
+    * A map from name to expression, but excluding custom expressions.
+    */
+    readonly presetExpressionMap: {
+        [name in VRMExpressionPresetName]?: VRMExpression;
+    };
+    /*
+    * A map from name to expression, but excluding preset expressions.
+    */
+    readonly customExpressionMap: {
+        [name: string]: VRMExpression;
+    };
+    /**
+     * Create a new {@link VRMExpressionManager}.
+     */
+    constructor();
+    /**
+     * Copy the given {@link VRMExpressionManager} into this one.
+     * @param source The {@link VRMExpressionManager} you want to copy
+     * @returns this
+     */
+    copy(source: VRMExpressionManager): this;
+    /**
+     * Returns a clone of this {@link VRMExpressionManager}.
+     * @returns Copied {@link VRMExpressionManager}
+     */
+    clone(): VRMExpressionManager;
+    /**
+     * Return a registered expression.
+     * If it cannot find an expression, it will return `null` instead.
+     *
+     * @param name Name or preset name of the expression
+     */
+    getExpression(name: VRMExpressionPresetName | string): VRMExpression | null;
+    /**
+     * Register an expression.
+     *
+     * @param expression {@link VRMExpression} that describes the expression
+     */
+    registerExpression(expression: VRMExpression): void;
+    /**
+     * Unregister an expression.
+     *
+     * @param expression The expression you want to unregister
+     */
+    unregisterExpression(expression: VRMExpression): void;
+    /**
+     * Get the current weight of the specified expression.
+     * If it doesn't have an expression of given name, it will return `null` instead.
+     *
+     * @param name Name of the expression
+     */
+    getValue(name: VRMExpressionPresetName | string): number | null;
+    /**
+     * Set a weight to the specified expression.
+     *
+     * @param name Name of the expression
+     * @param weight Weight
+     */
+    setValue(name: VRMExpressionPresetName | string, weight: number): void;
+    /**
+     * Get a track name of specified expression.
+     * This track name is needed to manipulate its expression via keyframe animations.
+     *
+     * @example Manipulate an expression using keyframe animation
+     * ```js
+     * const trackName = vrm.expressionManager.getExpressionTrackName( 'blink' );
+     * const track = new THREE.NumberKeyframeTrack(
+     *   name,
+     *   [ 0.0, 0.5, 1.0 ], // times
+     *   [ 0.0, 1.0, 0.0 ] // values
+     * );
+     *
+     * const clip = new THREE.AnimationClip(
+     *   'blink', // name
+     *   1.0, // duration
+     *   [ track ] // tracks
+     * );
+     *
+     * const mixer = new THREE.AnimationMixer( vrm.scene );
+     * const action = mixer.clipAction( clip );
+     * action.play();
+     * ```
+     *
+     * @param name Name of the expression
+     */
+    getExpressionTrackName(name: VRMExpressionPresetName | string): string | null;
+    /**
+     * Update every expressions.
+     */
+    update(): void;
+    /**
+     * Calculate sum of override amounts to see how much we should multiply weights of certain expressions.
+     */
+    private _calculateWeightMultipliers;
+}

package/ts3.4/types/expressions/VRMExpressionMaterialColorBind.d.ts

@@ -0,0 +1,58 @@
+import * as THREE from 'three';
+import { VRMExpressionBind } from './VRMExpressionBind';
+import { VRMExpressionMaterialColorType } from './VRMExpressionMaterialColorType';
+/**
+ * A bind of expression influences to a material color.
+ */
+export declare class VRMExpressionMaterialColorBind implements VRMExpressionBind {
+    /**
+     * Mapping of property names from VRMC/materialColorBinds.type to three.js/Material.
+     * The first element stands for color channels, the second element stands for the alpha channel.
+     * The second element can be null if the target property doesn't exist.
+     */
+    private static _propertyNameMapMap;
+    /**
+     * The target material.
+     */
+    readonly material: THREE.Material;
+    /**
+     * The type of the target property of the material.
+     */
+    readonly type: VRMExpressionMaterialColorType;
+    /**
+     * The target color.
+     */
+    readonly targetValue: THREE.Color;
+    /**
+     * The target alpha.
+     */
+    readonly targetAlpha: number;
+    /**
+     * Its binding state.
+     * If it cannot find the target property in the constructor, each property will be null instead.
+     */
+    private _state;
+    constructor({ material, type, targetValue, targetAlpha, }: {
+        /**
+         * The target material.
+         */
+        material: THREE.Material;
+        /**
+         * The type of the target property of the material.
+         */
+        type: VRMExpressionMaterialColorType;
+        /**
+         * The target color.
+         */
+        targetValue: THREE.Color;
+        /**
+         * The target alpha.
+         */
+        targetAlpha?: number;
+    });
+    applyWeight(weight: number): void;
+    clearAppliedWeight(): void;
+    private _initColorBindState;
+    private _initAlphaBindState;
+    private _getPropertyNameMap;
+}

package/ts3.4/types/expressions/VRMExpressionMaterialColorType.d.ts

@@ -0,0 +1,12 @@
+export declare const VRMExpressionMaterialColorType: {
+    readonly Color: "color";
+    readonly EmissionColor: "emissionColor";
+    readonly ShadeColor: "shadeColor";
+    readonly MatcapColor: "matcapColor";
+    readonly RimColor: "rimColor";
+    readonly OutlineColor: "outlineColor";
+};
+export type VRMExpressionMaterialColorType = typeof VRMExpressionMaterialColorType[keyof typeof VRMExpressionMaterialColorType];
+export declare const v0ExpressionMaterialColorMap: {
+    [key: string]: VRMExpressionMaterialColorType | undefined;
+};

package/ts3.4/types/expressions/VRMExpressionMorphTargetBind.d.ts

@@ -0,0 +1,35 @@
+import * as THREE from 'three';
+import { VRMExpressionBind } from './VRMExpressionBind';
+/**
+ * A bind of {@link VRMExpression} influences to morph targets.
+ */
+export declare class VRMExpressionMorphTargetBind implements VRMExpressionBind {
+    /**
+     * The mesh primitives that attached to target mesh.
+     */
+    readonly primitives: THREE.Mesh[];
+    /**
+     * The index of the morph target in the mesh.
+     */
+    readonly index: number;
+    /**
+     * The weight value of target morph target. Ranging in [0.0 - 1.0].
+     */
+    readonly weight: number;
+    constructor({ primitives, index, weight, }: {
+        /**
+         * The mesh primitives that attached to target mesh.
+         */
+        primitives: THREE.Mesh[];
+        /**
+         * The index of the morph target in the mesh.
+         */
+        index: number;
+        /**
+         * The weight value of target morph target. Ranging in [0.0 - 1.0].
+         */
+        weight: number;
+    });
+    applyWeight(weight: number): void;
+    clearAppliedWeight(): void;
+}

package/ts3.4/types/expressions/VRMExpressionOverrideType.d.ts

@@ -0,0 +1,6 @@
+export declare const VRMExpressionOverrideType: {
+    readonly None: "none";
+    readonly Block: "block";
+    readonly Blend: "blend";
+};
+export type VRMExpressionOverrideType = typeof VRMExpressionOverrideType[keyof typeof VRMExpressionOverrideType];

package/ts3.4/types/expressions/VRMExpressionPresetName.d.ts

@@ -0,0 +1,21 @@
+export declare const VRMExpressionPresetName: {
+    readonly Aa: "aa";
+    readonly Ih: "ih";
+    readonly Ou: "ou";
+    readonly Ee: "ee";
+    readonly Oh: "oh";
+    readonly Blink: "blink";
+    readonly Happy: "happy";
+    readonly Angry: "angry";
+    readonly Sad: "sad";
+    readonly Relaxed: "relaxed";
+    readonly LookUp: "lookUp";
+    readonly Surprised: "surprised";
+    readonly LookDown: "lookDown";
+    readonly LookLeft: "lookLeft";
+    readonly LookRight: "lookRight";
+    readonly BlinkLeft: "blinkLeft";
+    readonly BlinkRight: "blinkRight";
+    readonly Neutral: "neutral";
+};
+export type VRMExpressionPresetName = typeof VRMExpressionPresetName[keyof typeof VRMExpressionPresetName];

package/ts3.4/types/expressions/VRMExpressionTextureTransformBind.d.ts

@@ -0,0 +1,40 @@
+import * as THREE from 'three';
+import { VRMExpressionBind } from './VRMExpressionBind';
+/**
+ * A bind of expression influences to texture transforms.
+ */
+export declare class VRMExpressionTextureTransformBind implements VRMExpressionBind {
+    private static _propertyNamesMap;
+    /**
+     * The target material.
+     */
+    readonly material: THREE.Material;
+    /**
+     * The uv scale of the texture.
+     */
+    readonly scale: THREE.Vector2;
+    /**
+     * The uv offset of the texture.
+     */
+    readonly offset: THREE.Vector2;
+    /**
+     * The list of texture names and its state that should be transformed by this bind.
+     */
+    private _properties;
+    constructor({ material, scale, offset, }: {
+        /**
+         * The target material.
+         */
+        material: THREE.Material;
+        /**
+         * The uv scale of the texture.
+         */
+        scale: THREE.Vector2;
+        /**
+         * The uv offset of the texture.
+         */
+        offset: THREE.Vector2;
+    });
+    applyWeight(weight: number): void;
+    clearAppliedWeight(): void;
+}

package/ts3.4/types/expressions/index.d.ts

@@ -0,0 +1,10 @@
+export { VRMExpression } from './VRMExpression';
+export { VRMExpressionBind } from './VRMExpressionBind';
+export { VRMExpressionLoaderPlugin } from './VRMExpressionLoaderPlugin';
+export { VRMExpressionManager } from './VRMExpressionManager';
+export { VRMExpressionMaterialColorBind } from './VRMExpressionMaterialColorBind';
+export { VRMExpressionMaterialColorType } from './VRMExpressionMaterialColorType';
+export { VRMExpressionMorphTargetBind } from './VRMExpressionMorphTargetBind';
+export { VRMExpressionOverrideType } from './VRMExpressionOverrideType';
+export { VRMExpressionPresetName } from './VRMExpressionPresetName';
+export { VRMExpressionTextureTransformBind } from './VRMExpressionTextureTransformBind';