diff --git a/README.md b/README.md index fc31f18..d810146 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # UnityAI - StrayFog 框架文档中心 -UnityAI 是 StrayFog 框架的通用工作流与知识库。它面向 AI 工具、业务开发人员和框架维护人员；具体 Unity 项目提供真实实现与验证环境，当前主要验证对象为 `CrystalBattle_Client`。 +UnityAI 是 StrayFog 框架的通用工作流与知识库。它面向 AI 工具、业务开发人员和框架维护人员；具体 Unity 项目提供真实实现与验证环境，当前已验证接入项目包括 `FFCard_WeChat`。 ## 快速入口 @@ -45,7 +45,7 @@ UnityAI 是 StrayFog 框架的通用工作流与知识库。它面向 AI 工具 - [编辑器工具](modules/frameworks/编辑器工具/README.md) - [UI 拼接工具](modules/frameworks/编辑器工具/UI拼接工具.md) - [MCP 工具](modules/frameworks/编辑器工具/MCP工具/README.md) -- [CrystalBattle Codex 与 Unity MCP 使用规则](modules/frameworks/编辑器工具/MCP工具/CrystalBattle_Codex_Unity_MCP使用规则.md) +- [Codex 与 Unity MCP 使用规则](modules/frameworks/编辑器工具/MCP工具/Codex_Unity_MCP使用规则.md) ## 工作方式 diff --git a/Tools/CodexUnityMcp/README.md b/Tools/CodexUnityMcp/README.md index 180ae5b..23c67b7 100644 --- a/Tools/CodexUnityMcp/README.md +++ b/Tools/CodexUnityMcp/README.md @@ -1,6 +1,6 @@ -# CrystalBattle Unity MCP +# StrayFog Unity MCP -This local MCP server exposes selected CrystalBattle Unity Editor commands to Codex. +This local MCP server exposes selected StrayFog Unity Editor commands to Codex. ## Architecture @@ -10,7 +10,7 @@ This local MCP server exposes selected CrystalBattle Unity Editor commands to Co ## Unity Setup -Open `CrystalBattle_Client` in Unity. The bridge starts automatically after scripts compile. +Open the target StrayFog Unity project. The bridge starts automatically after scripts compile; use `unity_health` to confirm that the returned project path matches the current task. Manual controls are available from the bridge panel: @@ -28,11 +28,7 @@ From this directory: pnpm install ``` -If `pnpm` is not on `PATH`, use the Codex bundled runtime: - -```powershell -& "C:\Users\admin\.cache\codex-runtimes\codex-primary-runtime\dependencies\bin\pnpm.cmd" install -``` +If `pnpm` is not on `PATH`, locate the configured Codex bundled runtime for the current machine instead of copying a user-specific absolute path. ## Tools @@ -53,8 +49,7 @@ UNITY_MCP_BRIDGE_URL=http://127.0.0.1:17777 ## Codex Config -The workspace includes `.codex/config.toml` with a `crystalbattle-unity` MCP server entry. -Restart Codex after dependency installation so the new MCP server is discovered. +Register this server in the workspace `.codex/config.toml` and restart Codex after dependency installation so the MCP server is discovered. The configured server name is workspace-owned and does not affect the MCP tool names below. --- @@ -65,5 +60,5 @@ Restart Codex after dependency installation so the new MCP server is discovered. | 文档 | 关联原因 | |---|---| | [MCP 工具](../../modules/frameworks/编辑器工具/MCP工具/README.md) | Codex ↔ Unity MCP 工具说明 | -| [CrystalBattle Codex ↔ Unity MCP 使用规则](../../modules/frameworks/编辑器工具/MCP工具/CrystalBattle_Codex_Unity_MCP使用规则.md) | 具体使用规则 | +| [Codex ↔ Unity MCP 使用规则](../../modules/frameworks/编辑器工具/MCP工具/Codex_Unity_MCP使用规则.md) | 具体使用规则 | | [modules/模块索引.md](../../modules/模块索引.md) | 模块索引是项目知识总入口 | diff --git a/Tools/CodexUnityMcp/package.json b/Tools/CodexUnityMcp/package.json index 0a00388..e32e259 100644 --- a/Tools/CodexUnityMcp/package.json +++ b/Tools/CodexUnityMcp/package.json @@ -3,7 +3,7 @@ "version": "0.1.0", "private": true, "type": "module", - "description": "Local MCP server that exposes CrystalBattle Unity Editor commands to Codex.", + "description": "Local MCP server that exposes StrayFog Unity Editor commands to Codex.", "main": "src/server.mjs", "scripts": { "start": "node src/server.mjs" diff --git a/Tools/CodexUnityMcp/src/server.mjs b/Tools/CodexUnityMcp/src/server.mjs index a463471..f9870cd 100644 --- a/Tools/CodexUnityMcp/src/server.mjs +++ b/Tools/CodexUnityMcp/src/server.mjs @@ -9,7 +9,7 @@ const LONG_TIMEOUT_MS = 120000; const bridgeUrl = (process.env.UNITY_MCP_BRIDGE_URL || DEFAULT_BRIDGE_URL).replace(/\/+$/, ""); const server = new McpServer({ - name: "crystalbattle-unity", + name: "strayfog-unity", version: "0.1.0" }); @@ -17,7 +17,7 @@ server.registerTool( "unity_health", { title: "Unity health", - description: "Check whether the CrystalBattle Unity Editor bridge is online.", + description: "Check whether the target StrayFog Unity Editor bridge is online.", inputSchema: {} }, async () => textResult(await getHealth()) diff --git a/hooks/commit-check.ps1 b/hooks/commit-check.ps1 index df93398..fc0eadb 100644 --- a/hooks/commit-check.ps1 +++ b/hooks/commit-check.ps1 @@ -13,8 +13,10 @@ if ([string]::IsNullOrWhiteSpace($RepositoryRoot)) { $RepositoryRoot = (Get-Location).Path } $RepositoryRoot = [System.IO.Path]::GetFullPath($RepositoryRoot) -$gitRoot = & git -C $RepositoryRoot rev-parse --show-toplevel 2>$null | Select-Object -First 1 -if ($LASTEXITCODE -ne 0 -or [string]::IsNullOrWhiteSpace($gitRoot)) { +$gitRootOutput = @(& git -C $RepositoryRoot rev-parse --show-toplevel 2>$null) +$gitExitCode = $LASTEXITCODE +$gitRoot = $gitRootOutput | Select-Object -First 1 +if ($gitExitCode -ne 0 -or [string]::IsNullOrWhiteSpace($gitRoot)) { Write-Error "Git repository was not found: $RepositoryRoot" exit 1 } diff --git a/modules/frameworks/UI窗口系统/README.md b/modules/frameworks/UI窗口系统/README.md index 2408fbe..4377c5e 100644 --- a/modules/frameworks/UI窗口系统/README.md +++ b/modules/frameworks/UI窗口系统/README.md @@ -29,6 +29,8 @@ HFFunCatalogue.UIManager.OpenWindow() 关闭窗口会执行 `OnClose`、隐藏实例并放入窗口缓存。需要释放窗口与资源时使用 UI 管理器公开卸载入口，不直接 Destroy 窗口 Prefab 或绕过管理器修改父节点和 siblingIndex。 +对关闭后不需要缓存的窗口，可在 `HFUIWindowLayer` 上设置 `isUnloadOnClose = true`。窗口管理器会等待该批窗口的 `OnClose` 生命周期全部完成，再销毁该类型的缓存实例并卸载窗口资源；默认值为 `false`，现有窗口继续保留缓存行为。多开窗口仅在同类型窗口均已关闭后才能完成卸载。 + ## 生命周期 | 生命周期 | 用途 | diff --git a/modules/frameworks/UI窗口系统/开发指南.md b/modules/frameworks/UI窗口系统/开发指南.md index 4e7feca..c6a05ed 100644 --- a/modules/frameworks/UI窗口系统/开发指南.md +++ b/modules/frameworks/UI窗口系统/开发指南.md @@ -6,7 +6,7 @@ ```csharp [HFAssetBundlePath("UIWindows/ExampleWindow/ExampleWindow.prefab")] -[HFUIWindowLayer(enHFUICanvasLayer.Dynamic)] +[HFUIWindowLayer(enHFUICanvasLayer.UIWindow, enHFUIWindowLayer.Dynamic, isUnloadOnClose = true)] public partial class ExampleWindow : AbsHFUIWindow { protected override void OnRunAwake() @@ -15,16 +15,16 @@ public partial class ExampleWindow : AbsHFUIWindow // 查找控件、绑定按钮、初始化列表。 } - protected override void OnOpen(object[] _args) + protected override void OnOpen(Action _onOpenComplete) { - base.OnOpen(_args); // 注册事件并刷新本次显示数据。 + base.OnOpen(_onOpenComplete); } - protected override void OnClose() + protected override void OnClose(Action _onCloseComplete) { // 移除事件和计时器。 - base.OnClose(); + base.OnClose(_onCloseComplete); } } ``` @@ -37,11 +37,14 @@ HFFunCatalogue.UIManager.OpenWindow(); 不要直接实例化窗口 Prefab，也不要直接调用内部 `HFUIWindowMgr` 单例。 +`isUnloadOnClose` 默认是 `false`。设为 `true` 后，通过 UI 管理器或窗口自身调用 `CloseWindow` 时，会在 `OnClose` 完成后自动销毁缓存实例并卸载窗口资源，适用于低频且内存占用较大的窗口。频繁开关的窗口应保留默认缓存行为，避免反复加载 Prefab 和 AssetBundle。 + ## 二、生命周期规则 - `OnRunAwake`：实例首次绑定时执行一次，适合控件查找、按钮绑定和虚拟列表初始化。 - `OnOpen`：每次打开执行，适合注册事件、应用参数和刷新数据数量。 - `OnClose`：每次关闭执行，与 `OnOpen` 中的监听、计时器和临时状态对称清理。 +- 重写 `OnOpen(Action)` 或 `OnClose(Action)` 时必须保证完成回调最终且仅调用一次；自动卸载窗口会在 `OnClose` 完成回调后执行。 - 列表初始化不能依赖数据已经到达；先以数量 `0` 初始化，数据准备后再刷新数量。 ## 三、单列虚拟列表 diff --git a/modules/frameworks/UI窗口系统/界面拼接.md b/modules/frameworks/UI窗口系统/界面拼接.md index 0528889..bd23e7d 100644 --- a/modules/frameworks/UI窗口系统/界面拼接.md +++ b/modules/frameworks/UI窗口系统/界面拼接.md @@ -77,4 +77,4 @@ JSON 生成适合批量创建稳定层级和组件，不代替视觉校对、业 | [UI 窗口系统](README.md) | 窗口框架和资源路径 | | [UI 开发指南](开发指南.md) | 生命周期和虚拟列表接口 | | [UI 拼接工具](../编辑器工具/UI拼接工具.md) | MCP JSON/Prefab 工具 | -| [MCP 使用规则](../编辑器工具/MCP工具/CrystalBattle_Codex_Unity_MCP使用规则.md) | Codex 与 Unity 的调用规则 | +| [MCP 使用规则](../编辑器工具/MCP工具/Codex_Unity_MCP使用规则.md) | Codex 与 Unity 的调用规则 | diff --git a/modules/frameworks/编辑器工具/MCP工具/CrystalBattle_Codex_Unity_MCP使用规则.md b/modules/frameworks/编辑器工具/MCP工具/Codex_Unity_MCP使用规则.md similarity index 98% rename from modules/frameworks/编辑器工具/MCP工具/CrystalBattle_Codex_Unity_MCP使用规则.md rename to modules/frameworks/编辑器工具/MCP工具/Codex_Unity_MCP使用规则.md index 0c41eab..bb841bb 100644 --- a/modules/frameworks/编辑器工具/MCP工具/CrystalBattle_Codex_Unity_MCP使用规则.md +++ b/modules/frameworks/编辑器工具/MCP工具/Codex_Unity_MCP使用规则.md @@ -1,4 +1,4 @@ -# CrystalBattle Codex 与 Unity MCP 使用规则 +# Codex 与 Unity MCP 使用规则 ## 一、定位 diff --git a/modules/frameworks/编辑器工具/MCP工具/README.md b/modules/frameworks/编辑器工具/MCP工具/README.md index faca3a5..1a2f2df 100644 --- a/modules/frameworks/编辑器工具/MCP工具/README.md +++ b/modules/frameworks/编辑器工具/MCP工具/README.md @@ -1,6 +1,6 @@ # MCP 工具 -Codex 通过本地 Node MCP Server 与 Unity Editor Bridge 交互，当前实现已经在 CrystalBattle_Client 验证。 +Codex 通过本地 Node MCP Server 与 Unity Editor Bridge 交互。该实现不绑定具体游戏工程，当前已在 `FFCard_WeChat` 验证。 ## 实现位置 @@ -18,14 +18,14 @@ Codex 通过本地 Node MCP Server 与 Unity Editor Bridge 交互，当前实现 - UI JSON 生成 Prefab - Prefab 导出 JSON -具体调用、UI 前置阅读、安全边界和排错见 [CrystalBattle Codex 与 Unity MCP 使用规则](CrystalBattle_Codex_Unity_MCP使用规则.md)。 +具体调用、UI 前置阅读、安全边界和排错见 [Codex 与 Unity MCP 使用规则](Codex_Unity_MCP使用规则.md)。 ## 文档关联 | 文档 | 关联原因 | |---|---| | [编辑器工具入口](../README.md) | 编辑器工具模块入口 | -| [MCP 使用规则](CrystalBattle_Codex_Unity_MCP使用规则.md) | 具体调用规范 | +| [MCP 使用规则](Codex_Unity_MCP使用规则.md) | 具体调用规范 | | [MCP Server README](../../../../Tools/CodexUnityMcp/README.md) | 安装和实现 | | [模块索引](../../../模块索引.md) | 模块状态 | | [工作流清单](../../../../rules/40-工作流清单.md) | Unity 自动化验证步骤 | diff --git a/modules/frameworks/编辑器工具/UI拼接工具.md b/modules/frameworks/编辑器工具/UI拼接工具.md index 1d69f1a..ca71dd7 100644 --- a/modules/frameworks/编辑器工具/UI拼接工具.md +++ b/modules/frameworks/编辑器工具/UI拼接工具.md @@ -101,4 +101,4 @@ Assets/Game/GameHFResource/<语言>/UIWindows//.prefab | [编辑器工具入口](README.md) | 编辑器工具模块入口 | | [UI 窗口系统](../UI窗口系统/README.md) | 窗口框架和资源路径 | | [UI 界面拼接](../UI窗口系统/界面拼接.md) | 视觉与 Prefab 流程 | -| [MCP 使用规则](MCP工具/CrystalBattle_Codex_Unity_MCP使用规则.md) | Codex 调用和安全边界 | +| [MCP 使用规则](MCP工具/Codex_Unity_MCP使用规则.md) | Codex 调用和安全边界 | diff --git a/rules/00-项目概览.md b/rules/00-项目概览.md index 71404f4..58e6270 100644 --- a/rules/00-项目概览.md +++ b/rules/00-项目概览.md @@ -5,11 +5,11 @@ `UnityAI` 是 StrayFog 框架的通用知识库和工作流标准，服务 AI 工具、业务开发人员与框架维护人员。本仓库不保存完整游戏业务代码，具体结论必须结合接入的 Unity 项目验证。 - **通用标准仓库**：`UnityAI` -- **当前主要验证对象**：`CrystalBattle_Client` +- **当前已验证接入项目**：`FFCard_WeChat` - **文档语言**：中文 - **适用范围**：使用 StrayFog 框架的 Unity 项目 -CrystalBattle_Client 用于验证目录、接口、生成流程和平台行为，但项目专有实现不应被写成所有项目都必须遵守的框架规则。 +接入项目用于验证目录、接口、生成流程和平台行为，但项目专有实现不应被写成所有项目都必须遵守的框架规则。新增项目时应先读取其真实目录、Unity 版本与 Git 状态，不沿用其他项目的路径假设。 ## 目录 diff --git a/rules/10-架构说明.md b/rules/10-架构说明.md index b5eb916..ea5bb6b 100644 --- a/rules/10-架构说明.md +++ b/rules/10-架构说明.md @@ -55,7 +55,7 @@ CopyToX 会删除并重新生成目标子目录，同时把 `ESF_` 标记转换 ## 当前验证基线 -AI 每次都应读取目标项目的 `ProjectSettings/ProjectVersion.txt`，不把文档中的版本当作永久值。当前 CrystalBattle_Client 的验证基线为 Unity `2022.3.29f1`。 +AI 每次都应读取目标项目的 `ProjectSettings/ProjectVersion.txt`，不把文档中的版本当作永久值。当前 `FFCard_WeChat` 的已验证基线为 Unity `2022.3.29f1`。 ## 文档关联 diff --git a/rules/项目规则入口.md b/rules/项目规则入口.md index 157f82b..a72c048 100644 --- a/rules/项目规则入口.md +++ b/rules/项目规则入口.md @@ -1,6 +1,6 @@ # UnityAI 项目规则入口 -UnityAI 是 StrayFog 框架的通用工作流与知识标准。具体游戏项目负责提供真实代码、资源和验证环境；当前主要验证对象为 `CrystalBattle_Client`。 +UnityAI 是 StrayFog 框架的通用工作流与知识标准。具体游戏项目负责提供真实代码、资源和验证环境；当前已验证接入项目包括 `FFCard_WeChat`。 ## 快速启动