vampire-like/AGENTS.md

AGENTS.md — SBE（Seek-Battle-Evacuate）

单人 3d 类吸血鬼幸存者游戏原型。Unity 2022.3.62f3，框架为 GameFramework（UGF，源码在 Assets/GameFramework/），配置表用 Luban，插件有 UniTask、DOTween 等。

主要目录

路径	内容
Assets/GameMain/Scripts/Base/	程序集 SepCore.Base：常量、存档数据结构（Definition/DataStruct/）、Luban 生成代码（Gen/）
Assets/GameMain/Scripts/Runtime/	程序集 SepCore.Runtime：战斗内核（Battle/）、自定义组件（CustomComponent/ 下 Luban、Random、Run、Save）、UIBase
Assets/GameMain/Scripts/UI/	程序集 SepCore.Presentation：各界面 Form/View
Assets/GameMain/Scripts/Procedure/、Editor/	UGF 流程、编辑器工具
Assets/GameMain/Scripts/Tests/EditMode/	EditMode 测试
数据表/	Luban 源：Datas/*.xlsx（__tables__.xlsx 注册）、Defines/、导出脚本 gen_cli.sh / gen_cli.bat
Docs/GameDesign/、Docs/Tech/	设计文档；技术文档（Luban、存档、UI、战斗 TODO）

生成代码不可手改

• Scripts/Base/Gen/ 全部由 Luban 导出。改表只改 数据表/Datas/ 源表，再运行 数据表/gen_cli.sh（Windows 也可 gen_cli.bat）。
• Scripts/UI/ 下的 XxxForm.cs / XxxView.cs 由 UIAssetsTools 生成（文件头有 // <auto-generated />）。业务逻辑写在同名 XxxForm.Logic.cs partial 中；prefab 上要暴露给代码的组件在 UISerializationItem 登记变量名后重新构建（编辑器菜单 Utility/UI/Build UI Prefabs）。

UI 常见坑（详见 Docs/Tech/UIMaintenance.md）

• UGF 只对顶级 Form 调用 OnInit/OnOpen/OnClose 生命周期；嵌套 Form 的这些方法永远不会执行。事件绑定用幂等模式（_listenersBound 标志 + EnsureXxx()），放在能力入口（如 Refresh）里。
• 子 Form 只提供能力（public 方法，幂等可重入），数据由调用方传入；只有顶级 Form 有编排权。子组件向上通信用 GameEntry.Event.Fire + XxxEventArgs（放 Scripts/Base/Event/UIForm/，ReferencePool + Create/Clear），禁止反向持有父 Form。

Luban 约定（详见 Docs/Tech/01_LubanDataTable.md）

• 表名小写 tbxxxconfig：Excel 表名、导出文件名、Tables 构造参数、TableNames 数组四处必须一致。
• 访问入口 GameEntry.Luban.Get<T>(id) / GetTable<T>()；单行表（mode=one，如 tbglobalconfig）不注册访问器，走 Tables.TbXxxConfig.Data。
• 从 Luban 里取出的数据默认其有效，业务代码不对其是否有效做判断。

判空与错误处理

• 声明处已经初始化赋值的变量，之后不再对它判空。
• 不做静态回退（不用默认值/兜底逻辑静默继续）；异常路径直接 Log.Error(...) 抛出（UGF 的 Log，支持格式串，如 Log.Error("Entity data is invalid.")）。
• UI 的序列化字段（[SerializeField] 及 View 生成的引用）不做判空检查，默认已在 Inspector 中赋值。
• GameEntry 中提供的静态入口不对其进行判空，默认其不为空。

代码风格

• 命名：public 成员大驼峰（EncounterId、RoundNumber）；私有字段 _ 前缀 + 小驼峰（_random、_view），序列化字段写作 [SerializeField] private XxxView _view = null;；方法（含 private）大驼峰。
• 程序集拆分为 SepCore.Base / Runtime / Presentation / Procedure / Editor + Tests（仅 Editor 平台）+ Luban.Runtime；跨程序集引用参考各 .asmdef 的 GUID 列表。
• 命名空间跟随程序集根（如 SepCore.Battle、SepCore.Definition）。