副本结算流程

副本打完之后那段「镜头推进 → MVP 特写 → 全家福 → 数据面板」的完整演出。 八个模块里代码量最大、异步编排最复杂的一个：单 Controller 1435 行， 横跨 LevelSequence、程序相机、ECS 实体隐藏、UI 展台 Proxy、换装异步回调、DataTable 配置六个子系统。 本页把三个阶段拆开讲透，并把源码注释里沉淀下来的十来个坑逐个还原。

1. 模块定位与三阶段总览

1.1 三个阶段

1.2 文件职责表

1.3 事件名汇总

2. 入口 OnStart：三道校验与 SettlementReady 语义

/** OnStart 校验通过（本副本有结算表现）才为 true，
    false 时 MVP 界面只走倒计时不做任何 3D 表现 */
private SettlementReady = false;

3. 阶段1：相机 Tween 推镜（已关闭 / 代码保留）

3.1 数据结构

interface ISettlementCameraSegment {
    CamTarget: UE.Vector;              // 该段终点位置（世界偏移）
    TargetRot: UE.Rotator;             // 该段终点旋转
    Duration: number;                 // 段时长（秒）
    CamCurve: UE.CurveVector | undefined;  // 三轴各自的缓动曲线
}

配置来源是 DataTable，行结构 SSettlementCameraConfig，按角色 Id 取行：

readonly RoleId: number /* @cpp:int */;
readonly CameraOffset: Vector;
readonly CameraRotationOffset: Rotator;
readonly TweenDuration: number /* @cpp:float */;
readonly CameraPosCurve: UE.CurveVector | undefined;
readonly Seq2: ISoftObjectPtr<UE.LevelSequence>;
readonly MvpShowButtonTime: number /* @cpp:float */;

DungeonModel.GetDungeonSettlementAllData() 遍历 WorldConfig.GetDungeonSettlementDataTable() 的 RowNames， 按 info.RoleId 建 Map 缓存，OnInit 预热、OnClear 置 undefined。 源码注释：「相机配置按角色 ID 取行，新结构无 Skill 字段，直接用 RoleId 作 key」。

3.2 倒序推镜

// 相机初始落在最后一段，从 lastIndex - 1 逐段倒推到第 0 段（MVP）
this.TweenSegmentIndex = lastIndex - 1;

3.3 逐帧采样

private OnCameraTweenTick(deltaMs: number): void {
    if (this.TweenHolding) { /* 段末定格 TweenHoldDuration 秒 */ }

    const t = Math.min(elapsed / segment.Duration, 1);
    // CurveVector 三轴各取一条曲线，按轴分别插值 —— X/Y/Z 可以有不同缓动
    const camProgress = segment.CamCurve.GetVectorValue(t);
    loc.X = DungeonSettlementController.Lerp(prev.X, target.X, camProgress.X);
    // ... Y / Z 同理
    const rot = UE.KismetMathLibrary.RLerp(prevRot, targetRot, t, true);
    actor.K2_SetActorLocationAndRotation(loc, rot, false, ..., false);
}

private static Lerp(from: number, to: number, alpha: number): number {
    return from + (to - from) * alpha;
}

3.4 一个容易想歪的取舍：不叠加站位朝向

// 美术按角色默认朝向调好机位并复制相对值，这里直接当世界偏移/世界旋转用，
// 不叠加站位朝向，避免站位 Yaw 非0 时把正面机位转成侧面（所见即所得）

4. 阶段2：Seq2 MVP 特写（黑屏内异步编排）

4.1 全流程

/**
 * MVP 特写准备：隐藏实体 → 加载 Seq2 → 换装 → 定格首帧 → 切相机，
 * 全程在 MvpView 的黑屏内完成。
 * 由 DungeonMvpView.OnBeforeStartAsync await，完成后才关黑屏，再由 PlayMvpCloseUp 播放。
 */
public async PrepareMvpCloseUpAsync(): Promise<void> { ... }

4.2 双层超时兜底

/** MVP 准备阶段的一次性结束回调，OnEnd 提前结束时调用，
    避免界面永远 await 在黑屏里 */
private MvpPrepareFinish: (() => void) | undefined = undefined;

4.3 PlayMvpCloseUp 与 proxy 隐藏时机

if (this.Seq2Ready && actor valid) {
    this.LevelSequencePlayer2?.Play();
        // Seq2 真正 Play 之后再隐藏 proxy，避免出现"无角色"空窗导致描边特效闪断
    for (const proxy of this.ProxyActors) { proxy.SetRoleVisible(false); }
} else if (this.Gm) {
    this.OnDungeonSettlementCloseUpEnd();   // GM 模式没 Seq2，直接跳阶段3
}
EventSystem.Emit(EEventName.DungeonSettlementMvpCloseUp);

顺序是 先 Play 再隐藏，差一帧就会出现「旧 proxy 已消失、Seq2 角色还没显示」的空窗， 描边（CustomDepth）后处理会闪断一下。

4.4 Seq2 结束的收尾

player2.OnFinished.Add(() => {
    // Seq2 结束 = 阶段2 结束，进入阶段3（全屏 UI）；销毁 3D proxy 避免 UI 阶段穿帮
    this.ClearProxyActors();
    if (this.Gm) { this.OnDungeonSettlementCloseUpEnd(); }
});

5. 阶段3：Seq3 全家福

5.1 基准点：X/Y 与 Z 分别取

// X/Y 取 MVP 站位作排中心，Z 取结算基准地面（避免叠加 marker 抬高导致浮空）
const mvpLoc = this.MarkerActors.get(0)?.GetLocation() ?? this.GetSettlementSpawnLocation();
const groundZ = this.GetSettlementSpawnLocation().Z;
const baseLocation = new UE.Vector(mvpLoc.X, mvpLoc.Y, groundZ);

marker 的 Z 已经加过 SettlementZOffset = 10（防入地），直接整个复用会二次抬高。 所以只借 X/Y、Z 回到原始基准。

5.2 站位算法

// 1. 按体型半径累加中心距
centers[i] = centers[i - 1] + radii[i - 1] + radii[i] + formationSpace;
//    formationSpace = configCommonParamById.GetFloatConfig('team_formation_space')
//    radii 缺省时用 DefaultBodyRadius = 50

// 2. 整体居中

// 3. 首尾沿 forward 反方向后压 radii[index]，避免一字平直

5.3 GetSettlementPositionOrder：站位序 ↔ 成员序

// 排序键：CharacterBodyType 升序 → Id → a.Index - b.Index
// 最后一个键的作用：同角色同体型时按成员序定序，保证排序稳定、站位与成员一一对应

// 再从中间往两边铺：
let left = Math.floor(n / 2) - 1;
let right = Math.floor(n / 2);
// 偶数下标往右、奇数往左 → 体型小的站中间，大的分居两侧

5.4 贴地射线 TraceGroundZ

private TraceGroundZ(x: number, y: number, baseZ: number): number {
    // 从 baseZ + Seq3GroundTraceUp(300) 向下打 Seq3GroundTraceDown(1000)
    // 命中 → ImpactPoint.Z + SettlementZOffset(10)
    // 未命中 → baseZ + SettlementZOffset(10)
}

结算点位是配表填的固定坐标，但地形可能有坡。每个人独立打一条射线贴地， 避免一排人有的埋进地里有的浮空。射线起点抬高 300 是为了兼容站位点略低于地面的情况。

5.5 相机：从「配置半径估算」到「真实包围盒」的四连改

UE.GameplayStatics.GetActorArrayBounds(actorArray, false, originRef, extentRef);

// 把包围盒 extent 投影到相机右方向上，得到画面里的真实半宽
const halfWidth  = Math.abs(extent.X * rightDir.X) + Math.abs(extent.Y * rightDir.Y) + horizontalMargin;
const halfHeight = extent.Z;

// CameraFov(60) 是水平 FOV，垂直 FOV 要按 16:9 换算
const halfHorizontalFovRad = MathUtils.DegToRad * (CameraFov * 0.5);
const halfVerticalFovRad   = Math.atan(Math.tan(halfHorizontalFovRad) / CameraAspectRatio);

const distanceByWidth  = halfWidth  / Math.tan(halfHorizontalFovRad);
const distanceByHeight = halfHeight / Math.tan(halfVerticalFovRad);
const distance = MathUtils.Clamp(Math.max(distanceByWidth, distanceByHeight),
                              CameraMinDistance(120), CameraMaxDistance(2500));

5.6 留白用「一个身位」而不是比例系数

const avgBodyRadius = radii.reduce((a, b) => a + b, 0) / radii.length;
// 留白按"一个身位"取平均体型半径，避免用比例系数——
// 人数越多总宽度越大，比例留白会被同步放大导致人多时镜头明显偏远（8人小体型实测过远）

比例留白（halfWidth *= 1.2）看起来更「自适应」，实际是错的： 8 个小角色总宽 800，20% 留白就是 160；2 个角色总宽 200，20% 只有 40。 观感上人越多画面越空。绝对留白才符合直觉。

5.7 两个相机细节

rot = UE.KismetMathLibrary.FindLookAtRotation(camLoc, lookAtLoc);
cameraComponent.FieldOfView = 60;
cameraComponent.bConstrainAspectRatio = false;
// CameraActor 默认按 16:9 约束画幅，宽屏下会加左右黑边，这里关掉铺满视口

5.8 SwitchCamera3 三级兜底

6. 数据层 DungeonSettlementData

6.1 MVP 判定

public IsMvp(): boolean {
    return cfg.DataType === EDungeonEvaluationDataType.None;
}

不是「伤害最高」，而是服务器下发的评价条目里带了一条 DataType === None 的称号。 评价体系是配置化的（最高输出 / 最抗揍 / 最佳辅助…），MVP 是其中特殊的一条：它没有对应的数值维度。

6.2 排序

@profiled()
public AnalyzeData(): void {
    // 累加 Total / Max（伤害、承伤、治疗）
    // MembersData[0] 一定是 MVP
    // 其余按加入时间倒序（因为站位是倒着站的）
    if (!hasMvp) { Log.Warn(..., ELogAuthor.QCJ, '没有mvp数据'); }
}

构造 DungeonSettlementMemberData 时还会对 evaluationIdList 按 EvaluationType → EvaluationLevel 排序，保证 UI 上称号顺序稳定。 派生指标 GetDamagePercent / GetDps / GetDtps / GetHps 都在这层算好，View 只负责显示。

6.3 点赞双向索引

ClickLike: Map<number, Set<number>>;   // 被赞 uid → 点赞者 uid 集合
GetAllPlayerUidExceptSelf();                 // 排除自己（不能给自己点赞）

用 Map<number, Set<number>> 而不是数组，一次 has 就能判断「我赞过没」， 避免每帧 UI 刷新时做 O(n) 查找。

7. 实体隐藏与恢复：HiddenEntities 自维护集合

/**
 * 结算期间被本控制器隐藏的实体集合。
 * 现用现拿（hide/show 各调一次 GetAllEntities）会出现
 * "hide 时存在、show 时已不在列表"的实体永远卡在隐藏状态，
 * 因此自己维护这个集合，恢复时只遍历它，不再二次依赖 GetAllEntities。
 */
private readonly HiddenEntities: Set<Readonly<EntityHandle>> = new Set();

@profiled('SetActiveAllPlayers.GetAllEntities')
public SetActiveAllPlayers(enable: boolean): void {
    if (this.EntityActiveState === enable) { return; }   // 幂等

    if (!enable) {
        // 隐藏：取一次 GetAllEntities 全集 → SetActorVisible(false) → 存进集合
        // 同时挂 EntityCreated / EntityRemoved 两个监听
    } else {
        // 显示：先摘监听 → 只遍历 HiddenEntities → clear
    }
}

8. 外观获取：快照 vs 实时的双层回退

// 组队信息是进副本时的快照，副本内换装不刷新它，优先读实体上的实时外观
private GetAvatarInfo(index: number) {
    const snapshot = FashionUtils.ConvertToAvatarInfo(memberData.PlayerInfo.roleActiveFashion);
    return this.GetLiveAvatarInfo(this.GetMemberUid(index), snapshot[0]) ?? snapshot;
}

private GetLiveAvatarInfo(uid: number, snapshotRoleId: number) {
    for (const entity of EntityInterfaceHelper.GetAllEntities()) {
        if (entity.OwnerPlayerId !== uid) { continue; }
        const comp = entity.GetComponent(CreatureDataComponent)
                        ?.ServerCompData.Get('roleFashionComp');
        // 同一玩家的召唤物等实体没有外观组件，继续找角色实体
        if (!comp) { continue; }
        // 副本内可能切过角色，优先取与快照同角色的那份，避免把 MVP 换成别的角色
        return comp.roleActiveFashionList?.find(f => f.roleConfigId === snapshotRoleId)
               ?? comp.roleActiveFashion;
    }
}

9. UiSceneRoleActorProxy 的两个坑

9.1 SetModelStateNoTween

// 结算角色 spawn 在副本世界（非UI展台场景），走 SetModelStateNoTween 跳过相机Tween，
// 避免刷 "找不到对应的Actor(Tag=RoleCase/SceneCase/CameraTween)" 报错；相机由本控制器程序控制。
actorProxy.SetModelStateNoTween(UiModelStateNames.DungeonSettlement);

UiSceneRoleActorProxy 本来是给 UI 展台（角色界面、抽卡）用的， 默认会去场景里找 RoleCase / CameraTween 这些 Tag 的 Actor。 结算是在副本世界里 spawn，这些 Actor 不存在 → 每帧刷错误日志。 NoTween 版本只设模型状态、不碰相机。

9.2 ProxyActorByUid

/** 玩家 uid → proxy：ProxyActors 是站位序，UI 是成员序，两边只能靠 uid 对齐 */
private readonly ProxyActorByUid: Map<number, UiSceneRoleActorProxy> = new Map();

点赞特效 GetProxyActorByUid(tarUid)?.AddMaterialControllerEffect(FxFlowLight, ContextFlowLight)、 UI 飘字定位 GetProxyActorLocationByUid(uid) 都走这张表。

10. 两个 UI 界面

10.1 DungeonMvpView（阶段2）

protected MvpShowButtonTime = 3 * SecondToMillisecond;   // 3s 后出「结算」按钮
protected SkipPressTime     = 2 * SecondToMillisecond;   // 长按 2s 跳过
// MVP动画保底时长，暂定60秒，防止没有 DungeonSettlementMvpCloseUp 事件，导致卡流程
protected MaxShowTime       = 60 * SecondToMillisecond;

// 是否已结算过：CloseMe 为异步关闭，界面真正销毁前仍会继续 OnTick，
// 没有这个标记会导致保底逻辑在关闭中的界面上反复重触发，无限重复结算
protected HasSettled = false;

10.2 DungeonSettlementView（阶段3）

OnBeforeStartAsync: EventSystem.Emit(EEventName.DungeonSettlementTeamActive, true);
OnBeforeDestroy:    EventSystem.Emit(EEventName.DungeonSettlementTeamActive, false);

Controller 侧对这个事件的响应：

private OnDungeonSettlementTeamActive(active: boolean): void {
    for (const proxy of this.ProxyActors) { proxy.SetRoleVisible(active); }
    if (active) { this.SwitchCamera3(); }
    else { this.LevelSequencePlayer2?.Stop(); CameraManager.ReleaseCamera(...); }
    this.SetActiveAllPlayers(!active);   // 注意取反
}

其它要点：

• OnDungeonClickLike → GetProxyActorByUid(tarUid)?.AddMaterialControllerEffect(FxFlowLight, ContextFlowLight)
• OnClickBtnClose → RequestLeaveCurrentDungeon()
• StartTipsTimer 用 info.countdown.stateEndTimeMs 算剩余， LguiUtil.SetLocalTextNewNamed(TxtTips, 'SettlementRemainTimeTips', {...})
• CloseMe 里有被注释掉的 DungeonEndGameTipsView，注释「TODO: 策划要求先暂时隐藏该窗口 2026-07-28」

11. OnEnd 清理十一步

12. 常量速查表

全部在 DungeonSettlementControllerConstants，每条都带中文 JSDoc。

另有 DungeonSettlementDefineConstants：

MarkerSpawnMax            = 8;             // 结算点位数量
DungeonSettlementModelId  = 20100201;      // 结算关卡ID
PathDungeonSettlementSeq  = '/Game/Aki/Scene/InteractionLevel/Prefab/DungeonSettlement/';
FxFlowLight               = '.../DA_FX_MCTRL_Group_FlowLight_EndGame';
ContextFlowLight          = 'FlowLightEndGameFx';

13. Bug 卡集合

14. 常见修改场景

14.1 给某个角色配 MVP 特写

14.2 重新启用阶段1 相机 Tween

去掉 OnStart 里两行注释、删掉两个函数上的 @ts-expect-error。 但必须同时解决角色穿帮——阶段1 spawn 的那排 marker 角色会在 Seq2 特写时出现在画面里。 两个方向：① 阶段2 开始前 ClearProxyActors()； ② 阶段1 复用 Seq2 的角色，不单独 spawn。

14.3 加一个新的结算数据维度（比如「治疗量」）

14.4 排查表

15. 面试怎么讲