边界检查重生

策划在关卡编辑器里摆范围盒，玩家离开任务区域 → 弹倒计时警告 → 时间到强制拉回。 另有一种「坠落区域」：一进就直接重生，不倒计时。
本模块不自己做位移，位移全部委托给 ③ 坠落重生。 它负责的是判定时机、文案、黑屏编排——难点全在这三件事的时序上。

1. 模块定位

1.1 两种触发条件，一套组件

两者都是可选配置，一个实体可以只配一种，也可以两种都配。

1.2 编辑器配置结构

export interface IBoundaryRespawnComponent extends IComponentBase {
    /** 倒计时判断条件（可选配置） */
    BoundaryCountdownCondition?: IBoundaryRespawnCondition;
    /** 坠落区域判断条件（可选配置） */
    FallZoneCondition?: IFallZoneCondition;
}

export interface IBoundaryRespawnCondition {
    /** 倒计时（秒），默认15秒 */
    CountdownTime: number;
    EdTidWarningText?: string;      // 预警文本 · 编辑器显示文本（策划填的中文）
    TidWarningText?: string;        // 预警文本 · 多语言 ID
    EdTidRespawnText?: string;      // 重生文本 · 编辑器显示文本
    TidRespawnText?: string;        // 重生文本 · 多语言 ID
    /** 边界范围实体数组 */
    BoundaryRangeEntityIds: number[];
    /** 取反触发：true 表示在边界范围"外"才倒计时（区域内为安全区），默认 false */
    TriggerOnLeave?: boolean;
}

1.3 TriggerOnLeave：一个字段搞定两种语义

策划有两种摆法：「摆危险区」（进去就倒计时）和 「摆安全区」（出来才倒计时）。 代码用一个布尔翻转来统一：

private readonly HandleOnEntityEnterBoundaryRange = (otherCreatureDataId: number): void => {
    if (this.IsHidden()) { return; }
    if (this.DataComp?.BoundaryCountdownCondition?.TriggerOnLeave) {
        this.OnLeaveBoundaryRange();      // 翻转：物理"进入" → 逻辑"离开危险"
    } else {
        this.OnEnterBoundaryRange();
    }
};

private readonly HandleOnEntityLeaveBoundaryRange = (otherCreatureDataId: number): void => {
    if (this.IsHidden()) { return; }
    if (this.DataComp?.BoundaryCountdownCondition?.TriggerOnLeave) {
        this.OnEnterBoundaryRange();      // 翻转：物理"离开" → 逻辑"进入危险"
    } else {
        this.OnLeaveBoundaryRange();
    }
};

2. 核心难点一：范围盒还没创建怎么办

2.1 Pending 补注册机制

/** 组件启动时范围实体还没创建出来，先记下 PrefabDataId，等 EntityInitialized 事件再补注册 */
private readonly PendingBoundaryRangeIds: Set<number> = new Set();
private readonly PendingFallZoneIds: Set<number> = new Set();

/** 是否已挂上 EntityInitialized 监听（只在还有待补注册的实体时挂） */
private IsWaitingEntityInitialized = false;

private RegisterRangeEvents(): void {
    const boundaryIds = this.DataComp?.BoundaryCountdownCondition?.BoundaryRangeEntityIds;
    if (boundaryIds) {
        for (const prefabDataId of boundaryIds) {
            if (!this.TryRegisterBoundaryRange(prefabDataId)) {
                this.PendingBoundaryRangeIds.add(prefabDataId);   // 挂不上 → 进待办
            }
        }
    }
    // FallZone 同理 ...
    this.RefreshEntityInitializedListener();
}

2.2 为什么必须用 EntityInitialized 而不是 EntityCreated

/** 按 Pending 是否为空决定挂/摘 EntityInitialized 监听。
 *  用 Initialized 不用 Created：Created 时范围盒的 OnStart 还没跑，
 *  碰撞体和 overlap 委托都不存在，这时挂监听收不到进入事件。 */
private RefreshEntityInitializedListener(): void {
    const needListen = this.PendingBoundaryRangeIds.size > 0
                     || this.PendingFallZoneIds.size > 0;
    if (needListen === this.IsWaitingEntityInitialized) { return; }   // 状态没变不动
    this.IsWaitingEntityInitialized = needListen;
    if (needListen) {
        EventSystem.TryAdd(EEventName.EntityInitialized, this.HandleEntityInitialized);
    } else {
        EventSystem.TryRemove(EEventName.EntityInitialized, this.HandleEntityInitialized);
    }
}

2.3 补注册时玩家已经在里面了

this.BoundaryRangeEntityHandles.add(entityHandle);
// 挂监听时玩家可能已站在区域内（overlap begin 早已发过且不会补发），补判一次
const inRangeCreatureDataId = this.GetLocalPlayerCreatureDataIdInRange(entityHandle);
if (inRangeCreatureDataId !== undefined) {
    Log.Debug(..., '重生组件-注册时玩家已在边界范围内，补触发进入', ['PrefabDataId', prefabDataId]);
    this.HandleOnEntityEnterBoundaryRange(inRangeCreatureDataId);
}

/** 本地玩家已在该范围实体的客户端范围内则返回其 CreatureDataId，否则返回 undefined */
private GetLocalPlayerCreatureDataIdInRange(rangeEntityHandle: EntityHandle): number | undefined {
    const rangeComp = rangeEntityHandle.GetComponent(EComponent.EtRangeComponent);
    if (!rangeComp) { return undefined; }
    const localHandle = ActorUtils.GetEntityHandleByActor(Global.BaseCharacter);
    if (!localHandle) { return undefined; }
    const creatureDataId = localHandle.CreatureDataId;
    return rangeComp.IsCreatureInClientRange(creatureDataId) ? creatureDataId : undefined;
}

3. 倒计时流程

private StartCountdown(): void {
    if (this.IsRespawning || !this.DataComp?.BoundaryCountdownCondition) { return; }
    this.CurrentCountdown = this.DataComp.BoundaryCountdownCondition.CountdownTime;
    this.CachedWarningText = this.ResolveText(TidWarningText, EdTidWarningText);

    // 立即显示初始秒数，避免第一次tick先自减导致首帧少显示1秒
    const initTipText = `${this.CachedWarningText} ${this.CurrentCountdown}秒`;
    ControllerHolder.BoundaryRespawnTipsController.Show(initTipText);

    this.StopCountdown();                                   // 防重复启动
    this.CountdownTimer = TimerSystem.Forever(() => {
        this.OnCountdownTick();
    }, 1000);
}

4. 核心难点二：多语言文本的三层兜底

/** 取多语言文本：有翻译用翻译，无翻译用 EdTid 编辑器里策划填的中文兜底；
 *  都为空则返回空串由上层兜底 */
private ResolveText(tid: string | undefined, edTid: string | undefined): string {
    if (tid) {
        const text = this.SanitizeText(configMultiTextLang.GetLocalTextNew(tid) || '');
        if (text) { return text; }
    }
    return edTid || '';
}

/** 净化取词结果：剥掉测试地图导出的 test/ 前缀，
 *  并把"查不到"占位串（text not found|...）视为空，交由上层兜底 */
private SanitizeText(raw: string): string {
    if (!raw || raw.startsWith('text not found')) { return ''; }
    return raw.startsWith('test/') ? raw.slice('test/'.length) : raw;
}

5. 核心难点三：双层黑屏编排

5.1 倒计时重生（DoSimpleRespawn）：等重生完成再弹字

/** 倒计时重生：调坠落重生系统（黑屏→传送→取消黑屏），重生完成后再弹一次 Tip。
 *  Tip 必须等重生完成（黑屏已撤）才显示，否则会被中途黑屏劈成"触发前 + 重生后"两段。 */
private DoSimpleRespawn(respawnText: string): void {
    this.CleanupRebornCallback();

    this.OnRebornCompletedCallback = (): void => {
        this.CleanupRebornCallback();       // 一次性回调：自摘
        this.IsRespawning = false;
        this.IsInBoundary = false;
        // 重生完成、黑屏已撤，此时才弹一次文本，避免被黑屏劈成两段
        if (respawnText) {
            ControllerHolder.BoundaryRespawnFullScreenController.ShowOnce(respawnText);
        }
    };
    EventSystem.Add(EEventName.FallingRebornCompleted, this.OnRebornCompletedCallback);

    ControllerHolder.FallingRebornController.TriggerFallingReborn(
        baseCharacter, BoundaryRespawnTipsConstants.FallingRebornRuleId);
}

5.2 坠落区域（DoFallZoneRespawn）：五步黑屏接力

坠落区域必须先让玩家看清文字再传送（因为他不知道自己为什么被送走）， 所以要在主黑屏之前先垫一层低层黑屏。方法头注释直接写了完整编排：

5.3 UI 层级关系（必须记住）

/** 触发位移前的黑屏+文字预览时长（毫秒）。
 *  注意：Tip 是 Float 层，FallingRebornController 的主黑屏挂在 CG 层会盖住 Float，
 *  所以玩家只能在"主黑屏起来前"的这段窗口里看到文字，窗口要足够长。 */
public static readonly PreTeleportBlackScreenMs = 2500;

6. 清理路径：三个资源必须成对释放

protected override OnEnd(): boolean {
    this.StopCountdown();                          // ① 倒计时 Timer
    ControllerHolder.BoundaryRespawnTipsController.Hide();
    this.ClearPreTeleportTimer();                  // ② 预览延时 Timer
    this.CloseLowLayerBlackScreenIfNeeded();       // ③ 低层黑屏（最危险）
    this.CleanupRebornCallback();                  // ④ 全局事件回调
    this.UnregisterRangeEvents();                  // ⑤ 所有范围盒事件 + Pending + EntityInitialized
    this.UnregisterStateChangeEvent();
    return true;
}

6.1 UnregisterRangeEvents 的完整性

private UnregisterRangeEvents(): void {
    if (this.IsWaitingEntityInitialized) {              // 全局监听
        this.IsWaitingEntityInitialized = false;
        EventSystem.TryRemove(EEventName.EntityInitialized, this.HandleEntityInitialized);
    }
    this.PendingBoundaryRangeIds.clear();               // 待办集合
    this.PendingFallZoneIds.clear();

    for (const entityHandle of this.BoundaryRangeEntityHandles) {   // 已注册的 handle
        EventSystem.TryRemoveWithTarget(entityHandle, OnEntityEnterClientRange, ...);
        EventSystem.TryRemoveWithTarget(entityHandle, OnEntityLeaveClientRange, ...);
    }
    this.BoundaryRangeEntityHandles.clear();
    // FallZone 同理 ...
}

注意为什么要自己维护 BoundaryRangeEntityHandles 这个 Set： 配置里的是 PrefabDataId，取消注册需要的是 EntityHandle。 如果 OnEnd 时再去 GetEntityHandleByLevelEntityInstanceId 反查， 实体可能已经被销毁 → 拿不到 handle → 监听泄漏。 所以注册时就存下 handle 引用。

7. 隐藏态处理

/** 当前实体是否处于隐藏态。隐藏态时整个重生组件功能关闭 */
private IsHidden(): boolean {
    return this.SceneItemCompInternal?.SceneItemCurrentState === entityHiddenTagName;
}

private readonly HandleOnSceneItemStateChange = (oldTag, newTag): void => {
    if (newTag?.TagNameString === entityHiddenTagName) {
        this.ResetCountdown();          // 立即停倒计时 + 收 Tip
        this.IsInBoundary = false;
    }
};

IsHidden() 在 5 个地方被检查：4 个 overlap handler + 每次 tick。 为什么不只靠状态变更事件？因为防御式编程： 状态变更事件可能因为注册时机问题漏收，每次 tick 再查一遍代价可忽略。

8. 常见修改场景

8.1 改倒计时时长

不改代码。策划在编辑器里改 CountdownTime。

8.2 加一种新的重生条件（比如「血量低于 X」）

8.3 排查「边界重生不触发」

9. 面试怎么讲