# 架构说明

> 本文档是 UnityAI / StrayFog 框架知识库的长期规则，为 Codex (AGENTS.md) 和 Claude Code (CLAUDE.md) 共同引用。

项目文档按三类组织：**核心运行时**、**编辑器工具**、**业务参考**。详细模块索引见 [模块索引](../modules/模块索引.md)。

---

## 分类口径

- **核心运行时**：支撑游戏运行的内部系统，例如实体、UI、网络、资源、事件、场景、对象池。
- **编辑器工具**：Unity Editor 内使用的生成器、Inspector、菜单、配置工具。
- **业务参考**：外部实际项目的业务实现示例，仅作参考，不作为框架规范。

---

## 总体分层

```text
┌─────────────────────────────────────────────────────────────┐
│                     StrayFog Framework                      │
├─────────────────────────────────────────────────────────────┤
│  ┌──────────────────┐  ┌──────────────────┐  ┌───────────┐  │
│  │   GameGeneral    │  │     GameHF       │  │    Core   │  │
│  │   通用工具层     │  │   业务核心层     │  │  基础框架 │  │
│  └────────┬─────────┘  └────────┬─────────┘  └─────┬─────┘  │
├───────────┼─────────────────────┼──────────────────┼─────────┤
│           │                     │                  │         │
│           ▼                     ▼                  ▼         │
│  ┌─────────────────────────────────────────────────────┐    │
│  │                   Unity Engine                      │    │
│  └─────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘
```

### 各层职责

| 层级 | 路径 | 职责描述 |
|------|------|---------|
| **Core 层** | `Assets/StrayFog/Core` | 核心基础框架，模拟行为系统、全局数据管理 |
| **HF 层** | `Assets/Game/GameHFScripte/CopyToHF` | 游戏核心业务框架，资源管理、事件系统、相机管理、UI 管理等 |
| **General 层** | `Assets/Game/GameGeneralScripte` | 通用工具层，状态机、辅助工具、扩展方法等 |

---

## 核心运行时层

核心运行时按技术职责命名，可以对应内部目录。

- **Hotfix 启动/目录**：`GameFunction/GameRoot/`
- **实体系统**：`GameFunction/GameEntity/`、`Logic/EntityData/`
- **UI 系统**：`CopyToHF/UIWindowMgr/`、`GameFunction/UIWindows/`、`GameMono/Scripts/UIMono/`
- **场景系统**：`GameFunction/SceneManager/`、`GameMono/Scenes/`
- **网络系统**：`CopyToHF/Network/`、`GameFunction/WebSocket/`、`GoogleProtobufNetwork/`（如项目使用）
- **资源系统**：`CopyToHF/AssetBundle/`、`CopyToHF/SpriteAtlas/`、`GameHFResource/`
- **事件系统**：`CopyToHF/Event/`、`GameFunction/Event/`
- **对象池**：`CopyToHF/MemoryManager/`、`GameFunction/GameEntity/EntityPool/`
- **通用框架**：`GameGeneralScripte/`、`StrayFog/Core/`

---

## 编辑器工具层

- `Assets/StrayFog/Editor/`：StrayFog 编辑器扩展。
- `Assets/Editor/`：项目编辑器资源与脚本。
- `Assets/AutoBuildScript/Editor/`：编辑器生成工具（如项目使用）。

---

## 程序集边界

已识别 asmdef：

| 程序集 | 主要路径 | 分类 |
|---|---|---|
| `StrayFogCore` | `Assets/StrayFog/Core/` | 核心运行时 |
| `SFEditor` | `Assets/StrayFog/Editor/` | 编辑器工具 |
| `GameHF` | `Assets/Game/GameHFScripte/` | 核心运行时 / hotfix 承载 |
| `GameGeneral` | `Assets/Game/GameGeneralScripte/` | 核心运行时 / general |
| `SFMono` | `Assets/Game/GameMono/` | 核心运行时 / Mono 桥接 |

---

## 依赖方向

```text
业务功能（PVE、PVP、背包、商店等，放在外部业务参考层）
        |
        v
核心运行时（GameRoot、GameEntity、UIWindowMgr、SceneManager、Network、AssetBundle、Event 等）
        |
        v
通用框架 / 第三方插件（StrayFog Core、Spine、DOTween 等）
        |
        v
Unity Engine / .NET Runtime

编辑器工具 -----------------> 读取/生成 核心运行时代码
```

### 依赖规则

| 上层 | 可以依赖 | 禁止依赖 |
|---|---|---|
| 业务功能 | 核心运行时、通用框架 | 编辑器工具、第三方插件源码 |
| 核心运行时 | 通用框架、第三方插件 | 具体业务功能、编辑器工具 |
| 编辑器工具 | 核心运行时源码、生成模板 | 被运行时代码反向引用 |

### 说明

- 运行时代码不要依赖 Editor 程序集。
- 第三方插件不应反向依赖具体玩法模块。
- 业务功能代码按业务命名，代码目录可以仍然按框架/实现组织。

---

## 文档与代码分层对应

| 文档层 | 对应代码层 | 示例 |
|--------|-----------|------|
| `modules/frameworks/` | 核心运行时 | 实体系统、UI 系统、事件系统等 |
| `modules/frameworks/通用框架/框架架构.md` | 核心运行时 + 规范 | StrayFog 整体架构分析 |
| `rules/` | 规范与流程 | 开发规则、工作流清单、架构说明 |

---

## 待确认

- 各项目实际使用的 StrayFog 版本与目录可能略有差异，文档中路径以当前仓库描述的 `Assets/StrayFog/` 和 `Assets/Game/` 结构为准。
- 网络系统、配置生成系统是否为所有使用 StrayFog 的项目标配，需按具体项目确认。

---

## 文档关联

> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。

| 文档 | 关联原因 |
|---|---|
| [modules/frameworks/通用框架/框架架构.md](../modules/frameworks/通用框架/框架架构.md) | 实现视角的框架架构分析 |
| [modules/模块索引.md](../modules/模块索引.md) | 模块索引是架构说明的落地入口，分类口径需一致 |
| [rules/30-模块登记规则.md](30-模块登记规则.md) | 模块登记口径、状态定义与架构分层互相影响 |
| [rules/20-开发规则.md](20-开发规则.md) | 程序集边界、依赖方向与开发规则互相引用 |
| [rules/项目规则入口.md](项目规则入口.md) | 架构说明是项目规则入口索引的关键规则 |