# 架构说明

本文档定义 StrayFog 项目的代码分层、真实源码位置与生成边界。具体项目路径不同的时候，以项目配置和生成器实现为准。

## 总体分层

```text
游戏业务（GameFunction / GameMono / GameHFResource）
                    |
                    v
生成后的运行时框架（CopyToHF / GameGeneral）
                    |
                    v
StrayFog Core / Unity Engine / 第三方插件

StrayFog Editor / CopyToX --------------> 生成运行时代码与资源
```

## 源码与生成结果

| 路径 | 类型 | 修改规则 |
|---|---|---|
| `Assets/StrayFog/Core` | 直接维护的框架运行时源码 | 按框架需求直接修改并构建 `StrayFogCore` |
| `Assets/StrayFog/Editor` | Editor 工具与生成器源码 | 直接修改；运行时代码不得反向依赖 |
| `Assets/StrayFog/Editor/CopyToX/CopyToHF` | `ESF_` 热更框架源码 | 框架修改的主要源头，修改后执行 CopyToX |
| `Assets/StrayFog/Editor/CopyToX/CopyToGeneral` | General 层生成源码 | 修改后执行 CopyToX |
| `Assets/Game/GameHFScripte/CopyToHF` | CopyToX 生成的 `HF_` 运行时代码 | 禁止手改，只检查生成差异 |
| `Assets/Game/GameGeneralScripte/CopyToGeneral` | CopyToX 生成的 General 代码 | 禁止手改，只检查生成差异 |
| `Assets/Game/GameHFScripte/GameFunction` | 项目热更业务代码 | 业务需求直接修改 |
| `Assets/Game/GameMono` | 项目 Mono 桥接和组件代码 | 直接修改并构建 `SFMono` |
| `Assets/Game/GameHFResource` | Prefab、图集、配置和 AssetBundle 资源 | 通过 Unity 或已有工具修改并验证序列化结果 |
| `Assets/Editor/Command` | 项目 Editor/MCP 工具 | 直接修改，在 Unity 主线程验证 Editor API |

CopyToX 会删除并重新生成目标子目录，同时把 `ESF_` 标记转换为 `HF_`。因此目标目录中的手工改动会丢失，也不能作为下一次生成的源码。

## 程序集

| 程序集 | 主要职责 |
|---|---|
| `StrayFogCore` | StrayFog 基础运行时 |
| `SFEditor` | StrayFog Editor 工具 |
| `GameGeneral` | 生成后的通用运行时层 |
| `GameHF` | 热更框架与业务代码 |
| `SFMono` | MonoBehaviour、UIMono 和桥接层 |

项目接入第三方插件时，以 asmdef 依赖为准，不把第三方源码复制为框架规则。

## 依赖方向

- 业务代码可以依赖公开框架入口和通用层。
- 业务调用优先通过 `HFFunCatalogue` 等项目统一入口，不绕过封装直接依赖内部单例。
- Core 和生成后的框架运行时不能依赖具体业务模块。
- 运行时代码不能依赖 Editor 程序集。
- Editor 工具可以读取或生成运行时代码和资源，但生成结果不能成为生成器的反向依赖。

## 当前验证基线

AI 每次都应读取目标项目的 `ProjectSettings/ProjectVersion.txt`，不把文档中的版本当作永久值。当前 CrystalBattle_Client 的验证基线为 Unity `2022.3.29f1`。

## 文档关联

| 文档 | 关联原因 |
|---|---|
| [开发规则](20-开发规则.md) | 源码边界对应具体修改规则 |
| [工作流清单](40-工作流清单.md) | 生成和验证步骤引用本架构 |
| [模块索引](../modules/模块索引.md) | 模块职责和入口 |
| [通用框架](../modules/frameworks/通用框架/框架架构.md) | StrayFog 实现视角的架构说明 |