Script Analysis

GameRoot.cs

Main 场景的游戏主控制器——装配 ECS 世界、加载所有 UI、控制游戏主循环。共 101 行，是理解整个项目 ECS 启动链路 最关键的文件。以下从前端工程师视角，逐行拆解。

基类MonoBehaviour

场景Main.unity

核心方法Awake / Update

关联文件GameFeature.cs / GameEnv.cs

CH 01

完整源码

101 行，6 个方法。比 HomeRoot 复杂一个数量级，因为这里要初始化整个 ECS 世界。

GameRoot.cs 101 lines · 6 methods

using UnityEngine;
using UnityEngine.EventSystems;

// 训练工程游戏根节点（放在 Main 场景里）。
// 负责装配 ECS、加载关卡、创建 HUD。由主入口场景 Home 点击"开始游戏"后加载 Main 场景触发。
public sealed class GameRoot : MonoBehaviour
{
    Contexts _contexts;
    GameFeature _feature;
    GameEnv _env;

    void Awake()
    {
        _env = BuildEnv();

        _contexts = Contexts.sharedInstance;
        // 每次进入 Main 场景重置一份干净的 ECS 世界
        _contexts.Reset();

        _feature = new GameFeature(_contexts, _env);
        _feature.Initialize();

        EnsureEventSystem();

        // HUD（命值 + 关卡号 + 返回）
        var hudPrefab = Resources.Load<GameObject>("Prefabs/GameHud");
        if (hudPrefab != null)
            Instantiate(hudPrefab).GetComponent<GameHud>().Bind(_contexts);
        else
            Debug.LogError("HUD 预制体缺失...");

        // Awards 业务模块视图
        var toastPrefab = Resources.Load<GameObject>("Prefabs/AwardToast");
        if (toastPrefab != null)
            Instantiate(toastPrefab).GetComponent<AwardToast>().Bind(_contexts);

        // 失败弹窗
        var failPrefab = Resources.Load<GameObject>("Prefabs/LevelFailPopup");
        if (failPrefab != null)
            Instantiate(failPrefab).GetComponent<LevelFailPopup>().Bind(_contexts, RetryLevel);
        else
            Debug.LogError("失败弹窗预制体缺失...");

        // 作弊调试面板
        var cheatGo = new GameObject("CheatPanel");
        cheatGo.AddComponent<CheatPanel>();
    }

    void Update()
    {
        _feature.Execute();
        _feature.Cleanup();
    }

    void RetryLevel()
    {
        var current = _contexts.game.hasCurrentLevel
            ? _contexts.game.currentLevel.Value : 1;
        _contexts.game.isLevelFailed = false;
        _contexts.game.ReplaceCurrentLevel(-1);   // 哨兵值
        _contexts.game.ReplaceCurrentLevel(current);
    }

    GameEnv BuildEnv()
    {
        var env = new GameEnv();

        var cam = Camera.main;
        if (cam == null)
        {
            var camGo = new GameObject("Main Camera");
            camGo.tag = "MainCamera";
            cam = camGo.AddComponent<Camera>();
        }
        cam.orthographic = true;
        cam.clearFlags = CameraClearFlags.SolidColor;
        cam.backgroundColor = Theme.MainBackgroundColor;
        cam.transform.position = new Vector3(0, 0, -10);
        env.Camera = cam;

        env.Root = new GameObject("LevelRoot").transform;

        env.ArrowPrefab = Resources.Load<GameObject>("Prefabs/Arrow");
        env.GridPrefab  = Resources.Load<GameObject>("Prefabs/Grid");

        return env;
    }

    static void EnsureEventSystem()
    {
        if (Object.FindObjectOfType<EventSystem>() == null)
        {
            var es = new GameObject("EventSystem");
            es.AddComponent<EventSystem>();
            es.AddComponent<StandaloneInputModule>();
        }
    }
}

六件事速览

#	方法	做什么	前端类比
1	`BuildEnv()`	创建运行环境：摄像机、关卡容器、箭头/点阵预制体	创建 app 容器 + 加载静态资源
2	`Awake()` 前半	初始化 ECS 世界：Contexts、GameFeature	new Vuex.Store() / new Redux store
3	`Awake()` 后半	实例化 4 个 UI 预制体 + 作弊面板	mount() 渲染子组件
4	`Update()`	每帧执行所有 System + 清理	requestAnimationFrame 主循环
5	`RetryLevel()`	重开当前关卡（哨兵值技巧）	重置 state 触发重新渲染
6	`EnsureEventSystem()`	同 HomeRoot，确保 UI 可点击	同 HomeRoot

CH 02

逐行拆解

从字段声明到 RetryLevel 哨兵技巧，逐段覆盖全部 101 行。

02.1

三个私有字段 — 组装 ECS 的零件

第 8~10 行。

Contexts _contexts;

Contexts = Entitas 代码生成器（Jenny）自动生成的类。持有所有 ECS Context 的引用：contexts.game、contexts.input 等。

下划线前缀 _ = C# 团队编码约定：私有实例字段用下划线命名。前端类比：#contexts（JS 私有字段）。

JS 类比 // Contexts = 全局 store 引用
class GameRoot {
  #contexts; // private field
  #feature;
  #env;
}

GameFeature _feature;

GameFeature = 这个项目自定义的类，继承 Entitas 的 Feature。它把所有 System 按顺序装在一起，提供 Initialize()、Execute()、Cleanup() 三个统一入口。

类比：Feature = Redux 的 combineReducers + Vuex 的 modules，把分散的逻辑聚合到一条执行流水线。

GameEnv _env;

GameEnv = 这个项目自定义的依赖注入容器（DI Container）。只存 4 样东西：
Camera、Root（关卡物体父节点）、ArrowPrefab、GridPrefab。

JS 类比 const env = {
  camera: mainCamera,
  root: levelContainer,
  arrowPrefab: { /* 箭头模板 */ },
  gridPrefab: { /* 点阵模板 */ }
};
// Provider 传给所有 System

02.2

BuildEnv() — 搭建运行环境

第 65~90 行。创建摄像机、关卡容器、加载预制体引用。

65~67

GameEnv BuildEnv()
{
    var env = new GameEnv();

返回类型是 GameEnv，不是 void。创建一个空的 GameEnv 对象，然后逐步填充。

69~74

var cam = Camera.main;
if (cam == null)
{
    var camGo = new GameObject("Main Camera");
    camGo.tag = "MainCamera";
    cam = camGo.AddComponent<Camera>();
}

与 HomeRoot 不同：HomeRoot 只是「设置已有摄像机」，GameRoot 找不到就自己创建一个。

关键步骤：

camGo.tag = "MainCamera" — 设置 tag，这样以后 Camera.main 能找到它
AddComponent<Camera>() — 给空 GameObject 挂 Camera 组件，然后它会返回这个组件的引用

cam.orthographic = true;

orthographic = 正交投影（无透视）。2D 游戏标配。
设为 false 的话就是透视投影（3D 游戏用的），物体会近大远小。

JS 类比 CSS 的 perspective: none; // 2D 无透视
vs perspective: 800px; // 3D 有透视

77~79

cam.clearFlags = CameraClearFlags.SolidColor;
cam.backgroundColor = Theme.MainBackgroundColor;
cam.transform.position = new Vector3(0, 0, -10);

设置纯色白底 + 摄像机位置。注意：Z = -10，摄像机放在画面后面 10 单位远。
2D 正交投影下 Z 值决定渲染层级，只要在物体后面就行。前端类比：z-index 或 transform: translateZ(-10px)。

env.Camera = cam;

把摄像机存到 GameEnv 里。之后任何 System 需要摄像机时通过 _env.Camera 就能拿到。

env.Root = new GameObject("LevelRoot").transform;

创建空 GameObject，名字 "LevelRoot"，取其 Transform 组件存入 env。关卡加载后所有箭头、点阵都挂在这个空节点下，方便组织 Hierarchy。

JS 类比 const root = document.createElement('div');
root.id = 'level-root';
// 关卡里的箭头都是 root.appendChild(arrow)

84~87

env.ArrowPrefab = Resources.Load<GameObject>("Prefabs/Arrow");
env.GridPrefab = Resources.Load<GameObject>("Prefabs/Grid");

预加载箭头和点阵的预制体引用。存到 env 里，当 LevelStartSystem 加载关卡时直接用，不需要每关都 Resources.Load（很慢）。

return env;

返回组装好的 GameEnv。回到 Awake 里 _env = BuildEnv() 接收。

02.3

ECS 世界初始化 — 整个项目的心脏

第 16~21 行，Awake() 中最关键的 5 行。

_contexts = Contexts.sharedInstance;

Contexts.sharedInstance = 全局唯一的 ECS Context 单例。

_contexts.game = 游戏数据的 Context（关卡、命值、奖励等都在这）
_contexts.input = 输入数据的 Context（鼠标点击、拖拽等）
项目目前只用了这两个 Context。

JS 类比 const contexts = {
game: new Context(), // 游戏状态 store
input: new Context() // 输入状态 store
};

_contexts.Reset();

每次进 Main 场景都重置。因为 Contexts 是单例，用户可能需要「返回主菜单 → 再点开始游戏」，如果不 Reset，上次关卡的数据会残留。

_feature = new GameFeature(_contexts, _env);

创建 GameFeature。去看看 [GameFeature.cs](file:///Users/zl_bofeng/Documents/pending-dome/unity/demo/GameClientTrainning/Assets/GameBase/App/GameFeature.cs) 的构造函数，它会 Add() 接 Add()，把所有 System 按顺序串成流水线。

GameFeature 内部 System 流水线简图

SavegameFeature — 读档，设置 CurrentLevel/Awards

InputSystem / TimerSystem — 检测鼠标输入和计时

ArrowClick / Block / Move / Complete — 核心玩法逻辑

LivesMistake / LevelFail — 命值扣除和失败判定

LevelComplete / Reload / Start — 关卡流转

AwardsFeature — 奖励计算

DestroySystem — 清理标记为 Destroy 的 Entity

Add() 的顺序 = 执行顺序。存档最前（先恢复数据），销毁最后（收尾清理）。

_feature.Initialize();

调用所有 System 的 Initialize()。大部分 System 的 Initialize 是空的，但 SavegameSystem 会在这里 读 JSON 文件，恢复存档数据到 ECS 组件。

02.4

UI 预制体实例化 — Instantiate + GetComponent + Bind

第 26~47 行。这个项目里 UI 加载的标准三板斧。

var hudPrefab = Resources.Load<GameObject>("Prefabs/GameHud");

从 Resources/Prefabs/GameHud.prefab 加载 HUD 预制体。

27~28

if (hudPrefab != null)
    Instantiate(hudPrefab).GetComponent<GameHud>().Bind(_contexts);

这条链式调用是整个项目 UI 初始化的核心模式，拆开看：

步骤	代码	JS 类比
1. 克隆	`Instantiate(hudPrefab)`	`prefab.cloneNode(true)`
2. 拿组件	`.GetComponent<GameHud>()`	`.querySelector('[data-component="GameHud"]')`
3. 绑定数据	`.Bind(_contexts)`	`.bindContexts(contexts)` 类似 Vue 的 provide

Instantiate 的返回值：克隆出来的 GameObject。但 Unity 不知道它上面挂了什么脚本，所以需要用 GetComponent<GameHud>() 来拿那个特定的 MonoBehaviour 脚本引用。

JS 类比 const instance = prefab.cloneNode(true);
const hudScript = instance.getComponent(GameHud);
hudScript.bind(contexts); // 注入 ECS 上下文

29~30

else
    Debug.LogError("HUD 预制体缺失...");

如果 HUD 没加载到（Build UI Prefabs 没执行过），打错误日志。

33~35

var toastPrefab = Resources.Load<GameObject>("Prefabs/AwardToast");
if (toastPrefab != null)
    Instantiate(toastPrefab).GetComponent<AwardToast>().Bind(_contexts);

AwardToast（奖励弹出提示），同样的三板斧模式。注意这里没有 else 错误日志——奖励提示是可选的 UI，没加载也不会影响游戏运行，所以不打日志。

38~42

var failPrefab = Resources.Load<GameObject>("Prefabs/LevelFailPopup");
if (failPrefab != null)
    Instantiate(failPrefab).GetComponent<LevelFailPopup>().Bind(_contexts, RetryLevel);

失败弹窗有点不同：Bind 传了两个参数 —— _contexts 和 RetryLevel。第二个参数是回调函数，当用户点「重试」按钮时调用。

JS 类比 // Vue: <LevelFailPopup :contexts="contexts" @retry="retryLevel" />
// React: <LevelFailPopup contexts={contexts} onRetry={retryLevel} />

44~46

var cheatGo = new GameObject("CheatPanel");
cheatGo.AddComponent<CheatPanel>();

作弊面板不走预制体，直接在代码里创建空 GameObject + AddComponent。因为它是纯代码生成的（用反射收集所有作弊项加到按钮上），不需要可视化编辑。

JS 类比 import { CheatPanel } from './cheat-panel';
// 直接 new，不走模板
const cheat = new CheatPanel();
document.body.appendChild(cheat.render());

02.5

Update() — 游戏主循环，只有两行

第 49~53 行。

49~53

void Update()
{
    _feature.Execute();
    _feature.Cleanup();
}

整个游戏的「心脏跳动」就在这两行。每帧都会执行：

调用	做什么	前端类比
`Execute()`	跑一遍所有 System。按 GameFeature 里 Add 的顺序依次调用每个 System 的 Execute()	Redux dispatch 链 / Vuex action 链
`Cleanup()`	清理单帧数据。输入事件只存在一帧，下一帧就清掉。标记 Destroy 的 Entity 也在这里删掉	批量 clear 临时状态 / GC

一帧内发生了什么？

InputSystem 检测鼠标/触摸 → 写入 ECS

ArrowClickSystem 读到点击事件 → 判断拔/撞 → 改箭头状态

LivesMistakeSystem 读到撞了 → 扣命 → 判断 0 命 → 触发 LevelFailed

ArrowsCompleteSystem 读到全拔完 → 触发通关

UI Update()（GameHud 等）读到状态变化 → 刷新显示

Cleanup() — 清 Input Entity、删 Destroy Entity

02.6

RetryLevel() — 哨兵值重试技巧

第 56~63 行。精巧的「通过设 -1 再设回来触发 System」的模式。

56~63

void RetryLevel()
{
    var current = _contexts.game.hasCurrentLevel
        ? _contexts.game.currentLevel.Value : 1;
    _contexts.game.isLevelFailed = false;
    _contexts.game.ReplaceCurrentLevel(-1);
    _contexts.game.ReplaceCurrentLevel(current);
}

这段代码看着绕，但思路很聪明：

步骤	代码	为什么
1	`var current = ...`	记下当前第几关（比如第 3 关）
2	`isLevelFailed = false`	关掉失败标记，先让弹窗消失
3	`ReplaceCurrentLevel(-1)`	设一个不可能的值（哨兵 sentinel）
4	`ReplaceCurrentLevel(current)`	设回原值（3）

为什么不能直接 ReplaceCurrentLevel(current)？
因为如果 current 本来就是 3，设 3（值没变），Entitas 的 ReactiveSystem 不会触发。必须先设一个不同的值（-1），再设回去，才能让 LevelStartSystem 检测到变化并重建关卡。

JS 类比 // Vue 中的类似手法：
this.level = -1; // 先破坏
await nextTick();
this.level = 3; // 再重建，触发 watcher

CH 03

完整启动链路

从用户点「开始游戏」到画面第一帧刷新。

Main.unity 加载 → 第一帧 Update 完整链路

Home 场景点「开始游戏」→ UnityEngine.SceneManagement.LoadScene("Main") → Main.unity 加载

GameRoot.Awake() 被 Unity 调用

BuildEnv() — 创建 GameEnv

找到或创建 MainCamera → 正交投影 + 白底 + 位置 (0, 0, -10)
创建 LevelRoot 空节点
预加载 Arrow.prefab 和 Grid.prefab

ECS 初始化

Contexts.sharedInstance → 拿全局 Context
_contexts.Reset() → 清空上次残留
new GameFeature(_contexts, _env) → 组装所有 System
_feature.Initialize() → 存档系统读 JSON、恢复数据

EnsureEventSystem() — 确保 UGUI 事件系统存在

加载 UI 预制体

GameHud → Instantiate + GetComponent + Bind(_contexts)
AwardToast → 同上
LevelFailPopup → 同上 + Bind(_contexts, RetryLevel)
CheatPanel → new GameObject + AddComponent

Unity 进入主循环，开始每帧调用 GameRoot.Update()

第一帧（保存有进度的前提下）：

SavegameSystem 已在 Initialize 恢复了 CurrentLevel
LevelStartSystem 检测到 CurrentLevel 有值 → 加载关卡数据 → 创建箭头和点阵

以后每帧重复： Execute → Cleanup → 等待下一帧

TypeScript 伪代码（极简版）

class GameRoot extends MonoBehaviour { #contexts: Contexts; #feature: GameFeature; #env: GameEnv; awake(): void { this.#env = this.buildEnv(); // ① 创建运行环境 this.#contexts = Contexts.sharedInstance; // ② 拿 ECS 单例 this.#contexts.reset(); // 清空残留 this.#feature = new GameFeature(this.#contexts, this.#env); this.#feature.initialize(); // ③ 读档恢复数据 this.ensureEventSystem(); // ④ 确保 UI 可点击 const hud = Resources.load('Prefabs/GameHud'); // ⑤ 加载 UI instantiate(hud).getComponent(GameHud).bind(this.#contexts); // ... 其他 UI 同理 } update(): void { this.#feature.execute(); // 每帧：跑所有 System this.#feature.cleanup(); // 清理单帧数据 } retryLevel(): void { const current = this.#contexts.game.currentLevel?.Value ?? 1; this.#contexts.game.isLevelFailed = false; this.#contexts.game.replaceCurrentLevel(-1); // 哨兵 this.#contexts.game.replaceCurrentLevel(current); // 触发 System } }

CH 04

GameRoot vs HomeRoot

两个场景启动器的对比，帮助你理解代码量级跃升的原因。

对比维度	HomeRoot	GameRoot
场景	Home.unity（主菜单）	Main.unity（游戏主界面）
代码行数	35 行	101 行
有无 ECS	无 — 纯 UI，不需要 ECS 世界	有 — 整个游戏的逻辑由 ECS 驱动
Update()	无 — 静态 UI 不需要帧循环	有 — 每帧执行所有 System
相机	用场景里已有的，只改背景色	找不到就自己建：正交投影 + 位置 (0,0,-10)
UI 加载方式	1 个预制体：Instantiate(prefab)	4 个预制体 + 1 个代码创建：Instantiate + GetComponent + Bind
预制体引用	直接 Load 后用，不存	存到 GameEnv，供所有 System 复用
EventSystem	自己写 EnsureEventSystem()	一模一样的 EnsureEventSystem()（复制粘贴）
依赖	Theme.cs（颜色常量）	Contexts、GameFeature、GameEnv、Theme + 十余个 System

执行顺序总结

Home.unity 加载 → HomeRoot.Awake() 执行（主菜单显示）

用户点"开始游戏" → Main.unity 加载

GameRoot.Awake() 执行（ECS 初始化 + UI 挂载）

每帧 GameRoot.Update() → _feature.Execute() → _feature.Cleanup()

不是「两个文件谁先执行」的问题，而是场景加载先后决定的。Home 场景先加载，Main 场景后加载。

CH 05

知识点速查表

本文件中出现的所有新概念（HomeRoot 中未出现过的）。

Unity / C# 概念	含义	JS/TS 类比
`Contexts`	Entitas 代码生成的 ECS Context 容器	Vuex Store / Redux Store
`Contexts.sharedInstance`	全局单例 Context	单例模式 getStore()
`Feature`	Entitas System 容器，管控执行顺序	Redux combineReducers / 中间件链
`Feature.Initialize()`	初始化所有 System（通常只用来读存档）	Store 初始化 dispatch
`Feature.Execute()`	每帧执行所有 System	requestAnimationFrame 里 dispatch
`Feature.Cleanup()`	清理单帧数据（Input/Destroy）	批量 clear 临时状态
`GameEnv`	自定义依赖注入容器	Provider / Container
`Transform`	位置/旋转/缩放的组件，每个 GameObject 都有	CSS transform / position
`orthographic`	正交投影（2D 无透视）	perspective: none
`Vector3(x, y, z)`	三维坐标（即使 2D 也用）	{ x, y, z }
`tag`	GameObject 标签，用于分类查找	HTML tagName / data-tag
`.transform`	取 GameObject 的 Transform 组件	element.style / getBoundingClientRect
`GetComponent<T>()`	从 GameObject 获取指定类型的组件	querySelector('[data-component]')
`Bind(contexts)`	项目自定义方法，注入 ECS 上下文	provide / inject
哨兵值（Sentinel）	设一个不可能的值再设回去，触发变化检测	force update / key change
`_fieldName` 下划线	C# 私有字段命名约定	`#fieldName`（JS private）
`ReplaceCurrentLevel(-1)`	Entitas 组件替换方法	state.level = -1

CH 06

双栏对照 · 源码 + 逐行注释

左栏：高亮源码｜右栏：每行的解释、来源、JS 类比。标签：C# 语言特性 / JS 前端类比 / ! 注意事项

GameRoot.cs (Assets/GameBase/App/)

解释 / 来源 / 类比

1using UnityEngine;

导入 Unity 引擎核心 API（GameObject、MonoBehaviour、Debug 等）。C#

2using UnityEngine.EventSystems;

导入 UGUI 事件系统（EventSystem、StandaloneInputModule）。C#

4// 训练工程游戏根节点（放在 Main 场景里）。

XML 文档注释风格。说明这个脚本挂载在 Main 场景。!

5// 负责装配 ECS、加载关卡、创建 HUD。

一句话概括职责：ECS 初始化 + 关卡 + UI。

6public sealed class GameRoot : MonoBehaviour

sealed 防止被继承（性能优化 + 安全）。继承 MonoBehaviour 才能挂到 GameObject 上。类比：class GameRoot extends ComponentJS

8 Contexts _contexts;

ECS Context 容器。Jenny 代码生成器自动生成的类，持有所有 Context 引用。_ 前缀 = C# 私有字段约定。C#src: Jenny 生成js: #contexts

Contexts 是什么？怎么生成的？

Contexts 是由 Jenny 代码生成器根据 Entitas 组件定义自动生成的类。你写完组件（如 CurrentLevelComponent）后运行 Jenny，它会把所有 [Game]、[Input] 等 Context 聚合到一个 Contexts 类里。之后用 Contexts.sharedInstance 获取全局单例。