@dao3fun/player-fall-manager/index.d.ts

管理玩家的坠落，实时计算坠落开始到结束期间的数据并返回。

/**
 * 配置玩家坠落时的行为
 */
export interface FallConfigObject {
    /** 玩家实体对象 */
    entity: GameEntity;
    /** 可选参数，表示坠落的阈值，当玩家的Y坐标高低差异大于此值时触发事件。
        - 当设定后将优先设定本阈值，而不使用全局阈值
    */
    thresholdY?: number;
    /** 可选参数，当玩家坠落到 thresholdY 设定的阈值时执行的回调函数。
        - 当设定后将优先触发本回调函数，不触发全局回调函数
    */
    onThresholdExceeded?: (handle: onThresholdExceeded) => void;
}


/**
 * 表示当坠落到阈值以下时传递的数据
 */
export interface onThresholdExceeded {
    /** 坠落的实体对象 */
    entity: GameEntity;
    /** 坠落时间戳信息，包括开始戳、结束戳和坠落时间（MS） */
    time: {
        start: number;
        end: number;
        fallTimeMS: number;
    };
    /** Y轴方向上的坠落距离信息，包括开始Y坐标、结束Y坐标和绝对坠落距离
        - 由于本监听方式是基于 world.onTick ，所以Y坐标可能会有±2的误差。
    */
    yDistance: {
        start: number;
        end: number;
        absFallDistance: number;
    };
}


/**
 * 构造玩家坠落管理器的配置对象
 */
export interface FallConfigObjectConstructor {
    /**  坠落的阈值，当玩家的Y坐标高低差异大于此值时触发事件。
         - 当没有配置玩家单独的阈值时，使用全局阈值  
    */
    thresholdY: number;
    /** 当玩家坠落到阈值以下时执行的回调函数。
        - 当没有配置玩家单独的回调函数时，使用全局回调函数
    */
    onThresholdExceeded: (handle: onThresholdExceeded) => void;
}


export type FallConfig = FallConfigObject | GameEntity;
/**
 * 管理玩家的坠落行为
 */
export default class PlayerFallManager {
    /**
     * 当玩家坠落到 thresholdY 设定的阈值时执行的回调函数。
     */
    onThresholdExceeded: (handle: onThresholdExceeded) => void;

    /**
     * 坠落的阈值，当玩家的Y坐标高低差异大于此值时触发事件。
     */
    thresholdY: number;

    /**
     * 用于存储玩家的Map集合，键为玩家ID，值为玩家的坠落配置
     */
    players: Map<string, FallConfigObject>;

    /**
     * 游戏 world.onTick 事件处理器的令牌
     */
    tickToken: GameEventHandlerToken;

    /** 
     *  当玩家坠落到阈值以下时，打印日志
     *  - 缺省值：false
     */
    isLog: boolean;

    /**
     * 构造函数，初始化玩家坠落管理器
     * @param FallConfig - 初始化配置对象
     */
    constructor(FallConfig: FallConfigObjectConstructor);

    /**
     * 添加玩家到坠落管理器中
     * @param fallConfig - 玩家的坠落配置
     * @returns 更新后的玩家Map集合
     */
    addPlayer(fallConfig: FallConfig): Map<string, FallConfigObject>;

    /**
     * 从坠落管理器中移除玩家
     * @param id - 玩家ID
     * @returns 移除成功返回true，否则返回false
     */
    removePlayer(id: string): boolean;
}