爬塔

按武将（角色）分塔、逐副本挑战、每副本按条件拿 1/2/3 星的长线玩法。 本页的重点是星级系统：从宇宙编辑器行为树里配达成条件， 到局内 HUD 实时点亮，再到局外历史最佳 starMask 位掩码存档与展示， 以及三条协议（20532 / 20533 / 37503）的接入。

1. 模块构成

2. 星级系统全链路

3. 配置层：TowerStarConfig Scheme

3.1 三层结构

/** 单颗星：由一个子任务条件组成，完成即得这颗星 */
export interface ITowerStarItem {
    /** 星级描述-编辑器输入文本（必填） */
    EdTidDesc: string;
    /** 星级描述-多语言TID（副本内星级UI显示，客户端按档读取） */
    TidDesc: string;
    /** 子任务条件（与 ChildQuest 同源） */
    SubQuests: TChildQuestCondition;
}

/** 爬塔星级配置：上层封装一层，避免未来加新字段（如难度系数 / 提示文案）时改格式 */
export interface ITowerStarConfig {
    /** 星级列表，按顺序对应 1/2/3... 星 */
    Stars: ITowerStarItem[];
}

3.2 两套 scheme：编辑用真实、校验用空壳

// levelPlayScheme（通用玩法树）里：
// 爬塔星级：校验侧用空壳(IgnoreAllFields)取消检查，
// 编辑侧由 levelPlayDungeonScheme 覆盖为真实配置 scheme
TowerStarConfig: createObjectScheme<ITowerStarConfig>({
    Name: 'TowerStarConfig',
    Optional: true,
    IgnoreAllFields: true,
    Fields: {} as never,
}),

// levelPlayDungeonScheme（副本主控树）里覆盖成真的：
export const levelPlayDungeonScheme = createObjectScheme<ILevelPlay>({
    Fields: {
        ...levelPlayScheme.Fields,
        Tree: behaviorTreeScheme,
        TowerStarConfig: towerStarConfigScheme,   // 真实 scheme
    },
});

3.3 EdTid + Tid 双字段

EdTidDesc: createEdTidTextScheme({
    CnName: '星级描述(EdTid)',
    Tip: '该档星级达成条件的描述，显示在副本内星级提示UI（必填）',
    CreateDefault: () => '完成条件',
    IsDefaultCreate: true,
    IsAlwaysShow: true,
}),
TidDesc: createTidTextScheme({
    CnName: '星级描述(Tid)',
    TextKeyPrefix: 'TowerStarDesc',
}),

这是宇宙编辑器的通用模式：策划填 EdTid（中文原文），导表工具扫出来生成 Tid（多语言 key）。 运行时优先用 Tid 查译文，查不到回退 EdTid。
边界重生模块踩过的坑正好相反——那边 EdTid 运行时不导出， 兜底代码是死的；这里客户端两个字段都能拿到，回退是真实生效的。

4. 协议清单

4.1 局内（实时星级）

4.2 局外（历史最佳 + 任务 + 排行）

5. starMask 位掩码

5.1 语义

/** 场外历史最佳星级位掩码：按武将 roleId + 副本 dungeonId 取，
    第 i 位=第 i 档达成；无记录返回 0 */
public GetDungeonBestStarMask(roleId: number, dungeonId: number): number

5.2 统计已点亮星数：封顶防脏数据

/** 统计 starMask 已点亮星数，上限 TowerMaxStars 防服务器脏数据超配置档数 */
private CountStarsFromMask(starMask: number): number {
    let starCount = 0;
        for (let idx = 0; idx < this.TowerMaxStars; idx++) {
        if ((starMask & (1 << idx)) !== 0) { starCount++; }
    }
    return starCount;
}

// TowerMaxStars 来自公共参数表，缺省 3
this.TowerMaxStars = configCommonParamById.GetIntConfig('tower_max_stars') ?? 3;

5.3 塔维度累计

public GetRoleOwnTowerStars(roleId: number, towerId: number): number {
    for (const recordInfo of roleRecordInfo.bestRecords) {
        const towerInfoCfg = ConfigManager.TowerClimbConfig!
            .GetTowerClimbInfoConfigByDungeonId(recordInfo.dungeonId);
        if (towerInfoCfg && towerInfoCfg.TowerId === towerId) {
                    // 按 starMask 逐档累计，不能按"打过即满星"算
            ownTowerStars += this.CountStarsFromMask(recordInfo.starMask);
            detailList.push(`${recordInfo.dungeonId}=mask${recordInfo.starMask}/${dungeonStars}星`);
        }
    }
    Log.Debug(..., '爬塔星级-局外取塔已得星数GetRoleOwnTowerStars',
        ['ownTowerStars', ownTowerStars], ['明细', detailList.join(',')]);
}

public GetTotalTowerStars(towerId: number): number {
    return towerInfoCfgList.length * this.TowerMaxStars;   // 副本数 × 每副本档数
}

注意日志里带了「明细」字段：2010=mask5/2星,2011=mask7/3星。 线上出「星数对不上」的问题时，一行日志就能看出是哪个副本的 mask 不对， 不用逐个副本去查。这是一条值得固定下来的习惯—— 聚合数值的日志一定要附明细。

5.4 局内当前掩码：两个来源做 OR

/** 当前副本已达成星级掩码：20533 只更新单档不刷 starsMask，
    故按 starList 自算，并 OR 通关下发的 towerStarInfo 兜底 */
public GetCurrentTowerStarMask(): number {
    let mask = 0;
    const sources = [this.TowerStarInfo, this.CurrentDungeonInfo?.towerStarInfo];
    for (const info of sources) {
        if (!info) { continue; }
        mask |= info.starsMask ?? 0;
        for (const star of info.starList ?? []) {
            if (star.isTrue) { mask |= 1 << star.idx; }
        }
    }
    return mask;
}

6. 数据层

6.1 局内：UpdateTowerStarProgress

/** 单档星级实时更新；找不到 idx 直接 push 进列表 */
public UpdateTowerStarProgress(progress: Nami.Protocol.ITowerStarProgress): void {
    Log.Warn(..., '爬塔星级-单档更新UpdateTowerStarProgress',
        ['idx', progress.idx], ['isTrue', progress.isTrue],
        ['endTimeMs', MathUtils.LongToNumber(progress.condition?.waitTimeData?.endTimeMs ?? 0)]);

    if (!this.TowerStarInfo) {   // 全量还没到就先来了增量
        this.TowerStarInfo = { starList: [progress] } as Nami.Protocol.IDungeonTowerStarInfo;
        EventSystem.Emit(EEventName.DungeonTowerStarChange);
        return;
    }
    const i = this.TowerStarInfo.starList.findIndex((s) => s.idx === progress.idx);
    if (i >= 0) { list[i] = progress; } else { list.push(progress); }
    EventSystem.Emit(EEventName.DungeonTowerStarChange);
}

三条防御：全量未到先建 Model、idx 不存在就 push、 每条路径都 Emit 事件（早期版本「提前 return」那条漏了 Emit，导致偶发首档不亮）。

6.2 局外：UpdateTowerClimbBestRecord

/** 单副本最佳记录增量更新（37503）：无该武将记录先建，已有同 dungeonId 则整条替换 */
public UpdateTowerClimbBestRecord(roleId, record): void {
    let roleRecordInfo = this.TowerClimbRecordInfoMap?.get(roleId);
    if (!roleRecordInfo) {
        roleRecordInfo = new Nami.Protocol.TowerClimbRoleRecordInfo({ roleId, bestRecords: [] });
        this.TowerClimbRecordInfoMap?.set(roleId, roleRecordInfo);
    }
    const index = roleRecordInfo.bestRecords.findIndex((r) => r.dungeonId === record.dungeonId);
    if (index >= 0) { roleRecordInfo.bestRecords[index] = record; }
    else { roleRecordInfo.bestRecords.push(record); }
}

和局内完全同构：先保证容器存在，再按主键「有则更新、无则插入」。 两处主键不同（局内是 idx，局外是 dungeonId），但模式一致。

6.3 展示数据合并

/** 副本爬塔星级展示项：合并服务器 progress + 行为树多语言文本 */
export interface ITowerStarDisplayItem {
    /** 服务器下发的星级序号（对应行为树 TowerStarConfig.Stars 下标） */
    Idx: number;
    /** 是否已达成该档星级 */
    IsAchieved: boolean;
    /** 多语言 TID（找不到为空串） */
    TidDesc: string;
    /** 编辑器输入的中文原文（多语言未命中时回退显示） */
    EdDesc: string;
}

// 局内：达成来自实时 isTrue
public GetCurrentTowerStarDisplayList(levelId): ITowerStarDisplayItem[] {
    if (!info?.starList || info.starList.length === 0) { return []; }
    const configItems = this.GetCurrentTowerStarConfigItems(levelId);
        // 只认行为树配了的档（服务器可能多下发或乱序），按 idx 升序对齐 1/2/3 星
    return info.starList
        .filter((p) => !configItems || (p.idx >= 0 && p.idx < configItems.length))
        .sort((a, b) => a.idx - b.idx)
        .map((p) => ({ Idx: p.idx, IsAchieved: Boolean(p.isTrue),
                     TidDesc: configItems?.[p.idx]?.TidDesc ?? '',
                     EdDesc:  configItems?.[p.idx]?.EdTidDesc ?? '' }));
}

// 局外：达成来自 starMask 逐位
public GetTowerStarDisplayListByDungeon(dungeonId, roleId): ITowerStarDisplayItem[] {
    const levelId = configDungeonById.GetConfig(dungeonId, false)?.LevelConfigId;
    const configItems = this.GetCurrentTowerStarConfigItems(levelId);
    if (!configItems || configItems.length === 0) { Log.Warn(...); return []; }
    const starMask = ModelManager.TowerClimbModel?.GetDungeonBestStarMask(roleId, dungeonId) ?? 0;
        // 以配置为准展开全部档位，未达成的也返回（要显示灰星和条件文本）
    return configItems.map((cfg, idx) => ({
        Idx: idx,
        IsAchieved: (starMask & (1 << idx)) !== 0,
        TidDesc: cfg?.TidDesc ?? '', EdDesc: cfg?.EdTidDesc ?? '',
    }));
}

配置来源穿了三层表：

GetCurrentTowerStarConfigItems(levelId):
    levelId → configLevelConfigById → levelConfig.FlowId
           → LevelPlayModel.GetLevelPlayConfig(FlowId)
           → .TowerStarConfig?.Stars

7. 局内 HUD 实时显示

7.1 挂在哪

星级 HUD 没有单独开界面，而是挂在主界面追踪栏 MainUiTaskPanel（任务追踪那一块）里， 和任务列表、爬塔子任务列表共用一个面板。组件索引：

const enum EMainUiTaskType {
    QuestLayout, QuestItem, PnlCopyEntryList, PnlCopyEntry, PnlContent,
    PnlTowerStar,        // 爬塔星级 HUD 容器（非爬塔副本隐藏整块）
    TxtLevelName,        // 爬塔副本名
    TxtTime,             // 实时计时文本
    PnlTowerStarItem,    // 单档模板节点（复制它生成每一档）
    PnlTowerStarList,    // list 容器
}

7.2 动态生成 N 档：三个坑

/**
 * 生成/刷新星级 list（仿 UpdateClimbItemList）：按服务器星级数据，复制 PnlTowerStarItem 模板成 N 档。
 * 已有的复用并更新，多余的隐藏；创建是异步的，靠 IsCreatingStarItems 串行防重复复制。
 */
private UpdateTowerStarList(): void {
    const list = this.GetTowerStarDisplayList();
    if (list.length === 0) { /* 全隐藏 */ return; }
        // 创建未完成时不能再进，否则 ViewList 还是旧长度会把模板重复复制一轮
    if (this.IsCreatingStarItems) { return; }
    if (list.length > this.TowerStarItemViewList.length) {
        void this.CreateTowerStarItemsAsync(list.length);
        return;
    }
    this.ApplyTowerStarList(list);
}

/**
 * 补齐到 targetNum 档，期间屏蔽重入；补齐后用最新数据统一刷一遍。
 * 节点在 CreateTowerStarItem 里同步复制完成故顺序有保证，await 后按序 push。
 */
private async CreateTowerStarItemsAsync(targetNum: number): Promise<void> {
    this.IsCreatingStarItems = true;
    try {
        const tasks: Promise<TowerStarItem | undefined>[] = [];
        for (let i = this.TowerStarItemViewList.length; i < targetNum; i++) {
            tasks.push(this.CreateTowerStarItem());
        }
        const views = await Promise.all(tasks);   // 顺序由 Promise.all 保证
        for (const view of views) { if (view) { view.SetUiActive(true); this.TowerStarItemViewList.push(view); } }
    } finally {
        this.IsCreatingStarItems = false;
    }
        this.ApplyTowerStarList(this.GetTowerStarDisplayList());   // 用最新数据补刷
}

/** 隐藏星级容器下 prefab 预摆的所有静态子节点，只留动态复制出来的 */
private HideTowerStarStaticChildren(): void {
    const parent = this.PnlTowerStarItem?.GetParentAsUIItem() ?? this.PnlTowerStarList;
    const childNum = parent.UIChildren.Num();
    const names: string[] = [];
    for (let i = 0; i < childNum; i++) {
        const child = parent.UIChildren.Get(i);
        names.push(child.GetDisplayName());
        child.SetUIActive(false);
    }
    Log.Warn(..., '爬塔星级-隐藏容器预摆静态节点',
        ['容器', parent.GetDisplayName()], ['子节点数', childNum], ['明细', names.join(',')]);
}

日志里打出了子节点名列表——美术改 prefab 加节点时， 一看日志就知道新加的东西被隐藏了，不用来问「摆的星星为什么不见了」。

7.3 显隐判定：两套标准

/** 是否爬塔星级副本：有服务器下发的星级数据即认为是 */
private IsTowerStarDungeon(): boolean {
    const info = ModelManager.DungeonModel?.GetTowerStarInfo();
    return !!info?.starList && info.starList.length > 0;
}

/** 当前是否爬塔副本：按副本配置查爬塔表，进副本即可判定，不依赖服务器星级下发时机 */
public IsInTowerClimbDungeon(): boolean {
    const dungeonConfigId = this.CurrentDungeonInfo?.dungeonConfigId;
    return ConfigManager.TowerClimbConfig?.GetTowerClimbInfoConfigByDungeonId(dungeonConfigId) !== undefined;
}

// 显隐只由"是否有星级数据"决定，不依赖 CurrentDungeonInfo
// （两者是独立的服务器下发，副本信息可能晚到或缺）
const isTowerDungeon = this.IsTowerStarDungeon();
this.PnlTowerStar?.SetUIActive(isTowerDungeon);

7.4 实时正向计时

// 实时正向计时：从副本开始起每 50ms 刷新
if (this.TowerClimbStartMs === 0) { this.TowerClimbStartMs = Time.ServerTimeStamp; }
this.UpdateTowerTime();
if (!TimerSystem.Has(this.TowerTimeTimer)) {
    this.TowerTimeTimer = TimerSystem.Forever(this.UpdateTowerTime, 50);
}

/** 计算并刷新爬塔实时正向计时文本（分:秒.厘秒） */
private readonly UpdateTowerTime = (): void => {
    const elapsedMs = Math.max(0, Time.ServerTimeStamp - this.TowerClimbStartMs);
    const minutes = Math.floor(elapsedMs / 1000 / 60);
    const seconds = Math.floor(elapsedMs / 1000) % 60;
    const centiseconds = Math.floor((elapsedMs % 1000) / 10);   // 厘秒，两位
    this.TxtTime?.SetText(`${mm}:${ss}.${cc}`);   // 各 padStart(2, '0')
};

8. 星级 UI 组件：两个同构实现

工程里有两个功能几乎一样的星级单档组件，接口签名完全一致：

/** 亮星=达成显隐；文本=多语言译文，未命中则回退编辑器中文原文 */
public UpdateByProgress(isAchieved: boolean, tidDesc: string, edDesc: string): void {
    this.SprStar?.SetUIActive(isAchieved);
        // 多语言命中显译文，未命中回退中文原文（EdDesc）；永不显示 key / 空
    const localized = StringUtils.IsEmpty(tidDesc) ? undefined : TextConfig.GetLocalText(tidDesc);
    this.TxtCondition?.SetText(localized ?? edDesc);
}

9. 塔任务与排行（接口速查）

9.1 任务的两级分类

class TowerClimbDefineConstants {
    public static TowerTaskRoleType = 20;    // 武将维度任务
    public static TowerTaskTowerType = 10;   // 塔维度任务
}

TaskType（一级）+ TaskSubType（二级）。 TowerTaskTypeReg 表把 RoleId / TowerId 映射到 TypeId（= SubType）， 所以「某武将的任务进度」要先查这张注册表拿到 subType，再过滤任务列表。

public GetTowerClimbTaskProgressByRoleId(roleId): ITowerClimbTaskProgress {
    const taskTypeRegCfg = ConfigManager.TowerClimbConfig!.GetTowerClimbTaskTypeRegByRoleId(roleId);
    const roleTaskType = taskTypeRegCfg?.TypeId ?? 0;
    for (const taskInfo of this.TowerClimbTaskInfoList) {
        if (roleTaskType > 0 && taskConfig.TaskSubType !== roleTaskType) { continue; }
        ++taskProgress.TotalNum;
                // 注意：只要不是 UNFINISHED 就算完成（含"已完成待领奖"和"已领奖"）
        if (taskInfo.state !== TOWER_CLIMB_TASK_STATE_UNFINISHED) { ++taskProgress.FinishNum; }
    }
}

9.2 排行榜名次的模糊显示

public GetSelfDisplayRank(selfRank: number): string {
    if (selfRank <= TowerClimbConfig.MaxTopRank) { return `${selfRank}`; }   // 前 N 名显示真实名次
    const rankInfoData = ModelManager.RankModel!.GetRankRankInfoData(RANK_TYPE_TOWER);
        const rankScale = Math.ceil(selfRank / rankInfoData!.TotalCount) * 100;   // 算百分位
    const displayRule = this.TowerRankDisplayRuleList.find(
        (rule) => rankScale >= rule.RankRealMin && rankScale <= rule.RankRealMax);
    return displayRule?.ShowRank ?? `${selfRank}`;   // 显示"前 30%"这类文案
}

前 N 名（MaxTopRank 来自 RankBase 表的 TopN）显示真实名次， 之后按百分位查 RankDisplayRule 显示「前 30%」这种模糊档位。 避免玩家看到「第 128374 名」的挫败感。

10. 常见修改场景

10.1 给一个副本加星级

10.2 改星级上限（3 → 5）

改公共参数表 tower_max_stars。影响两处： CountStarsFromMask 的循环上界、GetTotalTowerStars 的乘数。 代码不用动。但要注意服务器侧也得同步，否则客户端封顶会把服务器给的第 4、5 档截断。

10.3 加一个新的星级达成条件类型

条件走的是 SubQuests: TChildQuestCondition，和普通子任务同源。 所以加条件类型不是爬塔的活，是往 EChildQuest 里加， 爬塔这边自动就能用上。这也是当初把 SubQuests 直接复用 ChildQuest 而不是另起一套的原因。

10.4 排查表

11. 技术债清单

12. 面试怎么讲