@asiyst/sdk 0.1.34 → 0.1.36

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.cts CHANGED
@@ -595,10 +595,20 @@ declare class CustomHostNavigationAdapter implements NavigationAdapter {
595
595
  type CanonicalBoneName = "hips" | "spine" | "chest" | "upperChest" | "neck" | "head" | "leftShoulder" | "leftUpperArm" | "leftLowerArm" | "leftHand" | "rightShoulder" | "rightUpperArm" | "rightLowerArm" | "rightHand" | "leftUpperLeg" | "leftLowerLeg" | "leftFoot" | "leftToes" | "rightUpperLeg" | "rightLowerLeg" | "rightFoot" | "rightToes";
596
596
  declare const CANONICAL_BONE_NAMES: readonly CanonicalBoneName[];
597
597
  type RigType = "mixamo" | "rigify" | "unreal" | "vrm" | "generic_humanoid" | "partial_humanoid" | "unsupported";
598
+ type AnimationSourceMode = "embedded_and_procedural" | "procedural_only" | "embedded_only" | "static";
599
+ interface RigDetectionOptions {
600
+ embeddedAnimationCount?: number;
601
+ }
598
602
  interface AvatarRigCapabilities {
599
603
  readonly rigType: RigType;
604
+ readonly detectedRigFlavor: RigType;
600
605
  readonly isHumanoid: boolean;
606
+ readonly hasSkeleton: boolean;
607
+ readonly hasSkinnedMesh: boolean;
608
+ readonly boneCount: number;
609
+ readonly skinnedMeshCount: number;
601
610
  readonly confidence: number;
611
+ readonly proceduralAnimationAvailable: boolean;
602
612
  readonly proceduralIdle: boolean;
603
613
  readonly proceduralLocomotion: boolean;
604
614
  readonly proceduralRunning: boolean;
@@ -609,7 +619,10 @@ interface AvatarRigCapabilities {
609
619
  readonly headLookAt: boolean;
610
620
  readonly upperBodyGestures: boolean;
611
621
  readonly facialAnimation: boolean;
622
+ readonly hasEmbeddedAnimations: boolean;
623
+ readonly embeddedAnimationCount: number;
612
624
  readonly clipPlayback: boolean;
625
+ readonly animationSourceMode: AnimationSourceMode;
613
626
  readonly missingRequiredBones: CanonicalBoneName[];
614
627
  readonly missingOptionalBones: CanonicalBoneName[];
615
628
  }
@@ -1251,8 +1264,31 @@ declare class AUBRSkeleton {
1251
1264
  readonly proportions: CharacterProportions;
1252
1265
  readonly capabilities: AvatarRigCapabilities;
1253
1266
  readonly modelRoot: THREE.Object3D;
1267
+ /** Conversion factor from physical meters (1.8m humanoid scale) to hips parent local units */
1268
+ readonly hipsLocalPerMeter: number;
1269
+ /** Conversion factor from physical meters (1.8m humanoid scale) to world units */
1270
+ readonly worldUnitsPerMeter: number;
1271
+ /** Detected arm rest angle from vertical down in radians (T-pose ≈ 1.57, A-pose ≈ 0.78, relaxed ≈ 0.25) */
1272
+ readonly leftArmRestAngleFromDown: number;
1273
+ readonly rightArmRestAngleFromDown: number;
1274
+ /** Sign around model +Z axis to lower each arm toward -Y (-1 for +X arm, +1 for -X arm) */
1275
+ readonly leftArmLowerSign: number;
1276
+ readonly rightArmLowerSign: number;
1277
+ /** Rest foot positions in modelRoot local space */
1278
+ readonly restLeftFootModelPos: THREE.Vector3;
1279
+ readonly restRightFootModelPos: THREE.Vector3;
1280
+ readonly hasRestFootPositions: boolean;
1254
1281
  private readonly boneToCanonical;
1255
- constructor(modelRoot: THREE.Object3D);
1282
+ private readonly restModelQuat;
1283
+ private readonly restModelQuatInv;
1284
+ constructor(modelRoot: THREE.Object3D, options?: RigDetectionOptions);
1285
+ private measureArmRest;
1286
+ /**
1287
+ * Applies a rotation delta defined in character model space (+Y up, +Z forward, +X right/left)
1288
+ * relative to the joint's rest pose, converted cleanly into the bone's local coordinate frame.
1289
+ * Allocation-free and rig-agnostic across Mixamo, Rigify, Unreal, VRM, and generic humanoids.
1290
+ */
1291
+ applyModelDeltaRotation(name: CanonicalBoneName, modelDeltaQuat: THREE.Quaternion, weight?: number, additive?: boolean): void;
1256
1292
  getJoint(name: CanonicalBoneName): AUBRJoint | undefined;
1257
1293
  getBone(name: CanonicalBoneName): THREE.Bone | undefined;
1258
1294
  hasJoint(name: CanonicalBoneName): boolean;
@@ -1287,10 +1323,12 @@ declare class IKCoordinator {
1287
1323
  private initChains;
1288
1324
  /**
1289
1325
  * Solves and applies left leg Two-Bone IK.
1326
+ * `targetFootPosModel` is in `skeleton.modelRoot` local space.
1290
1327
  */
1291
1328
  solveLeftLeg(targetFootPosModel: THREE.Vector3, weight?: number): void;
1292
1329
  /**
1293
1330
  * Solves and applies right leg Two-Bone IK.
1331
+ * `targetFootPosModel` is in `skeleton.modelRoot` local space.
1294
1332
  */
1295
1333
  solveRightLeg(targetFootPosModel: THREE.Vector3, weight?: number): void;
1296
1334
  /**
@@ -1308,6 +1346,7 @@ declare class IdleEngine {
1308
1346
  private targetWeightShift;
1309
1347
  private nextWeightShiftTime;
1310
1348
  constructor(skeleton: AUBRSkeleton);
1349
+ reset(): void;
1311
1350
  update(delta: number, weight?: number): void;
1312
1351
  }
1313
1352
 
@@ -1339,22 +1378,31 @@ declare class LocomotionEngine {
1339
1378
  private calibrateStride;
1340
1379
  setMotion(params: LocomotionParams): void;
1341
1380
  stop(): void;
1381
+ cancel(): void;
1342
1382
  update(delta: number, weight?: number): void;
1343
1383
  getPhase(): number;
1344
1384
  getSpeed(): number;
1345
1385
  }
1346
1386
 
1387
+ type FacingDirection = "left" | "right" | "center" | "forward" | "front";
1347
1388
  declare class TurnEngine {
1348
1389
  private readonly skeleton;
1349
1390
  private currentYaw;
1350
1391
  private targetYaw;
1351
1392
  private isTurning;
1352
1393
  private turnAngularVelocity;
1353
- constructor(skeleton: AUBRSkeleton);
1394
+ private readonly turnTarget;
1395
+ private readonly baseYaw;
1396
+ constructor(skeleton: AUBRSkeleton, turnTarget?: THREE.Object3D);
1354
1397
  setTargetHeading(targetYawRad: number): void;
1355
- setFacingDirection(direction: "left" | "right" | "center" | "forward"): void;
1398
+ turnLeft(stepRad?: number): void;
1399
+ turnRight(stepRad?: number): void;
1400
+ setFacingDirection(direction: FacingDirection): void;
1401
+ reset(): void;
1356
1402
  update(delta: number, isLocomoting?: boolean): void;
1357
1403
  getYaw(): number;
1404
+ getTargetYaw(): number;
1405
+ getAngularVelocity(): number;
1358
1406
  isTurnActive(): boolean;
1359
1407
  }
1360
1408
 
@@ -1411,6 +1459,10 @@ declare class GestureEngine {
1411
1459
  update(delta: number): void;
1412
1460
  private getDefaultDuration;
1413
1461
  private determineHand;
1462
+ /**
1463
+ * Helper: rotates an upper arm from its rest orientation to a target standing-relative Euler pose in model space.
1464
+ */
1465
+ private applyStandingArmDelta;
1414
1466
  private synthesizeWave;
1415
1467
  private synthesizePoint;
1416
1468
  private synthesizeAgree;
@@ -1501,6 +1553,10 @@ declare class MotionCoordinator {
1501
1553
  blendLayers(hasActiveClip: boolean): void;
1502
1554
  }
1503
1555
 
1556
+ interface ProceduralMovementEngineOptions extends RigDetectionOptions {
1557
+ /** Optional outer Object3D (e.g. centered wrapper group) to apply yaw turning to */
1558
+ turnTarget?: THREE.Object3D;
1559
+ }
1504
1560
  declare class ProceduralMovementEngine {
1505
1561
  readonly skeleton: AUBRSkeleton;
1506
1562
  readonly ik: IKCoordinator;
@@ -1514,17 +1570,31 @@ declare class ProceduralMovementEngine {
1514
1570
  readonly stateMachine: MotionStateMachine;
1515
1571
  readonly coordinator: MotionCoordinator;
1516
1572
  private isEnabled;
1517
- private stopTimer?;
1518
- constructor(modelRoot: THREE.Object3D);
1573
+ private paused;
1574
+ private locomotionBlendWeight;
1575
+ private startingTimer;
1576
+ private readonly balanceReachScratch;
1577
+ constructor(modelRoot: THREE.Object3D, options?: ProceduralMovementEngineOptions);
1519
1578
  getCapabilities(): AvatarRigCapabilities;
1579
+ getState(): MotionState;
1520
1580
  setEnabled(enabled: boolean): void;
1581
+ pause(): void;
1582
+ resume(): void;
1583
+ isPaused(): boolean;
1584
+ resetToRestPose(): void;
1585
+ startIdle(): void;
1586
+ startWalking(speed?: number, screenVelocityPx?: number): void;
1521
1587
  walk(speed?: number, screenVelocityPx?: number): void;
1522
1588
  run(speed?: number, screenVelocityPx?: number): void;
1589
+ stop(): void;
1523
1590
  stopLocomotion(): void;
1524
- dispose(): void;
1525
- private clearStopTimer;
1526
- setFacing(direction: "left" | "right" | "center" | "forward"): void;
1591
+ cancelLocomotion(): void;
1592
+ turnLeft(stepRad?: number): void;
1593
+ turnRight(stepRad?: number): void;
1594
+ turnTo(directionOrYaw: FacingDirection | number): void;
1595
+ setFacing(direction: FacingDirection): void;
1527
1596
  setTargetHeading(yawRad: number): void;
1597
+ dispose(): void;
1528
1598
  playGesture(type: GestureType, options?: {
1529
1599
  duration?: number;
1530
1600
  targetWorldPos?: THREE.Vector3;
@@ -1542,9 +1612,9 @@ declare class ProceduralMovementEngine {
1542
1612
  preMixerUpdate(): void;
1543
1613
  /**
1544
1614
  * Main procedural pipeline tick.
1545
- * Invoked in FbxRenderer.startLoop() after mixer.update(delta) and before renderer.render().
1615
+ * Invoked in FbxRenderer.startLoop() or Avatar Studio after mixer.update(delta) and before renderer.render().
1546
1616
  */
1547
- update(delta: number, hasActiveMixerClip: boolean): void;
1617
+ update(delta: number, hasActiveMixerClip?: boolean): void;
1548
1618
  }
1549
1619
 
1550
1620
  interface FbxRenderMetrics {
@@ -2132,9 +2202,14 @@ declare class TwoBoneIK {
2132
2202
  static solve(chainOrRoot: TwoBoneIKChain | THREE.Bone, targetOrMid: THREE.Vector3 | THREE.Bone, rootPosOrTip?: THREE.Vector3 | THREE.Bone, poleVectorOrTarget?: THREE.Vector3, optionsOrPole?: TwoBoneIKOptions | THREE.Vector3, extraOptions?: TwoBoneIKOptions): any;
2133
2203
  private static solveAnalytical;
2134
2204
  /**
2135
- * Applies solved two-bone IK rotations to the target AUBR joints in-place.
2205
+ * Applies solved two-bone IK rotations to the target AUBR leg joints in-place
2206
+ * using rest-pose-preserving world-space delta rotations so Mixamo, Rigify, Unreal,
2207
+ * VRM, and generic humanoid bone orientations are never distorted.
2208
+ *
2209
+ * `targetFootPosWorld` and `poleDirWorld` are in world space (or model space when
2210
+ * `modelRoot` is omitted and bones are evaluated in local space).
2136
2211
  */
2137
- static applyLegIK(thighBone: THREE.Bone, shinBone: THREE.Bone, footBone: THREE.Bone, thighLength: number, shinLength: number, targetFootPosModel: THREE.Vector3, poleVector: THREE.Vector3, weight?: number, modelRoot?: THREE.Object3D): void;
2212
+ static applyLegIK(thighBone: THREE.Bone, shinBone: THREE.Bone, footBone: THREE.Bone, thighLength: number, shinLength: number, targetFootPosWorld: THREE.Vector3, poleDirWorld: THREE.Vector3, weight?: number, _modelRoot?: THREE.Object3D): void;
2138
2213
  }
2139
2214
 
2140
2215
  interface FABRIKChain {
@@ -2196,11 +2271,13 @@ declare class FABRIKSolver {
2196
2271
  */
2197
2272
  static solve(chain: FABRIKChain, targetPos: THREE.Vector3, poleVector?: THREE.Vector3, options?: FABRIKSolverOptions): FABRIKSolveResult;
2198
2273
  /**
2199
- * Projects middle hinge joint onto plane defined by pole vector.
2274
+ * Projects middle hinge joint onto the half-plane defined by the pole direction vector.
2200
2275
  */
2201
2276
  private static applyPoleVector;
2202
2277
  /**
2203
2278
  * Converts solved world positions back into local bone rotations for the Three.js hierarchy.
2279
+ * Calculates delta rotation in world space from current bone direction to solved target direction,
2280
+ * transforming into local bone space to guarantee zero deformation when positions match rest pose.
2204
2281
  */
2205
2282
  static applyPositionsToBones(chain: FABRIKChain, solvedPositions: THREE.Vector3[], weight?: number): void;
2206
2283
  }
@@ -2218,18 +2295,18 @@ declare class RigDetector {
2218
2295
  */
2219
2296
  static cleanBoneName(rawName: string): string;
2220
2297
  /**
2221
- * Analyzes an imported 3D model root, identifies all bones, maps them to canonical AUBR,
2222
- * validates hierarchy, and reports capability profile.
2298
+ * Analyzes an imported 3D model root, identifies all bones and skinned meshes,
2299
+ * maps them to canonical AUBR, validates hierarchy, and reports capability profile.
2223
2300
  */
2224
- static detect(modelRoot: THREE.Object3D): RigDetectionResult;
2301
+ static detect(modelRoot: THREE.Object3D, options?: RigDetectionOptions): RigDetectionResult;
2225
2302
  /**
2226
2303
  * Alias for detect()
2227
2304
  */
2228
- static detectRig(modelRoot: THREE.Object3D): RigDetectionResult;
2305
+ static detectRig(modelRoot: THREE.Object3D, options?: RigDetectionOptions): RigDetectionResult;
2229
2306
  /**
2230
2307
  * Assesses avatar rig capabilities from detection result or model.
2231
2308
  */
2232
- static assessCapabilities(detection: RigDetectionResult, modelRoot?: THREE.Object3D): AvatarRigCapabilities;
2309
+ static assessCapabilities(detection: RigDetectionResult, modelRoot?: THREE.Object3D, options?: RigDetectionOptions): AvatarRigCapabilities;
2233
2310
  private static identifyRigFlavor;
2234
2311
  private static findBestBoneMatch;
2235
2312
  private static validateHierarchyConstraints;
@@ -2238,4 +2315,4 @@ declare class RigDetector {
2238
2315
  private static createUnsupportedCapabilities;
2239
2316
  }
2240
2317
 
2241
- export { ACTION_RISK_MAP, ACTION_STATUSES, type AUBRJoint, AUBRSkeleton, AVATAR_ACTION_PROTOCOL_VERSION, AVATAR_ACTION_TYPES, type ActionExecutionContext, type ActionHandler, type ActionKind, ActionNotAllowedError, type ActionRiskLevel, ActionScheduler, type AnimationCategory, type AppRouterLike, Asiyst, type AsiystClientInstance, type AsiystDiagnosticReport, AsiystError, type AsiystErrorCode, type AsiystEventMap, type AsiystEventName, type AsiystFallbackOptions, type AsiystInstance, type AsiystProgress, type AsiystSDKState, AssetLoader, type AssistantMode, AuthenticationError, type AvatarActionItem, type AvatarActionPlan, type AvatarActionStatus, type AvatarActionType, type AvatarAnimation, type AvatarBranding, AvatarController, type AvatarLifecycleState, type AvatarLoadingTimestamps, AvatarMetricsTracker, type AvatarPerformanceMetrics, type AvatarPose, type AvatarRenderer, type AvatarRigCapabilities, type AvatarRuntimeConfig, BalanceEngine, CANONICAL_BONE_NAMES, type CanonicalBoneName, type CharacterProportions, type ChatLifecycleState, ConfigurationError, ConfirmationManager, type ConfirmationRequestDetails, CssAvatarRenderer, CustomHostNavigationAdapter, DefaultBrowserNavigationAdapter, type DiagnosticResult, type ExpressionType, FABRIKSolver, FacialAnimationEngine, type FbxMountOptions, type FbxRenderMetrics, FbxRenderer, GestureEngine, type GestureType, GreetingManager, type HighlightStyle, IdleEngine, type InitOptions, InitializationError, LocomotionEngine, LookAtEngine, type MappedElement, MotionCoordinator, type MotionLayerWeights, type MotionState, MotionStateMachine, MovementEngine, type NavigationAdapter, NetworkError, NextJsAppRouterNavigationAdapter, NextJsPagesNavigationAdapter, ProceduralMovementEngine, type ProjectConfig, type RegisteredTarget, RigDetector, type RigType, RuntimeEventReporter, type RuntimeLifecycleState, SDK_VERSION, type SpeechOptions, SpeechPlayer, type TargetInput, TargetNotFoundError, type TargetRef, TargetRegistry, type TaskDefinition, TaskExecutionError, TaskStatus, type TaskStep, type TourDefinition, TourEngine, type TourEngineOptions, type TourStatus, type TourStep, type TourStepChangeEvent, TurnEngine, TwoBoneIK, type WebsiteMapSnapshot, type WorkflowDefinition, anchorToViewport, asiystInit, canNavigateTo, canTransition, computeAvatarDestination, createAsiystInstance, createNextAppRouterAdapter, evaluateActionPermission, fallbackConfig, isActionAllowed, isSafeSelector, isSensitiveTarget, normalizeProjectConfig, sanitizeText, setGlobalNavigationAdapter, validateActionDependencies, validateActionItem, validateActionPlan, validateInitOptions, validateWebsiteDomain };
2318
+ export { ACTION_RISK_MAP, ACTION_STATUSES, type AUBRJoint, AUBRSkeleton, AVATAR_ACTION_PROTOCOL_VERSION, AVATAR_ACTION_TYPES, type ActionExecutionContext, type ActionHandler, type ActionKind, ActionNotAllowedError, type ActionRiskLevel, ActionScheduler, type AnimationCategory, type AnimationSourceMode, type AppRouterLike, Asiyst, type AsiystClientInstance, type AsiystDiagnosticReport, AsiystError, type AsiystErrorCode, type AsiystEventMap, type AsiystEventName, type AsiystFallbackOptions, type AsiystInstance, type AsiystProgress, type AsiystSDKState, AssetLoader, type AssistantMode, AuthenticationError, type AvatarActionItem, type AvatarActionPlan, type AvatarActionStatus, type AvatarActionType, type AvatarAnimation, type AvatarBranding, AvatarController, type AvatarLifecycleState, type AvatarLoadingTimestamps, AvatarMetricsTracker, type AvatarPerformanceMetrics, type AvatarPose, type AvatarRenderer, type AvatarRigCapabilities, type AvatarRuntimeConfig, BalanceEngine, CANONICAL_BONE_NAMES, type CanonicalBoneName, type CharacterProportions, type ChatLifecycleState, ConfigurationError, ConfirmationManager, type ConfirmationRequestDetails, CssAvatarRenderer, CustomHostNavigationAdapter, DefaultBrowserNavigationAdapter, type DiagnosticResult, type ExpressionType, FABRIKSolver, FacialAnimationEngine, type FacingDirection, type FbxMountOptions, type FbxRenderMetrics, FbxRenderer, GestureEngine, type GestureType, GreetingManager, type HighlightStyle, IdleEngine, type InitOptions, InitializationError, LocomotionEngine, LookAtEngine, type MappedElement, MotionCoordinator, type MotionLayerWeights, type MotionState, MotionStateMachine, MovementEngine, type NavigationAdapter, NetworkError, NextJsAppRouterNavigationAdapter, NextJsPagesNavigationAdapter, ProceduralMovementEngine, type ProceduralMovementEngineOptions, type ProjectConfig, type RegisteredTarget, type RigDetectionOptions, type RigDetectionResult, RigDetector, type RigType, RuntimeEventReporter, type RuntimeLifecycleState, SDK_VERSION, type SpeechOptions, SpeechPlayer, type TargetInput, TargetNotFoundError, type TargetRef, TargetRegistry, type TaskDefinition, TaskExecutionError, TaskStatus, type TaskStep, type TourDefinition, TourEngine, type TourEngineOptions, type TourStatus, type TourStep, type TourStepChangeEvent, TurnEngine, TwoBoneIK, type WebsiteMapSnapshot, type WorkflowDefinition, anchorToViewport, asiystInit, canNavigateTo, canTransition, computeAvatarDestination, createAsiystInstance, createNextAppRouterAdapter, evaluateActionPermission, fallbackConfig, isActionAllowed, isSafeSelector, isSensitiveTarget, normalizeProjectConfig, sanitizeText, setGlobalNavigationAdapter, validateActionDependencies, validateActionItem, validateActionPlan, validateInitOptions, validateWebsiteDomain };
package/dist/index.d.ts CHANGED
@@ -595,10 +595,20 @@ declare class CustomHostNavigationAdapter implements NavigationAdapter {
595
595
  type CanonicalBoneName = "hips" | "spine" | "chest" | "upperChest" | "neck" | "head" | "leftShoulder" | "leftUpperArm" | "leftLowerArm" | "leftHand" | "rightShoulder" | "rightUpperArm" | "rightLowerArm" | "rightHand" | "leftUpperLeg" | "leftLowerLeg" | "leftFoot" | "leftToes" | "rightUpperLeg" | "rightLowerLeg" | "rightFoot" | "rightToes";
596
596
  declare const CANONICAL_BONE_NAMES: readonly CanonicalBoneName[];
597
597
  type RigType = "mixamo" | "rigify" | "unreal" | "vrm" | "generic_humanoid" | "partial_humanoid" | "unsupported";
598
+ type AnimationSourceMode = "embedded_and_procedural" | "procedural_only" | "embedded_only" | "static";
599
+ interface RigDetectionOptions {
600
+ embeddedAnimationCount?: number;
601
+ }
598
602
  interface AvatarRigCapabilities {
599
603
  readonly rigType: RigType;
604
+ readonly detectedRigFlavor: RigType;
600
605
  readonly isHumanoid: boolean;
606
+ readonly hasSkeleton: boolean;
607
+ readonly hasSkinnedMesh: boolean;
608
+ readonly boneCount: number;
609
+ readonly skinnedMeshCount: number;
601
610
  readonly confidence: number;
611
+ readonly proceduralAnimationAvailable: boolean;
602
612
  readonly proceduralIdle: boolean;
603
613
  readonly proceduralLocomotion: boolean;
604
614
  readonly proceduralRunning: boolean;
@@ -609,7 +619,10 @@ interface AvatarRigCapabilities {
609
619
  readonly headLookAt: boolean;
610
620
  readonly upperBodyGestures: boolean;
611
621
  readonly facialAnimation: boolean;
622
+ readonly hasEmbeddedAnimations: boolean;
623
+ readonly embeddedAnimationCount: number;
612
624
  readonly clipPlayback: boolean;
625
+ readonly animationSourceMode: AnimationSourceMode;
613
626
  readonly missingRequiredBones: CanonicalBoneName[];
614
627
  readonly missingOptionalBones: CanonicalBoneName[];
615
628
  }
@@ -1251,8 +1264,31 @@ declare class AUBRSkeleton {
1251
1264
  readonly proportions: CharacterProportions;
1252
1265
  readonly capabilities: AvatarRigCapabilities;
1253
1266
  readonly modelRoot: THREE.Object3D;
1267
+ /** Conversion factor from physical meters (1.8m humanoid scale) to hips parent local units */
1268
+ readonly hipsLocalPerMeter: number;
1269
+ /** Conversion factor from physical meters (1.8m humanoid scale) to world units */
1270
+ readonly worldUnitsPerMeter: number;
1271
+ /** Detected arm rest angle from vertical down in radians (T-pose ≈ 1.57, A-pose ≈ 0.78, relaxed ≈ 0.25) */
1272
+ readonly leftArmRestAngleFromDown: number;
1273
+ readonly rightArmRestAngleFromDown: number;
1274
+ /** Sign around model +Z axis to lower each arm toward -Y (-1 for +X arm, +1 for -X arm) */
1275
+ readonly leftArmLowerSign: number;
1276
+ readonly rightArmLowerSign: number;
1277
+ /** Rest foot positions in modelRoot local space */
1278
+ readonly restLeftFootModelPos: THREE.Vector3;
1279
+ readonly restRightFootModelPos: THREE.Vector3;
1280
+ readonly hasRestFootPositions: boolean;
1254
1281
  private readonly boneToCanonical;
1255
- constructor(modelRoot: THREE.Object3D);
1282
+ private readonly restModelQuat;
1283
+ private readonly restModelQuatInv;
1284
+ constructor(modelRoot: THREE.Object3D, options?: RigDetectionOptions);
1285
+ private measureArmRest;
1286
+ /**
1287
+ * Applies a rotation delta defined in character model space (+Y up, +Z forward, +X right/left)
1288
+ * relative to the joint's rest pose, converted cleanly into the bone's local coordinate frame.
1289
+ * Allocation-free and rig-agnostic across Mixamo, Rigify, Unreal, VRM, and generic humanoids.
1290
+ */
1291
+ applyModelDeltaRotation(name: CanonicalBoneName, modelDeltaQuat: THREE.Quaternion, weight?: number, additive?: boolean): void;
1256
1292
  getJoint(name: CanonicalBoneName): AUBRJoint | undefined;
1257
1293
  getBone(name: CanonicalBoneName): THREE.Bone | undefined;
1258
1294
  hasJoint(name: CanonicalBoneName): boolean;
@@ -1287,10 +1323,12 @@ declare class IKCoordinator {
1287
1323
  private initChains;
1288
1324
  /**
1289
1325
  * Solves and applies left leg Two-Bone IK.
1326
+ * `targetFootPosModel` is in `skeleton.modelRoot` local space.
1290
1327
  */
1291
1328
  solveLeftLeg(targetFootPosModel: THREE.Vector3, weight?: number): void;
1292
1329
  /**
1293
1330
  * Solves and applies right leg Two-Bone IK.
1331
+ * `targetFootPosModel` is in `skeleton.modelRoot` local space.
1294
1332
  */
1295
1333
  solveRightLeg(targetFootPosModel: THREE.Vector3, weight?: number): void;
1296
1334
  /**
@@ -1308,6 +1346,7 @@ declare class IdleEngine {
1308
1346
  private targetWeightShift;
1309
1347
  private nextWeightShiftTime;
1310
1348
  constructor(skeleton: AUBRSkeleton);
1349
+ reset(): void;
1311
1350
  update(delta: number, weight?: number): void;
1312
1351
  }
1313
1352
 
@@ -1339,22 +1378,31 @@ declare class LocomotionEngine {
1339
1378
  private calibrateStride;
1340
1379
  setMotion(params: LocomotionParams): void;
1341
1380
  stop(): void;
1381
+ cancel(): void;
1342
1382
  update(delta: number, weight?: number): void;
1343
1383
  getPhase(): number;
1344
1384
  getSpeed(): number;
1345
1385
  }
1346
1386
 
1387
+ type FacingDirection = "left" | "right" | "center" | "forward" | "front";
1347
1388
  declare class TurnEngine {
1348
1389
  private readonly skeleton;
1349
1390
  private currentYaw;
1350
1391
  private targetYaw;
1351
1392
  private isTurning;
1352
1393
  private turnAngularVelocity;
1353
- constructor(skeleton: AUBRSkeleton);
1394
+ private readonly turnTarget;
1395
+ private readonly baseYaw;
1396
+ constructor(skeleton: AUBRSkeleton, turnTarget?: THREE.Object3D);
1354
1397
  setTargetHeading(targetYawRad: number): void;
1355
- setFacingDirection(direction: "left" | "right" | "center" | "forward"): void;
1398
+ turnLeft(stepRad?: number): void;
1399
+ turnRight(stepRad?: number): void;
1400
+ setFacingDirection(direction: FacingDirection): void;
1401
+ reset(): void;
1356
1402
  update(delta: number, isLocomoting?: boolean): void;
1357
1403
  getYaw(): number;
1404
+ getTargetYaw(): number;
1405
+ getAngularVelocity(): number;
1358
1406
  isTurnActive(): boolean;
1359
1407
  }
1360
1408
 
@@ -1411,6 +1459,10 @@ declare class GestureEngine {
1411
1459
  update(delta: number): void;
1412
1460
  private getDefaultDuration;
1413
1461
  private determineHand;
1462
+ /**
1463
+ * Helper: rotates an upper arm from its rest orientation to a target standing-relative Euler pose in model space.
1464
+ */
1465
+ private applyStandingArmDelta;
1414
1466
  private synthesizeWave;
1415
1467
  private synthesizePoint;
1416
1468
  private synthesizeAgree;
@@ -1501,6 +1553,10 @@ declare class MotionCoordinator {
1501
1553
  blendLayers(hasActiveClip: boolean): void;
1502
1554
  }
1503
1555
 
1556
+ interface ProceduralMovementEngineOptions extends RigDetectionOptions {
1557
+ /** Optional outer Object3D (e.g. centered wrapper group) to apply yaw turning to */
1558
+ turnTarget?: THREE.Object3D;
1559
+ }
1504
1560
  declare class ProceduralMovementEngine {
1505
1561
  readonly skeleton: AUBRSkeleton;
1506
1562
  readonly ik: IKCoordinator;
@@ -1514,17 +1570,31 @@ declare class ProceduralMovementEngine {
1514
1570
  readonly stateMachine: MotionStateMachine;
1515
1571
  readonly coordinator: MotionCoordinator;
1516
1572
  private isEnabled;
1517
- private stopTimer?;
1518
- constructor(modelRoot: THREE.Object3D);
1573
+ private paused;
1574
+ private locomotionBlendWeight;
1575
+ private startingTimer;
1576
+ private readonly balanceReachScratch;
1577
+ constructor(modelRoot: THREE.Object3D, options?: ProceduralMovementEngineOptions);
1519
1578
  getCapabilities(): AvatarRigCapabilities;
1579
+ getState(): MotionState;
1520
1580
  setEnabled(enabled: boolean): void;
1581
+ pause(): void;
1582
+ resume(): void;
1583
+ isPaused(): boolean;
1584
+ resetToRestPose(): void;
1585
+ startIdle(): void;
1586
+ startWalking(speed?: number, screenVelocityPx?: number): void;
1521
1587
  walk(speed?: number, screenVelocityPx?: number): void;
1522
1588
  run(speed?: number, screenVelocityPx?: number): void;
1589
+ stop(): void;
1523
1590
  stopLocomotion(): void;
1524
- dispose(): void;
1525
- private clearStopTimer;
1526
- setFacing(direction: "left" | "right" | "center" | "forward"): void;
1591
+ cancelLocomotion(): void;
1592
+ turnLeft(stepRad?: number): void;
1593
+ turnRight(stepRad?: number): void;
1594
+ turnTo(directionOrYaw: FacingDirection | number): void;
1595
+ setFacing(direction: FacingDirection): void;
1527
1596
  setTargetHeading(yawRad: number): void;
1597
+ dispose(): void;
1528
1598
  playGesture(type: GestureType, options?: {
1529
1599
  duration?: number;
1530
1600
  targetWorldPos?: THREE.Vector3;
@@ -1542,9 +1612,9 @@ declare class ProceduralMovementEngine {
1542
1612
  preMixerUpdate(): void;
1543
1613
  /**
1544
1614
  * Main procedural pipeline tick.
1545
- * Invoked in FbxRenderer.startLoop() after mixer.update(delta) and before renderer.render().
1615
+ * Invoked in FbxRenderer.startLoop() or Avatar Studio after mixer.update(delta) and before renderer.render().
1546
1616
  */
1547
- update(delta: number, hasActiveMixerClip: boolean): void;
1617
+ update(delta: number, hasActiveMixerClip?: boolean): void;
1548
1618
  }
1549
1619
 
1550
1620
  interface FbxRenderMetrics {
@@ -2132,9 +2202,14 @@ declare class TwoBoneIK {
2132
2202
  static solve(chainOrRoot: TwoBoneIKChain | THREE.Bone, targetOrMid: THREE.Vector3 | THREE.Bone, rootPosOrTip?: THREE.Vector3 | THREE.Bone, poleVectorOrTarget?: THREE.Vector3, optionsOrPole?: TwoBoneIKOptions | THREE.Vector3, extraOptions?: TwoBoneIKOptions): any;
2133
2203
  private static solveAnalytical;
2134
2204
  /**
2135
- * Applies solved two-bone IK rotations to the target AUBR joints in-place.
2205
+ * Applies solved two-bone IK rotations to the target AUBR leg joints in-place
2206
+ * using rest-pose-preserving world-space delta rotations so Mixamo, Rigify, Unreal,
2207
+ * VRM, and generic humanoid bone orientations are never distorted.
2208
+ *
2209
+ * `targetFootPosWorld` and `poleDirWorld` are in world space (or model space when
2210
+ * `modelRoot` is omitted and bones are evaluated in local space).
2136
2211
  */
2137
- static applyLegIK(thighBone: THREE.Bone, shinBone: THREE.Bone, footBone: THREE.Bone, thighLength: number, shinLength: number, targetFootPosModel: THREE.Vector3, poleVector: THREE.Vector3, weight?: number, modelRoot?: THREE.Object3D): void;
2212
+ static applyLegIK(thighBone: THREE.Bone, shinBone: THREE.Bone, footBone: THREE.Bone, thighLength: number, shinLength: number, targetFootPosWorld: THREE.Vector3, poleDirWorld: THREE.Vector3, weight?: number, _modelRoot?: THREE.Object3D): void;
2138
2213
  }
2139
2214
 
2140
2215
  interface FABRIKChain {
@@ -2196,11 +2271,13 @@ declare class FABRIKSolver {
2196
2271
  */
2197
2272
  static solve(chain: FABRIKChain, targetPos: THREE.Vector3, poleVector?: THREE.Vector3, options?: FABRIKSolverOptions): FABRIKSolveResult;
2198
2273
  /**
2199
- * Projects middle hinge joint onto plane defined by pole vector.
2274
+ * Projects middle hinge joint onto the half-plane defined by the pole direction vector.
2200
2275
  */
2201
2276
  private static applyPoleVector;
2202
2277
  /**
2203
2278
  * Converts solved world positions back into local bone rotations for the Three.js hierarchy.
2279
+ * Calculates delta rotation in world space from current bone direction to solved target direction,
2280
+ * transforming into local bone space to guarantee zero deformation when positions match rest pose.
2204
2281
  */
2205
2282
  static applyPositionsToBones(chain: FABRIKChain, solvedPositions: THREE.Vector3[], weight?: number): void;
2206
2283
  }
@@ -2218,18 +2295,18 @@ declare class RigDetector {
2218
2295
  */
2219
2296
  static cleanBoneName(rawName: string): string;
2220
2297
  /**
2221
- * Analyzes an imported 3D model root, identifies all bones, maps them to canonical AUBR,
2222
- * validates hierarchy, and reports capability profile.
2298
+ * Analyzes an imported 3D model root, identifies all bones and skinned meshes,
2299
+ * maps them to canonical AUBR, validates hierarchy, and reports capability profile.
2223
2300
  */
2224
- static detect(modelRoot: THREE.Object3D): RigDetectionResult;
2301
+ static detect(modelRoot: THREE.Object3D, options?: RigDetectionOptions): RigDetectionResult;
2225
2302
  /**
2226
2303
  * Alias for detect()
2227
2304
  */
2228
- static detectRig(modelRoot: THREE.Object3D): RigDetectionResult;
2305
+ static detectRig(modelRoot: THREE.Object3D, options?: RigDetectionOptions): RigDetectionResult;
2229
2306
  /**
2230
2307
  * Assesses avatar rig capabilities from detection result or model.
2231
2308
  */
2232
- static assessCapabilities(detection: RigDetectionResult, modelRoot?: THREE.Object3D): AvatarRigCapabilities;
2309
+ static assessCapabilities(detection: RigDetectionResult, modelRoot?: THREE.Object3D, options?: RigDetectionOptions): AvatarRigCapabilities;
2233
2310
  private static identifyRigFlavor;
2234
2311
  private static findBestBoneMatch;
2235
2312
  private static validateHierarchyConstraints;
@@ -2238,4 +2315,4 @@ declare class RigDetector {
2238
2315
  private static createUnsupportedCapabilities;
2239
2316
  }
2240
2317
 
2241
- export { ACTION_RISK_MAP, ACTION_STATUSES, type AUBRJoint, AUBRSkeleton, AVATAR_ACTION_PROTOCOL_VERSION, AVATAR_ACTION_TYPES, type ActionExecutionContext, type ActionHandler, type ActionKind, ActionNotAllowedError, type ActionRiskLevel, ActionScheduler, type AnimationCategory, type AppRouterLike, Asiyst, type AsiystClientInstance, type AsiystDiagnosticReport, AsiystError, type AsiystErrorCode, type AsiystEventMap, type AsiystEventName, type AsiystFallbackOptions, type AsiystInstance, type AsiystProgress, type AsiystSDKState, AssetLoader, type AssistantMode, AuthenticationError, type AvatarActionItem, type AvatarActionPlan, type AvatarActionStatus, type AvatarActionType, type AvatarAnimation, type AvatarBranding, AvatarController, type AvatarLifecycleState, type AvatarLoadingTimestamps, AvatarMetricsTracker, type AvatarPerformanceMetrics, type AvatarPose, type AvatarRenderer, type AvatarRigCapabilities, type AvatarRuntimeConfig, BalanceEngine, CANONICAL_BONE_NAMES, type CanonicalBoneName, type CharacterProportions, type ChatLifecycleState, ConfigurationError, ConfirmationManager, type ConfirmationRequestDetails, CssAvatarRenderer, CustomHostNavigationAdapter, DefaultBrowserNavigationAdapter, type DiagnosticResult, type ExpressionType, FABRIKSolver, FacialAnimationEngine, type FbxMountOptions, type FbxRenderMetrics, FbxRenderer, GestureEngine, type GestureType, GreetingManager, type HighlightStyle, IdleEngine, type InitOptions, InitializationError, LocomotionEngine, LookAtEngine, type MappedElement, MotionCoordinator, type MotionLayerWeights, type MotionState, MotionStateMachine, MovementEngine, type NavigationAdapter, NetworkError, NextJsAppRouterNavigationAdapter, NextJsPagesNavigationAdapter, ProceduralMovementEngine, type ProjectConfig, type RegisteredTarget, RigDetector, type RigType, RuntimeEventReporter, type RuntimeLifecycleState, SDK_VERSION, type SpeechOptions, SpeechPlayer, type TargetInput, TargetNotFoundError, type TargetRef, TargetRegistry, type TaskDefinition, TaskExecutionError, TaskStatus, type TaskStep, type TourDefinition, TourEngine, type TourEngineOptions, type TourStatus, type TourStep, type TourStepChangeEvent, TurnEngine, TwoBoneIK, type WebsiteMapSnapshot, type WorkflowDefinition, anchorToViewport, asiystInit, canNavigateTo, canTransition, computeAvatarDestination, createAsiystInstance, createNextAppRouterAdapter, evaluateActionPermission, fallbackConfig, isActionAllowed, isSafeSelector, isSensitiveTarget, normalizeProjectConfig, sanitizeText, setGlobalNavigationAdapter, validateActionDependencies, validateActionItem, validateActionPlan, validateInitOptions, validateWebsiteDomain };
2318
+ export { ACTION_RISK_MAP, ACTION_STATUSES, type AUBRJoint, AUBRSkeleton, AVATAR_ACTION_PROTOCOL_VERSION, AVATAR_ACTION_TYPES, type ActionExecutionContext, type ActionHandler, type ActionKind, ActionNotAllowedError, type ActionRiskLevel, ActionScheduler, type AnimationCategory, type AnimationSourceMode, type AppRouterLike, Asiyst, type AsiystClientInstance, type AsiystDiagnosticReport, AsiystError, type AsiystErrorCode, type AsiystEventMap, type AsiystEventName, type AsiystFallbackOptions, type AsiystInstance, type AsiystProgress, type AsiystSDKState, AssetLoader, type AssistantMode, AuthenticationError, type AvatarActionItem, type AvatarActionPlan, type AvatarActionStatus, type AvatarActionType, type AvatarAnimation, type AvatarBranding, AvatarController, type AvatarLifecycleState, type AvatarLoadingTimestamps, AvatarMetricsTracker, type AvatarPerformanceMetrics, type AvatarPose, type AvatarRenderer, type AvatarRigCapabilities, type AvatarRuntimeConfig, BalanceEngine, CANONICAL_BONE_NAMES, type CanonicalBoneName, type CharacterProportions, type ChatLifecycleState, ConfigurationError, ConfirmationManager, type ConfirmationRequestDetails, CssAvatarRenderer, CustomHostNavigationAdapter, DefaultBrowserNavigationAdapter, type DiagnosticResult, type ExpressionType, FABRIKSolver, FacialAnimationEngine, type FacingDirection, type FbxMountOptions, type FbxRenderMetrics, FbxRenderer, GestureEngine, type GestureType, GreetingManager, type HighlightStyle, IdleEngine, type InitOptions, InitializationError, LocomotionEngine, LookAtEngine, type MappedElement, MotionCoordinator, type MotionLayerWeights, type MotionState, MotionStateMachine, MovementEngine, type NavigationAdapter, NetworkError, NextJsAppRouterNavigationAdapter, NextJsPagesNavigationAdapter, ProceduralMovementEngine, type ProceduralMovementEngineOptions, type ProjectConfig, type RegisteredTarget, type RigDetectionOptions, type RigDetectionResult, RigDetector, type RigType, RuntimeEventReporter, type RuntimeLifecycleState, SDK_VERSION, type SpeechOptions, SpeechPlayer, type TargetInput, TargetNotFoundError, type TargetRef, TargetRegistry, type TaskDefinition, TaskExecutionError, TaskStatus, type TaskStep, type TourDefinition, TourEngine, type TourEngineOptions, type TourStatus, type TourStep, type TourStepChangeEvent, TurnEngine, TwoBoneIK, type WebsiteMapSnapshot, type WorkflowDefinition, anchorToViewport, asiystInit, canNavigateTo, canTransition, computeAvatarDestination, createAsiystInstance, createNextAppRouterAdapter, evaluateActionPermission, fallbackConfig, isActionAllowed, isSafeSelector, isSensitiveTarget, normalizeProjectConfig, sanitizeText, setGlobalNavigationAdapter, validateActionDependencies, validateActionItem, validateActionPlan, validateInitOptions, validateWebsiteDomain };