three-player-controller 0.3.7 → 0.3.9

package/README.md

@@ -1,4 +1,4 @@
-[English](README_En.md)
+中文 | [English](README_En.md)
 
 # three-player-controller
 
@@ -82,7 +82,7 @@ await player.init({
         runAnim: "run",          // Run 动画名
         jumpAnim: "jump",        // Jump 动画名
     },
-    initPos: new THREE.Vector3(0, 0, 0), // 初始位置
+    initPos: new THREE.Vector3(0, 0, 0),
 });
 
 // 加入车辆控制
@@ -117,38 +117,24 @@ player.update();
 
 ```ts
 export function playerController(): {
-    // 初始化
     init: (opts: PlayerControllerOptions, callback?: () => void) => void;
-    // 加载车辆模型
     loadVehicleModel: (params: VehicleOptions) => void;
-    // 切换人物模型
     switchPlayerModel: (model: PlayerControllerOptions["playerModel"]) => void;
-    // 切换第一/第三人称
     changeView: () => void;
-    // 复位玩家位置
     reset: (pos?: THREE.Vector3) => void;
-    // 每帧调用
     update: (dt?: number) => void;
-    // 销毁控制器
     destroy: () => void;
-    // 外部输入控制
     setInput: (input: PlayerInput) => void;
-    // 获取人物当前位置
     getPosition: () => THREE.Vector3;
-    // 获取屏幕中心射线与场景的交点
     getCenterScreenRaycastHit: () => THREE.Intersection | undefined;
-    // 获取人物模型
     getPerson: () => THREE.Object3D | null;
-    // 获取当前驾驶的车辆实例
     getActiveVehicle: () => VehicleInstance | null;
-    // 获取所有车辆实例
     getAllVehicles: () => VehicleInstance[];
-    // 动态参数调整
     setMouseSensitivity: (mouseSensity: number) => void;
     setGravity: (gravity: number) => void;
     setJumpHeight: (jumpHeight: number) => void;
     setPlayerSpeed: (playerSpeed: number) => void;
-    setflySpeed: (flySpeed: number) => void;
+    setPlayerFlySpeed: (playerFlySpeed: number) => void;
     setMinCamDistance: (minCamDistance: number) => void;
     setMaxCamDistance: (maxCamDistance: number) => void;
     setThirdMouseMode: (thirdMouseMode: 0 | 1 | 2 | 3) => void;
@@ -156,6 +142,18 @@ export function playerController(): {
     setOverShoulderView: (enable: boolean) => void;
     setPlayerScale: (scale: number) => void;
     setDebug: (debug: boolean) => void;
+    getCurrentPersonAnimationName: () => string | null;
+    registerAnimation: (key: string, clipName: string, opts?: {
+        loop?: boolean;
+        timeScale?: number;
+        duration?: number;
+        clampWhenFinished?: boolean;
+        onFinished?: () => void;
+    }) => void;
+    playAnimation: (key: string, opts?: {
+        fade?: number;
+        force?: boolean;
+    }) => void;
 };
 ```
 
@@ -180,7 +178,7 @@ export function playerController(): {
 | `setGravity(v)` | 设置重力（传入基准值，内部自动乘以 scale） |
 | `setJumpHeight(v)` | 设置跳跃高度（传入基准值，内部自动乘以 scale） |
 | `setPlayerSpeed(v)` | 设置移动速度（传入基准值，内部自动乘以 scale） |
-| `setflySpeed(v)` | 设置飞行速度（传入基准值，内部自动乘以 scale） |
+| `setPlayerFlySpeed(v)` | 设置飞行速度（传入基准值，内部自动乘以 scale） |
 | `setMinCamDistance(v)` | 设置第三人称最小相机距离 |
 | `setMaxCamDistance(v)` | 设置第三人称最大相机距离 |
 | `setThirdMouseMode(v)` | 设置第三人称鼠标模式（0~3） |
@@ -188,6 +186,9 @@ export function playerController(): {
 | `setOverShoulderView(v)` | 开启/关闭过肩视角偏移 |
 | `setPlayerScale(scale)` | 动态设置人物缩放，同步更新碰撞体与所有相关物理参数 |
 | `setDebug(v)` | 开启/关闭碰撞体调试显示 |
+| `getCurrentPersonAnimationName()` | 获取当前正在播放的动画名称 |
+| `registerAnimation(key, clipName, opts?)` | 注册一个自定义动画，之后可通过 `playAnimation` 播放 |
+| `playAnimation(key, opts?)` | 播放已注册的自定义动画 |
 
 ---
 
@@ -211,15 +212,15 @@ export function offAllEvent(): void; // 关闭所有输入事件
 
 ```ts
 player.setInput({
-    moveX: 1 | 0 | -1,       // 横向移动：1 右，-1 左，0 停
-    moveY: 1 | 0 | -1,       // 纵向移动：1 前，-1 后，0 停
-    lookDeltaX: number,       // 视角横向偏移量
-    lookDeltaY: number,       // 视角纵向偏移量
-    jump: boolean,            // 跳跃
-    shift: boolean,           // 奔跑
-    toggleView: boolean,      // 切换第一/第三人称
-    toggleFly: boolean,       // 切换飞行模式
-    toggleVehicle: boolean,   // 上车/下车
+    moveX: 1 | 0 | -1,      // 横向移动：1 右，-1 左，0 停
+    moveY: 1 | 0 | -1,      // 纵向移动：1 前，-1 后，0 停
+    lookDeltaX: number,      // 视角横向偏移量
+    lookDeltaY: number,      // 视角纵向偏移量
+    jump: boolean,           // 跳跃
+    shift: boolean,          // 奔跑
+    toggleView: boolean,     // 切换第一/第三人称
+    toggleFly: boolean,      // 切换飞行模式
+    toggleVehicle: boolean,  // 上车/下车
 });
 ```
 
@@ -255,6 +256,7 @@ type PlayerControllerOptions = {
         rotateY?: number;
         headObjName?: string;
         flyEnabled?: boolean;
+        capsuleRadiusRatio?: number;
     };
     initPos?: THREE.Vector3;
     mouseSensity?: number;
@@ -304,14 +306,13 @@ type PlayerControllerOptions = {
 | `thirdMouseMode` | `0\|1\|2\|3` | 否 | `1` | 第三人称鼠标模式（见下表） |
 | `enableZoom` | `boolean` | 否 | `false` | 第三人称是否允许滚轮缩放 |
 | `enableOverShoulderView` | `boolean` | 否 | `false` | 是否开启过肩视角偏移 |
-| `capsuleRadiusRatio` | `number` | 否 | `1.0` | 玩家胶囊碰撞体的半径系数，值越大碰撞范围越宽 |
 
 **thirdMouseMode 说明：**
 
 | 值 | 行为 |
 |----|------|
-| `0` | 隐藏鼠标，鼠标同时控制朝向和视角 |
-| `1` | 隐藏鼠标，鼠标仅控制视角（默认） |
+| `0` | 隐藏鼠标，同时控制朝向和视角 |
+| `1` | 隐藏鼠标，仅控制视角（默认） |
 | `2` | 显示鼠标，拖拽控制朝向和视角 |
 | `3` | 显示鼠标，拖拽仅控制视角 |
 
@@ -355,6 +356,55 @@ type VehicleOptions = {
 
 ---
 
+---
+
+## 四、自定义动画
+
+除内置动画外，可在加载模型后注册并播放自定义动画片段。
+
+### registerAnimation
+
+```ts
+player.registerAnimation(key, clipName, opts?)
+```
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `key` | `string` | 动画标识符，之后通过此 key 播放 |
+| `clipName` | `string` | GLB 模型内动画片段的原始名称 |
+| `opts.loop` | `boolean` | 是否循环，默认 `true` |
+| `opts.timeScale` | `number` | 播放速度倍率，默认 `1` |
+| `opts.duration` | `number` | 指定播放时长（秒），会自动计算 timeScale，与 `timeScale` 二选一 |
+| `opts.clampWhenFinished` | `boolean` | 单次播放结束后是否停在最后一帧，默认 `false` |
+| `opts.onFinished` | `() => void` | 动画播放完毕回调（仅单次播放时有效） |
+
+### playAnimation
+
+```ts
+player.playAnimation(key, opts?)
+```
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `key` | `string` | 已注册的动画标识符 |
+| `opts.fade` | `number` | 过渡时间（秒），默认 `0.18` |
+| `opts.force` | `boolean` | 是否强制从头重播（即使当前已在播放该动画） |
+
+**示例：**
+
+```ts
+// 注册一个单次播放、播完回调的动画
+player.registerAnimation("attack", "Attack_Clip", {
+    loop: false,
+    duration: 1.2,
+    clampWhenFinished: true,
+    onFinished: () => console.log("攻击结束"),
+});
+
+// 播放
+player.playAnimation("attack", { force: true });
+```
+
 # 感谢
 
 [three-mesh-bvh](https://github.com/gkjohnson/three-mesh-bvh)

package/dist/index.d.mts

@@ -1,94 +1,61 @@
-import { RigidBody } from '@dimforge/rapier3d-compat';
 import * as THREE from 'three';
-import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js';
+import { RigidBody } from '@dimforge/rapier3d-compat';
 
-/**
- * 障碍物检测接口
- */
 interface ObstacleChecker {
-    /**
-     * 检查两点之间的线段是否被障碍物阻挡
-     */
     isBlocked(start: THREE.Vector3, end: THREE.Vector3): boolean;
-    /**
-     * 获取障碍物周围的导航节点
-     */
     getNavigationNodes(start: THREE.Vector3, goal: THREE.Vector3): THREE.Vector3[];
 }
-/**
- * 路径规划器配置
- */
 interface PathPlannerConfig {
     debugEnabled?: boolean;
     scene?: THREE.Scene;
     scale?: number;
 }
-/**
- * A*路径规划器
- */
 declare class PathPlanner {
-    private obstacleChecker;
-    private config;
-    private debugLines;
-    private debugPoints;
+    obstacleChecker: ObstacleChecker;
+    config: PathPlannerConfig;
+    debugLines: THREE.Line[];
+    debugPoints: THREE.Mesh[];
     constructor(obstacleChecker: ObstacleChecker, config?: PathPlannerConfig);
     private heuristic;
     findPath(start: THREE.Vector3, goal: THREE.Vector3): THREE.Vector3[];
-    /**
-     * 重建路径
-     */
     private reconstructPath;
-    /**
-     * 路径平滑
-     */
     private smoothPath;
-    /**
-     * 可视化路径
-     */
     private visualizePath;
-    /**
-     * 清除路径可视化
-     */
     clearVisualization(): void;
-    /**
-     * 更新配置
-     */
     updateConfig(config: Partial<PathPlannerConfig>): void;
-    /**
-     * 销毁
-     */
     dispose(): void;
 }
 
+type PlayerModelOptions = {
+    url: string;
+    scale: number;
+    idleAnim: string;
+    walkAnim: string;
+    runAnim: string;
+    jumpAnim: string;
+    leftWalkAnim?: string;
+    rightWalkAnim?: string;
+    backwardAnim?: string;
+    flyAnim?: string;
+    flyIdleAnim?: string;
+    enterCarAnim?: string;
+    exitCarAnim?: string;
+    gravity?: number;
+    jumpHeight?: number;
+    speed?: number;
+    flySpeed?: number;
+    rotateY?: number;
+    headObjName?: string;
+    flyEnabled?: boolean;
+    capsuleRadiusRatio?: number;
+};
 type PlayerControllerOptions = {
     scene: THREE.Scene;
     camera: THREE.PerspectiveCamera;
-    controls: OrbitControls;
-    playerModel: {
-        url: string;
-        idleAnim: string;
-        walkAnim: string;
-        runAnim: string;
-        jumpAnim: string;
-        leftWalkAnim?: string;
-        rightWalkAnim?: string;
-        backwardAnim?: string;
-        flyAnim?: string;
-        flyIdleAnim?: string;
-        enterCarAnim?: string;
-        exitCarAnim?: string;
-        scale: number;
-        gravity?: number;
-        jumpHeight?: number;
-        speed?: number;
-        flySpeed?: number;
-        rotateY?: number;
-        headObjName?: string;
-        flyEnabled?: boolean;
-        capsuleRadiusRatio?: number;
-    };
+    controls: any;
+    playerModel: PlayerModelOptions;
     initPos?: THREE.Vector3;
-    mouseSensity?: number;
+    mouseSensitivity?: number;
     minCamDistance?: number;
     maxCamDistance?: number;
     colliderMeshUrl?: string;
@@ -135,35 +102,47 @@ type VehicleInstance = {
     };
     speedMultiplier: number;
 };
+
 declare function playerController(): {
-    init: (opts: PlayerControllerOptions, callback?: () => void) => Promise<void>;
-    loadVehicleModel: (params: VehicleOptions) => Promise<void>;
-    changeView: () => void;
-    reset: (pos?: THREE.Vector3) => void;
+    init: (opts: PlayerControllerOptions, cb?: () => void) => Promise<void>;
+    loadVehicleModel: (opts: VehicleOptions) => Promise<void>;
     update: (dt?: number) => Promise<void>;
     destroy: () => void;
+    reset: (pos?: THREE.Vector3) => void;
     setInput: (i: any) => void;
+    changeView: () => void;
     getPosition: () => THREE.Vector3;
-    getCenterScreenRaycastHit: () => THREE.Intersection<THREE.Object3D<THREE.Object3DEventMap>>;
-    getPerson: () => THREE.Object3D<THREE.Object3DEventMap>;
-    getActiveVehicle: () => VehicleInstance;
+    getCenterScreenRaycastHit: () => THREE.Intersection<THREE.Object3D<THREE.Object3DEventMap>> | undefined;
+    getCurrentPersonAnimationName: () => string | null;
+    getPerson: () => THREE.Object3D<THREE.Object3DEventMap> | null;
+    getActiveVehicle: () => VehicleInstance | null;
     getAllVehicles: () => VehicleInstance[];
-    switchPlayerModel: (model: PlayerControllerOptions["playerModel"]) => Promise<void>;
-    setMouseSensitivity: (mouseSensity: number) => void;
-    setGravity: (gravity: number) => void;
-    setJumpHeight: (jumpHeight: number) => void;
-    setPlayerSpeed: (playerSpeed: number) => void;
-    setPlayerFlySpeed: (playerFlySpeed: number) => void;
-    setMinCamDistance: (minCamDistance: number) => void;
-    setMaxCamDistance: (maxCamDistance: number) => void;
-    setThirdMouseMode: (thirdMouseMode: 0 | 1 | 2 | 3) => void;
-    setEnableZoom: (enableZoom: boolean) => void;
-    setDebug: (debug: boolean) => void;
-    setOverShoulderView: (enable: boolean) => void;
+    switchPlayerModel: (model: PlayerModelOptions) => Promise<void>;
     setPlayerScale: (scale: number) => void;
+    setMouseSensitivity: (v: number) => void;
+    setGravity: (v: number) => void;
+    setJumpHeight: (v: number) => void;
+    setPlayerSpeed: (v: number) => void;
+    setPlayerFlySpeed: (v: number) => void;
+    setMinCamDistance: (v: number) => void;
+    setMaxCamDistance: (v: number) => void;
+    setThirdMouseMode: (v: 0 | 1 | 2 | 3) => void;
+    setEnableZoom: (v: boolean) => void;
+    setDebug: (v: boolean) => void;
+    setOverShoulderView: (v: boolean) => void;
+    registerAnimation: (key: string, clipName: string, opts?: {
+        loop?: boolean;
+        timeScale?: number;
+        clampWhenFinished?: boolean;
+        onFinished?: () => void;
+    }) => void;
+    playAnimation: (key: string, opts?: {
+        fade?: number;
+        force?: boolean;
+    }) => void;
 };
 type playerController = ReturnType<typeof playerController>;
 declare function onAllEvent(): void;
 declare function offAllEvent(): void;
 
-export { type PlayerControllerOptions, type VehicleInstance, type VehicleOptions, offAllEvent, onAllEvent, playerController };
+export { type PlayerControllerOptions, type PlayerModelOptions, type VehicleInstance, type VehicleOptions, offAllEvent, onAllEvent, playerController };

package/dist/index.d.ts

@@ -1,94 +1,61 @@
-import { RigidBody } from '@dimforge/rapier3d-compat';
 import * as THREE from 'three';
-import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js';
+import { RigidBody } from '@dimforge/rapier3d-compat';
 
-/**
- * 障碍物检测接口
- */
 interface ObstacleChecker {
-    /**
-     * 检查两点之间的线段是否被障碍物阻挡
-     */
     isBlocked(start: THREE.Vector3, end: THREE.Vector3): boolean;
-    /**
-     * 获取障碍物周围的导航节点
-     */
     getNavigationNodes(start: THREE.Vector3, goal: THREE.Vector3): THREE.Vector3[];
 }
-/**
- * 路径规划器配置
- */
 interface PathPlannerConfig {
     debugEnabled?: boolean;
     scene?: THREE.Scene;
     scale?: number;
 }
-/**
- * A*路径规划器
- */
 declare class PathPlanner {
-    private obstacleChecker;
-    private config;
-    private debugLines;
-    private debugPoints;
+    obstacleChecker: ObstacleChecker;
+    config: PathPlannerConfig;
+    debugLines: THREE.Line[];
+    debugPoints: THREE.Mesh[];
     constructor(obstacleChecker: ObstacleChecker, config?: PathPlannerConfig);
     private heuristic;
     findPath(start: THREE.Vector3, goal: THREE.Vector3): THREE.Vector3[];
-    /**
-     * 重建路径
-     */
     private reconstructPath;
-    /**
-     * 路径平滑
-     */
     private smoothPath;
-    /**
-     * 可视化路径
-     */
     private visualizePath;
-    /**
-     * 清除路径可视化
-     */
     clearVisualization(): void;
-    /**
-     * 更新配置
-     */
     updateConfig(config: Partial<PathPlannerConfig>): void;
-    /**
-     * 销毁
-     */
     dispose(): void;
 }
 
+type PlayerModelOptions = {
+    url: string;
+    scale: number;
+    idleAnim: string;
+    walkAnim: string;
+    runAnim: string;
+    jumpAnim: string;
+    leftWalkAnim?: string;
+    rightWalkAnim?: string;
+    backwardAnim?: string;
+    flyAnim?: string;
+    flyIdleAnim?: string;
+    enterCarAnim?: string;
+    exitCarAnim?: string;
+    gravity?: number;
+    jumpHeight?: number;
+    speed?: number;
+    flySpeed?: number;
+    rotateY?: number;
+    headObjName?: string;
+    flyEnabled?: boolean;
+    capsuleRadiusRatio?: number;
+};
 type PlayerControllerOptions = {
     scene: THREE.Scene;
     camera: THREE.PerspectiveCamera;
-    controls: OrbitControls;
-    playerModel: {
-        url: string;
-        idleAnim: string;
-        walkAnim: string;
-        runAnim: string;
-        jumpAnim: string;
-        leftWalkAnim?: string;
-        rightWalkAnim?: string;
-        backwardAnim?: string;
-        flyAnim?: string;
-        flyIdleAnim?: string;
-        enterCarAnim?: string;
-        exitCarAnim?: string;
-        scale: number;
-        gravity?: number;
-        jumpHeight?: number;
-        speed?: number;
-        flySpeed?: number;
-        rotateY?: number;
-        headObjName?: string;
-        flyEnabled?: boolean;
-        capsuleRadiusRatio?: number;
-    };
+    controls: any;
+    playerModel: PlayerModelOptions;
     initPos?: THREE.Vector3;
-    mouseSensity?: number;
+    mouseSensitivity?: number;
     minCamDistance?: number;
     maxCamDistance?: number;
     colliderMeshUrl?: string;
@@ -135,35 +102,47 @@ type VehicleInstance = {
     };
     speedMultiplier: number;
 };
+
 declare function playerController(): {
-    init: (opts: PlayerControllerOptions, callback?: () => void) => Promise<void>;
-    loadVehicleModel: (params: VehicleOptions) => Promise<void>;
-    changeView: () => void;
-    reset: (pos?: THREE.Vector3) => void;
+    init: (opts: PlayerControllerOptions, cb?: () => void) => Promise<void>;
+    loadVehicleModel: (opts: VehicleOptions) => Promise<void>;
     update: (dt?: number) => Promise<void>;
     destroy: () => void;
+    reset: (pos?: THREE.Vector3) => void;
     setInput: (i: any) => void;
+    changeView: () => void;
     getPosition: () => THREE.Vector3;
-    getCenterScreenRaycastHit: () => THREE.Intersection<THREE.Object3D<THREE.Object3DEventMap>>;
-    getPerson: () => THREE.Object3D<THREE.Object3DEventMap>;
-    getActiveVehicle: () => VehicleInstance;
+    getCenterScreenRaycastHit: () => THREE.Intersection<THREE.Object3D<THREE.Object3DEventMap>> | undefined;
+    getCurrentPersonAnimationName: () => string | null;
+    getPerson: () => THREE.Object3D<THREE.Object3DEventMap> | null;
+    getActiveVehicle: () => VehicleInstance | null;
     getAllVehicles: () => VehicleInstance[];
-    switchPlayerModel: (model: PlayerControllerOptions["playerModel"]) => Promise<void>;
-    setMouseSensitivity: (mouseSensity: number) => void;
-    setGravity: (gravity: number) => void;
-    setJumpHeight: (jumpHeight: number) => void;
-    setPlayerSpeed: (playerSpeed: number) => void;
-    setPlayerFlySpeed: (playerFlySpeed: number) => void;
-    setMinCamDistance: (minCamDistance: number) => void;
-    setMaxCamDistance: (maxCamDistance: number) => void;
-    setThirdMouseMode: (thirdMouseMode: 0 | 1 | 2 | 3) => void;
-    setEnableZoom: (enableZoom: boolean) => void;
-    setDebug: (debug: boolean) => void;
-    setOverShoulderView: (enable: boolean) => void;
+    switchPlayerModel: (model: PlayerModelOptions) => Promise<void>;
     setPlayerScale: (scale: number) => void;
+    setMouseSensitivity: (v: number) => void;
+    setGravity: (v: number) => void;
+    setJumpHeight: (v: number) => void;
+    setPlayerSpeed: (v: number) => void;
+    setPlayerFlySpeed: (v: number) => void;
+    setMinCamDistance: (v: number) => void;
+    setMaxCamDistance: (v: number) => void;
+    setThirdMouseMode: (v: 0 | 1 | 2 | 3) => void;
+    setEnableZoom: (v: boolean) => void;
+    setDebug: (v: boolean) => void;
+    setOverShoulderView: (v: boolean) => void;
+    registerAnimation: (key: string, clipName: string, opts?: {
+        loop?: boolean;
+        timeScale?: number;
+        clampWhenFinished?: boolean;
+        onFinished?: () => void;
+    }) => void;
+    playAnimation: (key: string, opts?: {
+        fade?: number;
+        force?: boolean;
+    }) => void;
 };
 type playerController = ReturnType<typeof playerController>;
 declare function onAllEvent(): void;
 declare function offAllEvent(): void;
 
-export { type PlayerControllerOptions, type VehicleInstance, type VehicleOptions, offAllEvent, onAllEvent, playerController };
+export { type PlayerControllerOptions, type PlayerModelOptions, type VehicleInstance, type VehicleOptions, offAllEvent, onAllEvent, playerController };