宇宙编辑器 Scheme

策划在编辑器里看到的每一个输入框、下拉、勾选、数组，都由一份 Scheme 描述。 八大模块里，边界重生、爬塔星级、传送表现、刷怪器按钮都动过 Scheme。 这一页讲清楚：Scheme 是什么、怎么加、以及为什么它是「配了没生效」类问题的第一嫌疑人。

1. Scheme 是什么

一句话：Scheme = 配置项的元数据（类型 + 默认值 + UI 呈现 + 校验规则 + 自动修复）。 它不是「数据」，而是「描述数据长什么样」的对象。

// Src/UniverseEditor/EditorCommon/Scheme/Component/BoundaryRespawnComponentScheme.ts
export const boundaryRespawnConditionScheme = createObjectScheme<IBoundaryRespawnCondition>({
    Name: 'BoundaryRespawnConditionScheme',
    CnName: '倒计时判断条件',   // ← 策划在编辑器里看到的名字
    NewLine: true,
    ShowName: true,
    Optional: true,               // ← 可选字段，不勾就不下发
    Fields: {
        CountdownTime: createIntScheme({
            CnName: '倒计时',
            Tip: '倒计时数值，单位秒',   // ← 鼠标悬停提示
            CreateDefault: () => 15,     // ← 新建时的默认值
        }),
        BoundaryRangeEntityIds: createArrayScheme({
            ...refEntityListScheme,
            CnName: '边界范围实体数组',
        }),
        TriggerOnLeave: createBooleanScheme({
            CnName: '取反触发（边界外才倒计时）',
            Tip: '勾选后，边界范围内为安全区，玩家离开边界才开始倒计时',
            CreateDefault: () => false,
        }),
    },
});

2. 工厂函数速查

全部来自 Src/UniverseEditor/EditorCommon/Type.ts：

2.1 EdTid / Tid 永远成对

EdTidRespawnText: createEdTidTextScheme({
    Name: 'EdTidRespawnText',
    CnName: '重生提示文本(EdTid)',
    CreateDefault: () => '不要离开任务区域',
    IsDefaultCreate: true,
    IsAlwaysShow: true,
}),
TidRespawnText: createTidTextScheme({
    Name: 'TidRespawnText',
    CnName: '重生提示文本(Tid)',
    TextKeyPrefix: 'BoundaryRespawnRespawnText',   // ← 生成的多语言 key 前缀
}),

3. Scheme 的四个回调

每个 Scheme 实例都有这四个钩子（EditorCommon/Type.ts 里的 class Scheme）。 顺序很重要：

3.1 一个完整的校验示例

// CustomBaseScheme/TeleportIdScheme.ts —— 传送点 ID 引用校验
export const teleportIdScheme = createAkiExcelKeySelectorScheme({
    ExcelType: EAkiExcelType.Teleporter,
    CnName: '传送点Id',
    Tip: '引用c.传送.xlsx',
    OnSchemeCheck: (teleporterId, messages): number => {
        // 模板检查阶段跳过：模板里的引用允许悬空
        if (globalContext.Get('IsTemplateChecking')) { return 0; }
        if (!getTableParser('Teleporter').GetTeleporterById(teleporterId)) {
            messages.push(`不存在传送表ID: ${teleporterId}`);   // ← 策划直接能看懂
            return 1;
        }
        return 0;
    },
});

3.2 globalContext：校验时「当前在哪」

校验函数经常需要知道上下文——当前在哪个关卡、哪个实体、哪个组件里。 Scheme 通过 OnOpEnter / OnOpExit 压栈出栈：

// levelPlayScheme
OnOpEnter: (value): void => {
    globalContext.Push('LevelId', value.LevelId);
    globalContext.Push('LevelPlay', value);
    globalContext.Push('RootContext', ...);
},
OnOpExit: (value): void => {
    globalContext.Pop('LevelId');
    globalContext.Pop('LevelPlay');
    globalContext.Pop('RootContext');
},

于是深层字段的校验里能直接 globalContext.Get('LevelId')。 Push / Pop 必须严格配对，漏 Pop 会污染后续所有校验。

4. 双 Scheme：最坑的一个坑

同一份数据，编辑时用的 Scheme 和校验时用的 Scheme 可能不是同一个。

// Scheme/Var/LevelPlay.ts:385 —— 通用玩法 scheme（校验走这条）
export const levelPlayScheme = createObjectScheme<ILevelPlay>({
    Fields: {
        // 爬塔星级：校验侧用空壳(IgnoreAllFields)取消检查
        TowerStarConfig: createObjectScheme<ITowerStarConfig>({
            Name: 'TowerStarConfig',
            Optional: true,
            IgnoreAllFields: true,      // ← 空壳！不校验内部字段
            Fields: {} as never,
        }),
    },
});

// Scheme/Var/LevelPlay.ts:499 —— 副本主控树 scheme（编辑走这条）
export const levelPlayDungeonScheme = createObjectScheme<ILevelPlay>({
    Fields: {
        ...levelPlayScheme.Fields,
        TowerStarConfig: towerStarConfigScheme,   // ← 覆盖成真实 scheme
    },
});

for (const key in value) {
    if (!fields[key] && !key.startsWith('_') && !scheme.IgnoreAllFields) {
        keysToRemove.push(key);   // ← 直接 delete 掉！
    }
}

5. 主控树节点（Action）Scheme

主控树上策划摆的每个节点，对应一个 EAction 枚举值 + 一份参数 Scheme + 一份 actionConfig 条目。 全工程 171 个 EAction，其中 82 个 ImplementType: 'Server'。 （该口径来自更早分支；071 分支实测为 105 个 EAction / 83 个 Server， 见旧版编辑器 · 节点类型）

5.1 加一个节点要动三处

5.2 给已有节点加可选参数（实例）

「跨地图传送表现」这个需求，要给三个已有节点加同一个可选参数。 做法是抽一个共享 Scheme，三处引用：

// Scheme/Action/LevelPlay.ts:280
/** 单个传送表现下拉：飞天遁地(默认)/淡入淡出，未来新表现在此扩展 */
const createTeleportShowEnumScheme = (cnName: string, newLine: boolean) =>
    createEnumScheme<ETeleportShowType>({
        CnName: cnName,
        Config: {
            [ETeleportShowType.FlyThrough]: '飞天遁地',
            [ETeleportShowType.FadeInOut]: '淡入淡出',
        },
        CreateDefault: () => ETeleportShowType.FlyThrough,
    });

/** 传送表现：进入/离开各一个下拉，作为可选字段挂到传送类节点 */
export const teleportShowScheme = createObjectScheme<ITeleportShowInfo>({
    Name: 'ShowInfo',
    CnName: '传送表现',
    Optional: true,     // ← 老数据不填也合法
    NoFolder: true,     // ← 不折叠，两个下拉平铺展示
    Fields: {
        EnterType: createTeleportShowEnumScheme('进入', false),
        LeaveType: createTeleportShowEnumScheme('离开', false),
    },
});

// 三个节点各引用一行：
// teleportLevelScheme (传送关卡) / 传送副本 / SetDungeonExitPosition (退出副本)
ShowInfo: teleportShowScheme,

6. 组件 Scheme

实体组件的 Scheme 用 createComponentScheme，它会自动补两个隐藏字段：

// Scheme/Component/ComponentRegistry.ts
export function createComponentScheme<T>(type: Partial<ComponentScheme<T>>): ComponentScheme<T> {
    if (type?.Fields) {
        fields.Disabled   = createBooleanScheme({ HideFlag: ETabFlag.AlwaysHide, Optional: true });
        fields.EdIsLocked = createBooleanScheme({ HideFlag: ETabFlag.AlwaysHide, Optional: true });
    }
    ...
}

目录里现有 65 个组件 Scheme（EditorCommon/Scheme/Component/）， 本站涉及的 BoundaryRespawnComponentScheme.ts 是其中之一。

7. 自定义渲染（加按钮）

默认渲染只有输入框、下拉、勾选。想在字段旁边加一个按钮（比如刷怪器的「生成」）， 要走自定义 RenderType：

const dungeonSpawnerIdScheme = createIntScheme({
    CnName: '副本刷怪器ID',
    Optional: true,
    RenderType: 'intWithGenerateButton',
    Tip: '填副本刷怪器表ID，点旁边【生成】读表自动布怪',
});

8. 构建：gulp，不是 npm run compile

9. 分层纪律：Game 不许 import UniverseEditor

// ❌ Src/Game/** 里禁止
import { getTableParser } from '../../UniverseEditor/EditorCommon/TableParsers/...';

// ✅ 只能 import 纯类型的 Interface
import type { ITowerStarConfig } from '../../UniverseEditor/Interface/ILevelPlay';

需要编辑器侧的数据怎么办？让业务方查表后当参数传进来。 配置从 ClientJson 走 ConfigManager，不是从编辑器代码里拿。

10. 改 Scheme 的自查清单

11. 面试可讲的点