feat: Add VRMSpringBoneLimitHinge

The implementation of the hinge limit and its helper

I believe the current `calculateLimit` implementation has the improvement window

TODOs:

- implement polar limit
- implement loader plugin support for the limits

See: vrm-c/vrm-specification#496

Author: 0b5vr

packages/three-vrm-springbone/src/VRMSpringBoneLimitCone.ts

@@ -1,6 +1,9 @@
 import * as THREE from 'three';
 import { VRMSpringBoneLimit } from './VRMSpringBoneLimit';
 
+/**
+ * Represents the cone limit of a spring bone defined in `VRMC_springBone_limit`.
+ */
 export class VRMSpringBoneLimitCone extends VRMSpringBoneLimit {
   /**
    * The angle of the cone limit in radians.

packages/three-vrm-springbone/src/VRMSpringBoneLimitHinge.ts

@@ -0,0 +1,56 @@
+import * as THREE from 'three';
+import { VRMSpringBoneLimit } from './VRMSpringBoneLimit';
+
+/**
+ * Represents the hinge limit of a spring bone defined in `VRMC_springBone_limit`.
+ */
+export class VRMSpringBoneLimitHinge extends VRMSpringBoneLimit {
+  /**
+   * The angle of the hinge limit in radians.
+   * If the angle is set to π or greater, the angle will be interpreted as π by the implementation.
+   * When the angle is set to π, the hinge shape becomes a full disc.
+   */
+  public angle: number;
+
+  public constructor(params?: { angle?: number; rotation?: THREE.Quaternion }) {
+    super();
+
+    this.angle = params?.angle ?? Math.PI;
+    this.rotation = params?.rotation ?? new THREE.Quaternion();
+  }
+
+  public calculateLimit(tailDir: THREE.Vector3): boolean {
+    // bring the direction into the local space of the limit
+    tailDir.applyQuaternion(this._totalRotationInvCache);
+
+    // kill the x component and normalize the direction
+    let isLimited = false;
+    if (tailDir.x !== 0.0) {
+      tailDir.x = 0.0;
+      tailDir.normalize();
+    }
+
+    // calculate the current angle of the tail
+    const dryAngle = Math.acos(tailDir.y);
+
+    if (dryAngle > this.angle) {
+      // now we have to apply the limit
+      isLimited = true;
+
+      // set the y component to the cos of the angle
+      tailDir.y = Math.cos(this.angle);
+
+      // multiply the z component by the ratio of the sins of the angles
+      const ratio = Math.sin(this.angle) / Math.sin(dryAngle);
+      tailDir.z *= ratio;
+
+      // normalize the direction just in case
+      tailDir.normalize();
+    }
+
+    // change the direction back to the world space
+    tailDir.applyQuaternion(this._totalRotationCache);
+
+    return isLimited;
+  }
+}

packages/three-vrm-springbone/src/helpers/VRMSpringBoneLimitHelper.ts

@@ -4,6 +4,8 @@ import { VRMSpringBoneJoint } from '../VRMSpringBoneJoint';
 import { VRMSpringBoneLimitCone } from '../VRMSpringBoneLimitCone';
 import { LimitConeBufferGeometry } from './utils/LimitConeBufferGeometry';
 import { LimitBufferGeometry } from './utils/LimitBufferGeometry';
+import { VRMSpringBoneLimitHinge } from '../VRMSpringBoneLimitHinge';
+import { LimitHingeBufferGeometry } from './utils/LimitHingeBufferGeometry';
 
 const _vec3WorldPosition = /*@__PURE__*/ new THREE.Vector3();
 const _vec3Scale = /*@__PURE__*/ new THREE.Vector3();
@@ -23,6 +25,8 @@ export class VRMSpringBoneLimitHelper extends THREE.Group {
 
     if (this.limit instanceof VRMSpringBoneLimitCone) {
       this._geometry = new LimitConeBufferGeometry(this.limit);
+    } else if (this.limit instanceof VRMSpringBoneLimitHinge) {
+      this._geometry = new LimitHingeBufferGeometry(this.limit);
     } else {
       throw new Error('VRMSpringBoneLimitHelper: Unknown limit type detected');
     }

packages/three-vrm-springbone/src/helpers/utils/LimitHingeBufferGeometry.ts

@@ -0,0 +1,63 @@
+import * as THREE from 'three';
+import { LimitBufferGeometry } from './LimitBufferGeometry';
+import { VRMSpringBoneLimitHinge } from '../../VRMSpringBoneLimitHinge';
+
+const ARC_SEGMENTS = 17;
+
+export class LimitHingeBufferGeometry extends THREE.BufferGeometry implements LimitBufferGeometry {
+  private readonly _attrPos: THREE.BufferAttribute;
+  private readonly _attrIndex: THREE.BufferAttribute;
+  private readonly _limit: VRMSpringBoneLimitHinge;
+  private _currentAngle = 0;
+
+  public constructor(limit: VRMSpringBoneLimitHinge) {
+    super();
+
+    this._limit = limit;
+
+    this._attrPos = new THREE.BufferAttribute(new Float32Array(3 * (ARC_SEGMENTS + 1)), 3);
+    this.setAttribute('position', this._attrPos);
+
+    this._attrIndex = new THREE.BufferAttribute(new Uint16Array(2 * (ARC_SEGMENTS + 1)), 1);
+    this.setIndex(this._attrIndex);
+
+    this._buildIndex();
+    this.update();
+  }
+
+  public update(): void {
+    let shouldUpdateGeometry = false;
+
+    if (this._currentAngle !== this._limit.angle) {
+      this._currentAngle = this._limit.angle;
+      shouldUpdateGeometry = true;
+    }
+
+    if (shouldUpdateGeometry) {
+      this._buildPosition();
+    }
+  }
+
+  private _buildPosition(): void {
+    for (let i = 0; i < ARC_SEGMENTS; i++) {
+      const t = this._currentAngle * (2.0 * (i / (ARC_SEGMENTS - 1)) - 1.0);
+
+      this._attrPos.setXYZ(i, 0, Math.cos(t), Math.sin(t));
+    }
+
+    this._attrPos.setXYZ(ARC_SEGMENTS, 0, 0, 0);
+
+    this._attrPos.needsUpdate = true;
+  }
+
+  private _buildIndex(): void {
+    for (let i = 0; i < ARC_SEGMENTS - 1; i++) {
+      this._attrIndex.setXY(i * 2, i, i + 1);
+    }
+
+    this._attrIndex.setXY(ARC_SEGMENTS * 2 - 2, ARC_SEGMENTS - 1, ARC_SEGMENTS);
+    this._attrIndex.setXY(ARC_SEGMENTS * 2, ARC_SEGMENTS, 0);
+
+    this._attrIndex.needsUpdate = true;
+  }
+}

packages/three-vrm-springbone/src/index.ts

@@ -9,6 +9,7 @@ export * from './VRMSpringBoneJoint';
 export * from './VRMSpringBoneJointSettings';
 export * from './VRMSpringBoneLimit';
 export * from './VRMSpringBoneLimitCone';
+export * from './VRMSpringBoneLimitHinge';
 export * from './VRMSpringBoneLoaderPlugin';
 export * from './VRMSpringBoneLoaderPluginOptions';
 export * from './VRMSpringBoneManager';