操作手册（按任务）

不解释机制，只写「要完成 X，按顺序做这些」。想动手做事，先读这篇。

每条的详细机制见左侧对应模块页。

我要引导一个世界

public sealed class GameBootstrap : MonoBehaviour
{
    private async void Start()
    {
        await new FrameworkBootstrap().InitializeAsync("World");
    }
}

全平台同一套代码。详见 引导与世界。

我要配一张配置表

1. 建模板       编辑器里定义 ConfigTemplate（加字段，枚举字段引用 ConfigEnumDefinition）
2. 生成代码     HYC Framework/Config/1-生成配置模板与代码 → CfgXxx + XxxBlobSystem + 枚举
3. 填数据+导出   .../2-导出Blob → Assets/StreamingAssets/ConfigBlob/*.blob
4. 引导期注册    生成的 XxxBlobSystem 自动完成（挂在 A1）
5. 运行期读      ref var row = ref ConfigManager.{Type}.GetByID(id);

详见 配置系统 / 枚举配置。

我要写一个界面

public partial class BagWindow : BaseWindowSystem<BagBinder>
{
    public override string PrefabKey => "UI/BagWindow";   // Addressable key
    public override void OnViewOpen(params object[] args)
    {
        base.OnViewOpen();
        Binder.CloseButton.onClick.AddListener(() => UIManager.Close<BagWindow>());
    }
    public override void OnViewClose()
    {
        base.OnViewClose();     // 必调
    }
}

UIManager.OpenWindow<BagWindow>(1001);

前置：预制体挂 ComponentBinderTable 并跑 HYC Framework/UI/Generate UI Binders；引导期手动建 UIManager。详见 窗口系统 / 组件绑定。

我要做多语言

1. 产出数据   Loc 数据编辑器（Excel → id / lang / *.lang 等 blob）导出到 StreamingAssets/Localization/
2. 加载      LocalizationBlobSystem 自动加载；或手动 LocalizationManager.Reload(folder)
3. 取文本    LocalizationManager.GetText("ui/start") / GetText(key, args) / HasKey(key)
4. 切语言    LocalizationManager.SetLanguage(Locale.Chinese)
5. UI 刷新   Prefab 挂 LocalizedTMP，Inspector 设 Key

详见 多语言。

我要做行为树 AI

1. 建树资产   BTAssetFactory.Create("EnemyAI")（或 Project 右键 HYC/BT/Tree）
2. 画树       必须有且仅有一个 Root，靠 Connections（Source→Target + PortIndex）连成树
3. 导出 Blob   HYC Framework/BT/Export Blob (For Build)      ← 真机必做
4. 运行期加载  BTBlobLoader.LoadAll()
5. 挂组件      new RunningBT { TreeId = ..., RunState = default, TickInterval = 0f }
              BTInterpreterSystem 已 RequireForUpdate<RunningBT>()，自动驱动

自定义行为走 GameCustom 节点（LongParams[0] = subType）。详见 行为树。

我要接输入 / 热键

// 事件层：动作名 + 回调（引导期先 BindAsset）
HotkeyManager.BindAsset(myInputActionAsset);
mHotkey = RegisterHotkey(HotkeyActionNames.UI_UGUI_Cancel, ctx => UIManager.Close<BagWindow>());

// 轮询层：按 map 生成 ECS 组件
UIInputComponent.AddTo(em, player);
InputPlayerRegistry.Register(player, myAssetInstance);

详见 输入与热键。

我要做过场动画

public class MyCutsceneDirector : CutsceneDirector
{
    protected override void PlayClip(Cutscene clip)
    {
        Addressables.LoadAssetAsync<PlayableDirector>(clip.AssetKey).Completed += h =>
        {
            _director = h.Result;
            _director.stopped += _ => NotifyFinished();   // ← 关键
            _director.Play();
        };
    }
}

框架只提供 FIFO 队列骨架，轨道由宿主用 Unity Timeline 自己做。详见 过场 Timeline。

我要发消息 / 打日志

var e = ecb.CreateEntity();
ecb.AddComponent<MessageEntity>(e);                                    // 必须加，才会被帧末清
ecb.AddComponent(e, new EventMessage { EventID = 10023, IsRepeated = false });

Log.Open();                       // PersistentDataPath/logs 下开文件
Log.Info("..."); Log.Error(ex, "context");
Log.Format(LogLevel.Info, "玩家 {0} 升到 {1} 级", id, lv);

详见 消息与日志。

最容易踩的 9 件事

1. 字符串字段必须显式选 BlobString / FixedString，否则烘焙失败。
2. 分类字段用 Enum 不用裸 Int，且枚举是 1 基、没有 0。
3. Blob 里枚举是 int——运行期别指望拿到枚举类型。
4. 改表结构只跑菜单 3 不生效，必须 1 → 2 → 3。
5. UI 类必须 partial，且 OnViewClose 要调 base。
6. 打开窗口是异步的——初始化写在 OnViewOpen，别写 OnCreate。
7. HotkeyManager.BindAsset 必先做，且别重复调。
8. 配置行必须 blittable；取行必须 ref var row = ref ...。
9. WebGL / Android 不能用 System.IO 读 StreamingAssets，引导必须走 InitializeAsync。