框架与分层总纲

这一页是所有模块页的公共前置知识。八大功能模块里出现的每一个基类、每一个生命周期钩子、 每一种注册/注销配对，规则都在这里。看模块页遇到不认识的基类，回到这里查。

1. 技术栈：UE5 + puerts

import * as UE from 'ue';
import type { $Undefinable } from 'puerts';
import { $ref, $unref } from 'puerts';

puerts 把 UE 的 C++ 反射类型全量映射成 TypeScript 声明（ue.d.ts）， TS 里可以直接 new UE.Vector(...)、调 Actor.SetActorLocation(...)。 底层是 V8 引擎，脚本和 C++ 在同一进程内互调。

// 典型的 out 参数调用：GetActorBounds(bOnlyColliding, Origin, BoxExtent)
const origin = $ref(new UE.Vector());
const extent = $ref(new UE.Vector());
actor.GetActorBounds(false, origin, extent);
const box = $unref(extent);   // 必须 unref 才拿得到值

2. 目录分层

Src/
├── Core/            // 引擎无关的基础设施，不含任何业务
│   ├── Framework/   // ControllerBase / ModelBase / ConfigBase 及其 Manager
│   ├── Event/       // 通用事件类（弱引用 + 防重入）
│   ├── Net/         // Net 静态门面 + NetConnection + 协议定义
│   ├── Entity/      // ECS：Entity / EntityComponent / 组件注册
│   ├── Timer/       // TimerSystem 优先队列定时器
│   ├── Config/      // 配置表加载
│   └── Utils/       // 数学 / 字符串 / 命令
├── Game/            // 全部游戏业务
│   ├── Module/      // 116 个功能模块，一个目录一个模块
│   ├── World/       // 实体世界：Entity 组件实现、Model
│   ├── Ui/          // UI 基类与管理器
│   ├── Manager/     // ModelManager / ControllerHolder / ConfigManager
│   ├── LevelGamePlay/ // 关卡玩法、行为树节点执行器
│   └── Common/      // EventDefine / EventSystem
├── UniverseEditor/  // 宇宙编辑器（关卡编辑工具）
│   ├── Interface/   // 纯数据接口，Game 层唯一可 import 的子目录
│   ├── Common/      // 操作定义
│   └── EditorCommon/// Scheme 定义（编辑器 UI 生成规则）
├── Fight/           // 战斗系统
└── Editor/          // 编辑器工具脚本

// ✅ 允许
import type { ITowerStarConfig } from '../../UniverseEditor/Interface/ILevelPlay';

// ❌ 禁止（eslint import/no-restricted-paths 会报错）
import { towerStarConfigScheme } from '../../UniverseEditor/EditorCommon/Scheme/Var/LevelPlay';

3. MVC 三件套

每个业务模块标准是三个类：Controller（逻辑与协议）+ Model（数据）+ Config（配置表加工）， UI 另有 View / Panel。三者都是进程级单例，通过静态 Manager 访问。

3.1 ControllerBase

export abstract class ControllerBase {
    public Init(): boolean { return this.OnInit(); }
    public Clear(): boolean { return this.OnClear(); }
    public LeaveLevel(): boolean { return this.OnLeaveLevel(); }

    // tick接口使用下面的进行override
    protected OnPreWorldActorTick(delta: number): void {}
    protected OnPrePhysicsTick(delta: number): void {}
    protected OnDuringPhysicsTick(delta: number): void {}
    protected OnEndPhysicsTick(delta: number): void {}
    protected OnPostPhysicsTick(delta: number): void {}
    protected OnPostUpdateWorkTick(delta: number): void {}
}

3.2 UiControllerBase：四对注册/注销

export abstract class UiControllerBase extends ControllerBase {
    public Init(): boolean {
        const ret = super.Init();          // ← 先跑 OnInit
        this.OnRegisterNetEvent();          // ① 注册协议
        this.OnAddEvents();                 // ② 注册事件
        this.OnAddOpenViewCheckFunction();  // ③ 注册开界面检查
        return ret;
    }
    public Clear(): boolean {
        this.OnUnRegisterNetEvent();        // 逆序清理
        this.OnRemoveEvents();
        this.OnRemoveOpenViewCheckFunction();
        return super.Clear();               // ← 最后跑 OnClear
    }
}

3.3 ModelBase：多了一个 ChangeMode

export abstract class ModelBase {
    protected OnInit(): boolean { return true; }
    protected OnClear(): boolean { return true; }
    protected OnLeaveLevel(): boolean { return true; }
        protected OnChangeMode(): boolean { return true; }
}

3.4 Manager 单例

export class ModelManager extends ModelManagerBase {
    public static DungeonModel: DungeonModel | undefined = undefined;
    public static TowerClimbModel: TowerClimbModel | undefined = undefined;
    // ... 共 136 个
}

// ModelManagerBase 的批量生命周期驱动
public static Init(): boolean {
    for (const model of this.Models) {
        if (!model.Init()) {
            Log.Error(..., '模块初始化失败，请往上查看具体出错模块日志解决问题',
                ['model', model.constructor.name]);
                        return false;   // 任一失败整体中断
        }
    }
    return true;
}

返回 false 会中断整个初始化链，游戏起不来。 所以 OnInit 里返回 false 要慎重——查表失败这类问题应该 Log.Error + 返回 true 降级， 只有真正无法继续（比如必需的配置表整个缺失）才返回 false。

4. 事件系统

EventSystem（静态门面）→ Event<EEventName, IEventType>（实现）。 768+ 个事件名定义在 EEventName 枚举，每个事件的参数签名定义在 IEventType 映射表里：

// EventDefine.ts
export enum EEventName {
    /** 创建实体（表现层还没有准备好） */
    EntityCreated,
    /** 实体已创建，而且初始化完成（包括表现层的都准备好了） */
    EntityInitialized,
    ...
}

export interface IEventType {
    [EEventName.EntityCreated]: (creatureData: Readonly<CreatureDataComponent>,
                                 handle: Readonly<EntityHandle>) => void;
}

好处是 Emit 的参数编译期强类型检查， Add 的回调签名写错直接编译不过。

4.1 弱引用持有：事件系统不阻止 GC

/** 事件系统不真正持有 handle */
private static readonly HandlerToWeakHandler = new WeakMap<TEventHandler, WeakRef<TEventHandler>>();
private readonly Handlers = new Map<TName, Map<WeakRef<TEventHandler>, EHandlerType>>();

存的是 WeakRef，Emit 时 deref()。回调所属对象被回收后 deref 返回 undefined， 系统会打一条 Critical 并自动摘除：

if (!handler) {
    Log.Critical(ELogModule.Event, ..., '事件处理方法已被回收',
        ['name', this.EventNames[name]],
                ['source', this.HandlerSources.get(name)?.get(weakHandler) ?? '未知']);
    handlers.delete(weakHandler);
    continue;
}

4.2 防重入：位掩码 + Pending 队列

public Emit(name, ...params): boolean {
        if (this.IsEmitting(name)) {
        Log.Critical(..., '事件重复派发，请检查事件链是否产生循环调用',
            ['name', ...], ['emitting', this.EmittingMask]);
        return false;
    }
    this.SetEmitting(name, true);
    // ... 遍历 handlers 逐个调用，每个 try/catch 包住 ...
    this.SetEmitting(name, false);

    // 派发期间的增删在这里统一生效
        for (const h of pendingRemoveHandles) { this.DoRemove(name, h); }
        for (const h of pendingAddHandles)    { this.DoAdd(name, ...); }
}

4.3 六组 API 对照

5. 协议层

// Net 是纯静态门面，内部转发给 NetConnection
Net.Register(ENotifyMessageId.WorldDungeonTowerStarStartSCNotify, this.OnStart);
Net.UnRegister(ENotifyMessageId.WorldDungeonTowerStarStartSCNotify);

Net.Call(ERequestMessageId.XxxCSReq, message, (rsp) => { ... }, timeout);
const rsp = await Net.CallAsync(ERequestMessageId.XxxCSReq, message);
Net.Push(EPushMessageId.XxxCSPush, message);

// ❌ 直接用会拿到 Long 对象而不是 number
const t = progress.condition.waitTimeData.endTimeMs;
// ✅
const t = MathUtils.LongToNumber(progress.condition?.waitTimeData?.endTimeMs ?? 0);

6. ECS 实体组件

@RegisterComponent(EComponent.BoundaryRespawnComponent)
export class EtBoundaryRespawnComponent extends EntityComponent {
    protected override OnStart(): boolean { ... }
    protected override OnEnd(): boolean { ... }
}

@RegisterComponent(id) 装饰器只做一件事：type.Id = id。 组件靠这个数字 id 在 EComponent 枚举里唯一标识， entity.GetComponent(EComponent.Xxx) 按 id 查。

6.1 组件生命周期：六个钩子，两两配对

const enum EExecutedFunctions {
    None        = 0,
    Created     = 0b1,
    Initialized = 0b10,
    Started     = 0b100,
    Activated   = 0b1000,
    Ended       = 0b10000,
    Cleared     = 0b100000,
}

每个组件用一个位掩码记录「已执行过哪些阶段」。 清理时可以据此跳过未配对的终止函数 （开关 EntityComponentConstants.SkipUnpairedEventFunctions，当前设为 false，即全部都跑）。

6.2 分帧调度：InitComplexity

/**
 * 组件 Init 复杂度评分 (0-10)，用于分帧调度预算控制。
 * 子类可 override 此属性声明自身的 Init 开销权重。默认值 2（低复杂度）。
 */
public get InitComplexity(): number { return EComponentInitComplexity.Low; }

export const enum EComponentInitComplexity {
    None = 0, Min = 1, Low = 2, Medium = 3,
    High = 5, VeryHigh = 8, Extreme = 10,
}

一帧内批量创建实体（比如刷一波怪）时，调度器按这个权重攒够预算就切帧， 避免单帧卡顿。写重初始化逻辑（加载资源、建大表）的组件应该 override 提高评分。

6.3 从外部访问实体数据

// 拿服务器同步的组件数据（不需要实体表现层就绪）
const comp = EntityInterfaceHelper.GetServerCompData(creatureDataId, 'cumulativeValueComp');

// 遍历全部实体
for (const handle of EntityInterfaceHelper.GetAllEntities()) { ... }

7. 定时器

TimerSystem.Next(action)                        // 下一帧
TimerSystem.Delay(action, ms)                   // 单次
TimerSystem.Loop(action, ms, loopCount)        // 循环 N 次
TimerSystem.Forever(action, ms)                 // 永久循环

TimerSystem.Has(handle)                        // 判存活
TimerSystem.Remove(handle)                     // 移除
handle.Pause() / .Resume() / .ChangeDilation(d) // 句柄上的便捷方法

class TimerSystemConstants {
    /** 最小定时器时间 */  public static readonly MinTime = 20;
    /** 最大定时器时间 */  public static readonly MaxTime = 90000;
    /** 最多循环次数 */    public static readonly MaxLoop = 10;
    /** 永久计时器 */      public static readonly Forever = 0;
}

7.1 三条铁律

// ① 建之前先判存活，否则会堆出一堆重复定时器
if (!TimerSystem.Has(this.Timer)) {
    this.Timer = TimerSystem.Forever(this.OnTick, 50);
}

// ② 销毁时必须清，否则回调打在已销毁的 UI 上
protected override OnBeforeDestroy(): void {
    if (TimerSystem.Has(this.Timer)) {
        TimerSystem.Remove(this.Timer!);
        this.Timer = undefined;
    }
    super.OnBeforeDestroy();
}

// ③ 回调必须是箭头函数成员，不能是普通方法（会丢 this）
private readonly OnTick = (): void => { ... };

8. UI 层

8.1 UiPanelBase 生命周期

OnRegisterComponent()   // 声明控件索引表，最先执行
OnBeforeCreate()        // 创建前
OnStart()               // 首次启动
OnBeforeShow()          // 每次显示前 ← 取控件引用、刷数据都在这
OnAfterShow()           // 每次显示后
OnBeforeHide()          // 每次隐藏前
OnAfterHide()           // 每次隐藏后
OnPrepareDestroy()      // 准备销毁
OnBeforeDestroy()       // 销毁前 ← 清定时器、解事件都在这
OnAfterDestroy()        // 销毁后

/** UiItem_TowerStar 组件索引：0=亮星、1=条件文本 */
const enum ETowerStarComps { SprStar, TxtCondition }

protected override OnRegisterComponent(): void {
    this.ComponentRegisterInfos = [
        [ETowerStarComps.SprStar, UE.UISprite],
        [ETowerStarComps.TxtCondition, UE.UIText],
    ];
}
protected override OnBeforeShow(): void {
    this.SprStar = this.GetSprite(ETowerStarComps.SprStar);
    this.TxtCondition = this.GetText(ETowerStarComps.TxtCondition);
}

8.2 LGUI 常用 API

9. 日志规范

Log.Warn(ELogModule.TowerClimb, ELogAuthor.ZZB, '爬塔星级-局内收包20532 TowerStarStart',
    ['starCount', notify.info?.starList?.length ?? 0],
    ['starsMask', notify.info?.starsMask ?? 0],
    ['明细', (notify.info?.starList ?? []).map((s) => `idx${s.idx}=${s.isTrue}`).join(',')]);

签名固定四段：模块 + ELogAuthor 来源标记 + 消息 + N 组 [键, 值]。

10. 编码约定速查

10.1 编译流水线

11. 反复出现的通用模式

12. 面试怎么讲架构