@soonspacejs/plugin-navigation 2.16.8 → 3.0.0-alpha.1

package/dist/index.d.ts

@@ -1,4 +1,623 @@
-export * from './camera';
-export * from './navigator';
-export * from './utils';
-export * from './azimuth';
+import { Camera } from 'three';
+import { default as default_2 } from 'soonspacejs';
+import { Euler } from 'three';
+import { EulerOrder } from 'three';
+import { Node as Node_2 } from 'soonspacejs';
+import { Object3D } from 'three';
+import { Object3DEventMap } from 'three';
+import { OrthographicCamera } from 'three';
+import { Quaternion } from 'three';
+import { Topology } from 'soonspacejs';
+import { Vector3 } from 'three';
+
+/**
+ * 角度范围
+ * @remarks
+ * - 可以是 [start,end] 也可以是 [end，start]，即：可以第一个值 可以在于 第二个值
+ * - 范围始终包含 第一个值，不包含第二个值
+ */
+export declare type AngleRange = [number, number];
+
+/**
+ * 计算方位的类
+ */
+export declare class Azimuth {
+    constructor(options?: AzimuthOptions);
+    static get options(): AzimuthOptions;
+    static set options(value: AzimuthOptions);
+    protected static _options?: AzimuthOptions | null;
+    /**
+     * 默认选项
+     */
+    protected get defaultOptions(): AzimuthOptions;
+    get options(): AzimuthOptions;
+    set options(value: AzimuthOptions);
+    protected _options?: AzimuthOptions | null;
+    /**
+     * 是否使用角度，而非弧度
+     */
+    get degrees(): boolean;
+    set degrees(value: boolean);
+    get map(): CourseAzimuthMap<AzimuthDefine> | null | undefined;
+    set map(value: CourseAzimuthMap<AzimuthDefine> | null | undefined);
+    protected get listMap(): CourseAzimuthMap<AzimuthList>;
+    protected _listMap?: CourseAzimuthMap<AzimuthList> | null;
+    get front(): IVector3;
+    set front(value: IVector3);
+    protected _front?: Vector3 | null;
+    get up(): IVector3;
+    set up(value: IVector3);
+    protected _up?: Vector3 | null;
+    /**
+     * 计算方位
+     * @param target
+     * @param front
+     * @param up
+     */
+    computeAzimuth(target: IVector3, front?: IVector3 | null, up?: IVector3 | null): CourseInfo;
+    /**
+     * 查找匹配的方位名字
+     * @param type - 类型
+     * @param angle - 角度
+     * @returns 匹配的名字列表
+     */
+    findAzimuthNames(type: keyof CourseAzimuthMap, angle: number): string[];
+}
+
+export declare const azimuth: any;
+
+/**
+ * 方位定义
+ */
+export declare type AzimuthDefine = AzimuthList | AzimuthMap;
+
+export declare interface AzimuthInfo {
+    /**
+     * 角度
+     */
+    angle: number;
+    /**
+     * 所有匹配的名字
+     */
+    name: string[];
+}
+
+/**
+ * 方位范围列表
+ */
+export declare type AzimuthList = AzimuthRange[];
+
+/**
+ * 方位映射
+ */
+export declare type AzimuthMap = Record<string, [number, number]>;
+
+/**
+ * Azimuth 的选项
+ */
+export declare interface AzimuthOptions {
+    /**
+     * 是否使用角度，而非弧度
+     * @defaultValue true
+     */
+    degrees?: boolean | null;
+    /**
+     * 方位映射定义
+     */
+    map?: CourseAzimuthMap | null;
+    /**
+     * 前方向量
+     * @defaultValue {x:0,y:0,z:1}
+     */
+    front?: IVector3;
+    /**
+     * 前方向量
+     * @defaultValue {x:0,y:1,z:0}
+     */
+    up?: IVector3;
+}
+
+/**
+ * 方位范围，用来描述方位对应的角度范围
+ */
+declare interface AzimuthRange {
+    name: string;
+    range: [number, number];
+}
+
+export declare type CameraOppositeType = {
+    x: boolean;
+    y: boolean;
+    z: boolean;
+};
+
+/**
+ * 相机控制回调
+ *
+ * camera 当前相机
+ *
+ * target 跟踪的目标
+ */
+export declare type ControlCallback = (camera: Camera, target: Object3D, event?: MouseEvent | TouchEvent) => void;
+
+/**
+ * 航向方位映射
+ */
+export declare interface CourseAzimuthMap<Define extends AzimuthDefine = AzimuthDefine> {
+    /**
+     * 偏航角
+     * @remarks
+     * - 旋转轴 上方向量
+     * - 起始向量：前方向量
+     */
+    yaw?: Define | null;
+    /**
+     * 俯仰角
+     * @remarks
+     * - 旋转轴 右方向量
+     * - 起始向量：前方向量
+     */
+    pitch?: Define | null;
+    /**
+     * 横滚角
+     * @remarks
+     * - 旋转轴 后方向量
+     * - 起始向量：上方向量
+     */
+    roll?: Define | null;
+}
+
+/**
+ * 航向信息
+ */
+export declare interface CourseInfo {
+    /**
+     * 偏航角
+     * @remarks
+     * - 旋转轴 上方向量
+     * - 起始向量：前方向量
+     */
+    yaw: AzimuthInfo;
+    /**
+     * 俯仰角
+     * @remarks
+     * - 旋转轴 右方向量
+     * - 起始向量：前方向量
+     */
+    pitch: AzimuthInfo;
+    /**
+     * 横滚角
+     * @remarks
+     * - 旋转轴 后方向量
+     * - 起始向量：上方向量
+     */
+    roll: AzimuthInfo;
+}
+
+export declare type Direction = 'left' | 'right' | 'up' | 'down' | 'left-up' | 'left-down' | 'right-up' | 'right-down' | 'straight';
+
+declare interface DistanceInfo {
+    distanceToStartNode: number;
+    distanceToEndNode: number;
+    distanceToStart: number;
+    distanceToEnd: number;
+}
+
+export declare type EulerArray = [number, number, number, EulerOrder?];
+
+export declare function eulerToVector3(e: Euler): Vector3;
+
+export declare type FixEuler = EulerArray | ((target?: Object3DLike) => EulerArray);
+
+export declare type FixVector = VectorArray | ((target?: Object3DLike) => VectorArray);
+
+export declare function getDirection(target: Vector3, front: Vector3): Direction;
+
+export declare function getDirectionByNodes(p1: Node_2, p2?: Node_2, p3?: Node_2): Direction;
+
+/** 获取当前位置距离信息 */
+export declare function getDistanceInfoByProgress(progress: number, info?: NavigatorNodeInfo): DistanceInfo;
+
+export declare function getFixEuler(e: FixEuler, target?: Object3DLike): EulerArray;
+
+export declare function getFixVector(v: FixVector, target?: Object3DLike): VectorArray;
+
+/** 根据进度获取当前节点信息 */
+export declare function getNavigatorNodeInfoByProgress(progress: number, infos: NavigatorNodeInfo[]): NavigatorNodeInfo | undefined;
+
+/** 分析并返回所有节点信息 */
+export declare function getNavigatorNodeInfosByTopology(topology: Topology): NavigatorNodeInfo[];
+
+export declare class GyroListener {
+    gyroEvent: null | ((event: DeviceOrientationEvent) => void);
+    onChange: (alpha: number | null, beta: number | null, gamma: number | null) => void;
+    _isActive: boolean;
+    defaultBeta: number | null;
+    defaultAlpha: number | null;
+    defaultGamma: number | null;
+    cache: null | {
+        beta: number | null;
+        alpha: number | null;
+        gamma: number | null;
+    };
+    beta: number | null;
+    alpha: number | null;
+    gamma: number | null;
+    gyroX: boolean;
+    gyroY: boolean;
+    gyroZ: boolean;
+    absolute: boolean;
+    constructor(x?: boolean, y?: boolean, z?: boolean, absolute?: boolean);
+    requestPermisson(): Promise<unknown>;
+    /** 监听陀螺仪事件 */
+    active(): Promise<void>;
+    /** 销毁陀螺仪事件 */
+    inActive(): void;
+}
+
+/**
+ * 二维向量
+ */
+declare interface IVector2 {
+    	x: number;
+    	y: number;
+}
+
+/**
+ * 三维向量
+ */
+declare interface IVector3 extends IVector2 {
+    	z: number;
+}
+
+export declare class MapCamera extends SoonSpaceCamera<OrthographicCamera> {
+    readonly ssp: default_2;
+    protected resizeObserver: ResizeObserver;
+    _zoom: number;
+    get zoom(): number;
+    set zoom(value: number);
+    constructor(ssp: default_2);
+    resizeCamera(): void;
+    protected onEnter(): void;
+    protected onQuit(): void;
+}
+
+export declare enum NAVIGATE_ORIENTATION_TYPE {
+    RELATIVE_ORIENTATION = "relative",
+    FIXED_ORIENTATION = "fixed",
+    GYRO_ORIENTATION = "gyro"
+}
+
+export declare enum NAVIGATE_VISION_TYPE {
+    FIRST_VISION = "first",
+    THIRD_VISION = "third",
+    UP_VISION = "up",
+    LEFT_VISION = "left"
+}
+
+/** 导航相机 */
+export declare class NavigateCamera extends SoonSpaceCamera<Camera> {
+    readonly ssp: default_2;
+    initOptions: Readonly<NavigateCameraOptions>;
+    cameraKey: string;
+    private _events;
+    get position(): Vector3;
+    get rotation(): Euler;
+    get quaternion(): Quaternion;
+    private _lookAt;
+    private _restoreTimer;
+    private _positionTween;
+    private autoFollowRender;
+    /** 相机位置记录用的对象，用于恢复相机位置和朝向使用 */
+    protected _cameraPlaceholder: Object3D<Object3DEventMap>;
+    /** 取消飞向动画 */
+    disabledAnimate: boolean;
+    /** 第三人称相机距离跟踪目标距离 */
+    distanceToTarget: number;
+    /** 第三人称相机相对模型视角 */
+    rotationToTarget: Vector3;
+    /** 相机反转 */
+    oppositeCamera: boolean;
+    /** 相机反转类型, 默认为 Y 轴对称 */
+    oppositeType: CameraOppositeType;
+    /** 是否相对模型修正角度 */
+    isFixRotationRelativeTarget: boolean;
+    /**
+     * 目标角度修正
+     *
+     * 支持传入 getter 函数
+     */
+    targetRotationFix: FixEuler;
+    /** 是否相对模型修正偏移 */
+    isFixPositionRelativeTarget: boolean;
+    /**
+     * 目标位置修正
+     *
+     * 支持传入 getter 函数
+     */
+    targetPositionFix: FixVector;
+    /**
+     * 自动恢复朝向
+     *
+     * boolean 是否恢复朝向
+     *
+     * number 间隔多少秒后恢复朝向
+     */
+    autoRestoreOrientation: boolean | number;
+    /** 当控制器控制相机时允许外部自定义控制，控制开始时触发 */
+    onControlStart: null | ControlCallback;
+    /** 当控制器控制相机时允许外部自定义控制，控制进行时回调 */
+    onControlRender: null | ControlCallback;
+    /** 当控制器控制相机时允许外部自定义控制，控制结束时回调 */
+    onControlEnd: null | ControlCallback;
+    /** 陀螺仪 */
+    protected _gyroListener: GyroListener;
+    protected _enableGyro: boolean;
+    /** 开启 */
+    get enableGyro(): boolean;
+    set enableGyro(value: boolean);
+    /** 是否应用陀螺仪 X 轴，默认不启动 */
+    get gyroX(): boolean;
+    set gyroX(value: boolean);
+    /** 是否应用陀螺仪 Y 轴，默认启动 */
+    get gyroY(): boolean;
+    set gyroY(value: boolean);
+    /** 是否应用陀螺仪 Z 轴，默认不启动 */
+    get gyroZ(): boolean;
+    set gyroZ(value: boolean);
+    /** 陀螺仪是否使用绝对值，默认使用 */
+    get gyroAbsolute(): boolean;
+    set gyroAbsolute(value: boolean);
+    /** 陀螺仪的旋转欧拉角 */
+    protected _gyroRotation: Euler;
+    get targetRotationAfterFix(): EulerArray;
+    get targetPositionAfterFix(): VectorArray;
+    get realDistanceToTarget(): number;
+    get realRotationToTarget(): Vector3;
+    protected _orientationType: NAVIGATE_ORIENTATION_TYPE;
+    /** 绝对朝向的缓存值 */
+    private _fixedOrientationRotation;
+    /**
+     * 	相机朝向类型
+     *
+     *  NAVIGATE_ORIENTATION_TYPE.RELATIVE_ORIENTATION 相对朝向
+     *
+     *  NAVIGATE_ORIENTATION_TYPE.FIXED_ORIENTATION 绝对朝向
+     *
+     *  NAVIGATE_ORIENTATION_TYPE.GYRO_ORIENTATION 陀螺仪朝向
+     */
+    get orientationType(): NAVIGATE_ORIENTATION_TYPE;
+    set orientationType(value: NAVIGATE_ORIENTATION_TYPE);
+    protected _orientationTarget: NavigateOrientationTarget;
+    /**
+     * 相机朝向目标
+     *
+     * “main” 朝向跟踪目标
+     *
+     * Vector3 朝向点
+     *
+     * Object3D 朝向目标对象
+     *
+     * Euler 固定朝向
+     */
+    get orientationTarget(): NavigateOrientationTarget;
+    set orientationTarget(value: NavigateOrientationTarget);
+    protected _vision: NAVIGATE_VISION_TYPE;
+    /**
+     * 视角配置
+     *
+     * NAVIGATE_VISION_TYPE.FIRST_VISION 第一人称
+     *
+     * NAVIGATE_VISION_TYPE.THIRD_VISION 第三人称
+     *
+     * NAVIGATE_VISION_TYPE.UP_VISION 俯视图
+     *
+     * NAVIGATE_VISION_TYPE.LEFT_VISION 左视图
+     *
+     * 默认为第三人称
+     */
+    get vision(): NAVIGATE_VISION_TYPE;
+    set vision(value: NAVIGATE_VISION_TYPE);
+    protected _followTarget: Object3D;
+    /** 相机跟随目标 */
+    get followTarget(): Object3D;
+    set followTarget(value: Object3D);
+    /** 相机跟踪点（相对跟随目标以及偏移参数获取的点） */
+    get followPosition(): Vector3;
+    /** 跟踪目标的方向（相对跟随目标以及偏移参数获取的朝向） */
+    get followRotation(): Euler;
+    protected _fixedOrientation: boolean;
+    /** 固定朝向，朝向不受控制器影响 */
+    get fixedOrientation(): boolean;
+    set fixedOrientation(value: boolean);
+    constructor(ssp: default_2, camera?: Camera, options?: Partial<NavigateCameraOptions>);
+    protected initGyroListener(): void;
+    /** 控制器操作时处理 */
+    protected setCameraOrientationOnControl(): void;
+    /** 更新相机占位符的方位 */
+    protected updateCameraPlaceholder(): void;
+    /** 设置相机的方位 */
+    protected setCameraOrientationOnRender(): void;
+    /** 获取相机点相对跟踪点的欧拉角 */
+    protected getRenderCameraOrientation(): Euler;
+    /** 获取相机落点（相对跟踪点的方向归一化 * 距离） */
+    protected getRenderCameraPosition(): Vector3;
+    protected onRender(): void;
+    /** 初始化事件 */
+    protected initEvents(): void;
+    /** 清除事件 */
+    protected clearEvents(): void;
+    protected onEnter(): void;
+    protected onQuit(): void;
+    /** 参数重置 */
+    resetOptions(): void;
+    /** 设置参数 */
+    setOptions(options: Partial<NavigateCameraOptions>): void;
+    /**
+     * 设置相机，若导航相机正在使用中，则会立即切换为设置的相机
+     */
+    setCamera(camera: Camera): this;
+    /** 重置相机坐标 */
+    restoreOrientation(): void;
+}
+
+export declare interface NavigateCameraOptions {
+    disabledAnimate: boolean;
+    fixedOrientation: boolean;
+    autoRestoreOrientation: boolean | number;
+    oppositeCamera: boolean;
+    oppositeType: CameraOppositeType;
+    orientationTarget: NavigateOrientationTarget;
+    vision: NAVIGATE_VISION_TYPE;
+    orientationType: NAVIGATE_ORIENTATION_TYPE;
+    distanceToTarget: number;
+    rotationToTarget: Vector3;
+    isFixRotationRelativeTarget: boolean;
+    targetRotationFix: FixEuler;
+    isFixPositionRelativeTarget: boolean;
+    targetPositionFix: FixVector;
+    enableGyro: boolean;
+    gyroX: boolean;
+    gyroY: boolean;
+    gyroZ: boolean;
+    gyroAbsolute: boolean;
+    onControlStart: null | ControlCallback;
+    onControlRender: null | ControlCallback;
+    onControlEnd: null | ControlCallback;
+}
+
+export declare type NavigateOrientationTarget = 'main' | Vector3 | Euler | Object3D;
+
+declare class Navigator_2 {
+    readonly ssp: default_2;
+    paths: Topology[];
+    onPlay: (info: playInfo) => void;
+    onStatusChange: (status: PLAY_STATUS) => void;
+    /** 是否循环播放，默认为否 */
+    loop: boolean;
+    /** 是否自动开始下一段路径播放，默认为是 */
+    autoNext: boolean;
+    /** 开始或者重新开始后自动播放路径动画，默认为否 */
+    playAfterStart: boolean;
+    /** 开始时飞向模型，默认为是 */
+    flyToModelAfterStart: boolean;
+    /** 停止时是否返回起点，默认为是 */
+    backStartPointWhenStop: boolean;
+    /** 路径动画主体模型 */
+    _model: Object3D<Object3DEventMap>;
+    get model(): Object3D;
+    set model(obj: Object3D);
+    protected _speed: number;
+    /** 播放速度 */
+    get speed(): number;
+    set speed(value: number);
+    protected _pathProgress: number;
+    /** 当前段进度 */
+    get pathProgress(): number;
+    set pathProgress(value: number);
+    protected _totalProgress: number;
+    /** 总进度 */
+    get totalProgress(): number;
+    set totalProgress(value: number);
+    /** 当前播放的动画路径索引 */
+    protected _currentPathIndex: number;
+    /** 当前节点 */
+    protected _currentNode: Vector3 | null;
+    /** 下个路径节点 */
+    protected _nextNode: Vector3 | null;
+    /** 当前状态 */
+    protected _playStatus: PLAY_STATUS;
+    get currentPath(): Topology;
+    /** 对外只读 当前路径索引 */
+    get currentPathIndex(): number;
+    /** 对外只读 当前朝向方向向量 */
+    get currentRotationVector(): Vector3;
+    constructor(ssp: default_2, paths: Topology[]);
+    protected changeStatus(status: PLAY_STATUS): void;
+    /** 开始导航 */
+    start(): void;
+    /** 重新开始导航 */
+    restart(): void;
+    /** 播放动画 */
+    play(index?: number, node?: Vector3): void;
+    /** 暂停动画 */
+    pause(): void;
+    /** 停止动画 */
+    stop(): void;
+    /** 路径反转 */
+    flip(): void;
+    /** 结束导航 */
+    over(): void;
+}
+export { Navigator_2 as Navigator }
+
+declare interface NavigatorNodeInfo {
+    progressArea: [number, number];
+    distanceArea: [number, number];
+    node: Node_2;
+    nextNode?: Node_2;
+    distanceToNext: number;
+    distanceToStart: number;
+    distanceToEnd: number;
+    frontDirection: Direction;
+}
+
+/**
+ * 欧拉角归一化
+ * @param e 欧拉角
+ */
+export declare function normalizeEuler(e: Euler): Vector3;
+
+export declare type Object3DLike = {
+    position: Vector3;
+    rotation: Euler;
+} & Record<PropertyKey, any>;
+
+export declare enum PLAY_STATUS {
+    'PENDING' = "pending",
+    'STOP' = "stop",
+    'PLAYING' = "playing",
+    'PAUSE' = "pause",
+    'FINISHED' = "finished"
+}
+
+export declare interface playInfo {
+    pathId: string;
+    progress: number;
+    pathProgress: number;
+    distanceToNodeStart: number;
+    distanceToPathStart: number;
+    distanceToStart: number;
+    distanceToNodeEnd: number;
+    distanceToPathEnd: number;
+    distanceToEnd: number;
+    position: Vector3;
+    rotation: Vector3;
+    direction: Direction;
+}
+
+/**
+ * 路径反转
+ * @param ssp
+ * @param topologies 路径数组
+ * @returns
+ */
+export declare function reverseTopologies(ssp: default_2, topologies: Topology[]): Topology[];
+
+export declare abstract class SoonSpaceCamera<C extends Camera = Camera> {
+    readonly ssp: default_2;
+    nativeCamera: C;
+    protected _isActive: boolean;
+    constructor(ssp: default_2, nativeCamera: C);
+    active(): void;
+    private _onBeforeEnter;
+    private _onBeforeQuit;
+    protected onEnter(): void;
+    protected onQuit(): void;
+}
+
+export declare function Vector3ToEuler(v: Vector3): Euler;
+
+export declare type VectorArray = [number, number, number];
+
+export { }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@soonspacejs/plugin-navigation",
   "pluginName": "NavigationPlugin",
-  "version": "2.16.8",
+  "version": "3.0.0-alpha.1",
   "description": "Navigation plugin for SoonSpace.js",
   "main": "dist/index.esm.js",
   "module": "dist/index.esm.js",
@@ -15,7 +15,7 @@
   "license": "UNLICENSED",
   "gitHead": "4a87dd85050651088e11c3da777c49fab3db7e5d",
   "peerDependencies": {
-    "soonspacejs": "2.16.8"
+    "soonspacejs": "3.0.0-alpha.1"
   },
   "dependencies": {
     "@three3d/tools": "^1.6.0"