传送点

场景里那些可交互的传送水晶/传送门。本模块管的是解锁状态与表现， 真正的位移交给 ① 传送模块。 核心难点是：解锁状态不能用服务器的实体 State——那是全服玩家共用的。

1. 模块定位

1.1 三个可分离的关注点

2. 配置表 Teleporter

FlatBuffers 自动生成，源文件 c.传送.xlsx，表名 Teleporter， 生成到 Src/Core/Define/Config/Teleporter.ts。只有 4 个字段：

3. 解锁状态：三条数据来源

这是本模块最容易漏的地方——解锁数据有三个入口，改逻辑时要全部覆盖。

3.1 关键设计：不能用服务器 State

// 值得注意的是，传送点解锁的表现不能根据服务器 State，
// 因为 State 是全部玩家共用的，
// 所以需要通过玩家个人解锁存档，去设置本地 State
const isUnlock = ControllerHolder.SceneItemController
    .CheckTeleportIsUnlocked(this.DataComp!.TeleporterId);

3.2 解锁的实现

/** 已解锁的传送点集合 */
private readonly UnlockTeleportIdSet: Set<number> = new Set();

/** 解锁传送点 */
public UnlockTeleport(teleportId: number): void {
    if (!this.UnlockTeleportIdSet.has(teleportId)) {   // 幂等：三个来源可能重复解锁同一个
        this.UnlockTeleportIdSet.add(teleportId);
        Log.Info(ELogModule.Level, ELogAuthor.TJH, '[传送点] 解锁传送点', ['TeleportId', teleportId]);
        EventSystem.Emit(EEventName.OnTeleportUnlocked, teleportId);   // 通知表现层刷新
    }
}

幂等设计很重要：三条来源可能对同一个传送点重复解锁， 不做 has 判断就会重复 Emit 事件，导致表现层重复刷新。

4. 表现层 EtTeleportComponent

实体侧 ECS 组件，62 行。职责只有一件事：按解锁与否切 LevelTag。

@RegisterComponent(EComponent.EtTeleportComponent)
export class EtTeleportComponent extends EntityComponent {
    public DataComp: $Undefinable<ITeleportComponent> = undefined;

    protected override OnStart(): boolean {
        const prefabDataId = this.EntityHandle!.PrefabDataId;
        const entityData = EntityInterfaceHelper.GetCompleteEntityData(prefabDataId);
        if (!entityData) { return false; }
        this.DataComp = getComponent(entityData.ComponentsData, EComponentData.TeleportComponent);
        if (!this.DataComp) { return false; }
        EventSystem.Add(EEventName.OnTeleportUnlocked, this.HandleOnTeleportUnlocked);
        this.RefreshIsUnlocked();      // 首次立刻刷一次（可能实体创建时已经是解锁态）
        return true;
    }

    /** 刷新是否解锁 */
    private RefreshIsUnlocked(): void {
        const levelTagComp = this.GetComponent(EComponent.LevelTagComponent);
        if (levelTagComp) {
            const isUnlock = ControllerHolder.SceneItemController
                .CheckTeleportIsUnlocked(this.DataComp!.TeleporterId);
            if (isUnlock) {
                levelTagComp.ChangeLevelTagByClient(
                    GameplayTagUtils.GetTagIdByName('关卡.Common.数字状态.状态2')!);
            } else {
                levelTagComp.ChangeLevelTagByClient(
                    GameplayTagUtils.GetTagIdByName('关卡.Common.数字状态.状态1')!);
            }
        }
    }
}

5. 发起传送

5.1 唯一调用点

全工程只有一处发起传送点传送：TeleportController.ts:1853

// 期间镜头停在世界画面但角色已经隐身，会出现穿帮帧。
// 这里立刻盖瞬时遮罩兜住到 OnTeleportSelfSCNotify 入口（入口处会复用同一个遮罩，不会重复 Add）。
// 后续流送完成时由 streaming-complete 关掉，loading 场景的 seq 已经接管屏幕，不会留空。
this.OpenSeamlessTransitionMask();
ControllerHolder.SceneItemController.RequestTeleportByEntityPrefabDataId(
    ModelManager.TeleportModel!.TeleportPointId,
);
this.EndTeleportUp(Global.PlayerEntity);

5.2 RequestTeleport 实现

/** 传送点，请求传送 */
public RequestTeleport(teleportId: number): void {
    if (!teleportId || teleportId <= 0) {                    // 参数防御
        Log.Warn(..., '请求传送被拦截：teleportId 非法', ['teleportId', teleportId]);
        return;
    }
    const playerEntity = Global.PlayerEntity;
    if (!playerEntity) { return; }

    ModelManager.GameModeModel!.IsTeleporting = true;      // 全局态：屏蔽其它交互

    const teleportCsReq = new Nami.Protocol.WorldTeleportCSReq();
    teleportCsReq.teleportId = teleportId;
    Log.Info(ELogModule.Net, ELogAuthor.ZZB,
        '传送-发包 WorldTeleportCSReq(23707)', ['teleportId', teleportId]);

    Net.Call(ERequestMessageId.WorldTeleportCSReq, teleportCsReq, (response) => {
        ModelManager.GameModeModel!.IsTeleporting = false;   // 无论成败都复位
        Log.Info(ELogModule.Net, ELogAuthor.ZZB, '传送-收包 WorldTeleportCSRsp',
            ['teleportId', teleportId], ['retcode', response?.retcode]);
        if (response!.retcode !== Nami.Protocol.Retcode.RET_SUCC) {
            ConfigManager.ErrorCodeConfig!.GetTextByErrorId(response!.retcode);  // 弹错误提示
            Log.Info(..., '请求传送失败', ['retcode', response!.retcode]);
        }
    });
}

6. 地图标记 TeleportMarkItem

export class TeleportMarkItem extends MarkItemBase {
    // 按地图类型切不同资源：罗盘用小图标，大地图用完整图标
    public get MarkViewResId(): string {
        return this.MapType === EMapType.Compass
            ? 'UiItem_WarpGateCompass'
            : 'UiItem_Teleport';
    }

    // 解锁态转发给权威持有者，自己不缓存
    public get IsUnlocked(): boolean {
        return ControllerHolder.SceneItemController
            .CheckTeleportIsUnlockedByEntityPrefabDataId(this.MarkConfig!.EntityConfigId);
    }

    public GetMapMarkTypeName(): string { return 'Map_Mark_Teleport'; }
}

7. 最近传送点检索

/** 获取距离坐标最近的已解锁的传送点 */
public FindNearestTeleporterPrefabDataId(location: Readonly<Vector>): $Undefinable<number> {
    // 遍历 UnlockTeleportIdSet
    // 用 configTeleporterById 查配置
    // 只在 curMapPath === teleporterMapPath（同一 WP）的传送点中比较
    // 按 Size2D() 找最近 —— 注意是 2D 距离，忽略高度差
}

典型用途：坠落重生 / 边界重生找回城点、UI 显示「最近传送点」。

8. 常见修改场景

8.1 加一个新传送点

8.2 改解锁表现（比如加个解锁动画）

改 EtTeleportComponent.RefreshIsUnlocked()。注意它会被两处调用： OnStart（初始态）和 HandleOnTeleportUnlocked（解锁事件）。 初始态时不应该播解锁动画——玩家进图时已解锁的传送点不该重新播一遍。 所以要加参数区分「首刷」和「事件触发」。

8.3 排查「传送点该亮没亮」

9. 面试怎么讲