# 项目概览

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

## 摘要

`UnityAI` 是 **StrayFog 框架文档中心**，用于沉淀 StrayFog 框架的架构设计、核心功能使用规范、开发流程和项目管理规则。

本仓库本身不包含游戏业务代码，而是一个**面向 AI 工具与人工开发者的知识库**。AI 工具通过 ai/rules/modules/ 下的规则与模块文档快速理解框架；人工开发者可以通过 `modules/frameworks/` 下的框架模块文档和 `rules/` 下的规则文档学习使用。

- **项目名**：UnityAI
- **副标题**：StrayFog 框架文档中心
- **目标读者**：AI 工具、业务开发人员、框架维护人员
- **文档语言**：中文
- **适用项目**：GiftGameX、OnlineGame 等使用 StrayFog 框架的项目

---

## 重要目录

| 目录 | 用途 |
|------|------|
| `modules/frameworks/` | 核心框架模块文档：实体、UI、事件、资源、对象池等。 |
| `rules/` | 项目长期规则：工作方式、扫描范围、任务流程、归档规则。 |
| `modules/` | 项目知识总入口：框架模块、核心功能、编辑器工具。 |
| `hooks/` | 共享 hook：归档检查、提交检查、文档关联同步。 |
| `specs/` | 大需求 / 新模块的 OpenSpec 归档。 |
| `modules/frameworks/编辑器工具/UI工具/` | UI 预制体 JSON 转换工具脚本。 |
| `business-reference/` | 外部实际项目业务参考，与框架核心分离。 |

---

## 核心子系统

StrayFog 框架主要包含以下子系统：

| 子系统 | 主要职责 | 对应文档 |
|--------|---------|---------|
| **模拟行为系统** | 解耦 MonoBehaviour，模拟完整生命周期 | [SimulateBehaviour](../modules/frameworks/通用框架/README.md) |
| **对象池系统** | GameObject 对象池、脚本对象池、类实例池 | [对象池](../modules/frameworks/内存对象管理/README.md) |
| **事件系统** | CTC/STC 事件派发、监听与释放 | [事件系统](../modules/frameworks/事件系统/README.md) |
| **资源管理系统** | AssetBundle 加载、依赖管理、语言包、图集 | [资源管理](../modules/frameworks/资源管理/README.md) |
| **相机管理系统** | 多相机管理、相机堆栈、渲染顺序 | [相机系统](../modules/frameworks/相机系统/README.md) |
| **实体系统** | 实体创建、System-Model 架构、实体池 | [实体系统](../modules/frameworks/实体系统/README.md) |
| **UI 窗口系统** | UI 窗口管理、层级、生命周期、事件释放 | [UI 窗口系统](../modules/frameworks/UI窗口系统/README.md) |
| **技能系统** | 技能触发器、释放器、配置联动 | [技能系统](../modules/frameworks/技能系统/README.md) |
| **场景系统** | 场景加载、资源配置、生命周期 | [场景系统](../modules/frameworks/场景系统.md) |
| **网络系统** | WebSocket、protobuf、消息映射（如项目使用） | [网络系统](../modules/frameworks/网络系统.md) |
| **配置生成系统** | XLSX / protobuf 配置生成（如项目使用） | [配置生成](../modules/frameworks/数据配置框架.md) |

---

## 文档分层

```text
AI 接入层
  AGENTS.md / CLAUDE.md / RULES.md / ai/AI接入入口.md
      |
      v
项目规则层
  rules/项目规则入口.md + 00~70 规则文件
      |
      v
项目知识层
  modules/模块索引.md
      |
      ├── 框架模块（frameworks/）
      ├── 编辑器工具（editor-tools/）
      └── 使用示例（examples/）
      |
      v
业务参考层
  business-reference/playballoons/
      |
      v
Hook / Spec / Plan
  hooks/ / specs/ / plans/
```

---

## 使用方式

### AI 工具

1. 读取 `ai/AI接入入口.md`
2. 读取 `rules/项目规则入口.md`
3. 按任务范围读取 `modules/` 下具体模块文档
4. 如需了解外部项目业务参考，读取 `business-reference/playballoons/业务框架映射接口.md`

### 人工开发者

1. 新成员从 [开发规则](20-开发规则.md) 开始。
2. 了解架构看 [架构说明](10-架构说明.md) 和 [通用框架/框架架构](../modules/frameworks/通用框架/框架架构.md)。
3. 使用具体系统看 `modules/frameworks/` 下对应框架模块。
4. 遇到问题看 [开发规则/常见问题](20-开发规则.md#常见问题)。

---

## 关键约束

- `ai/rules/modules/` 是 StrayFog 框架知识的唯一事实来源；旧中文教程内容已迁移合并至此。
- 修改 `modules/` 中模块文档后，必须同步更新 `modules/模块索引.md` 和相关规则文件。
- `business-reference/` 中的内容来自外部实际项目，仅作参考，不作为 StrayFog 框架规范。
- 不要把项目规则复制进系统提示或 AI 工具私有目录。

---

## 文档关联

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

| 文档 | 关联原因 |
|---|---|
| [rules/项目规则入口.md](项目规则入口.md) | 项目概览是项目规则入口引用的核心信息 |
| [rules/10-架构说明.md](10-架构说明.md) | 重要顶层目录与总体分层、程序集边界相关 |
| [rules/20-开发规则.md](20-开发规则.md) | 生成内容约束与开发规则互相引用 |
| [rules/70-项目设置.md](70-项目设置.md) | 扫描范围、跳过目录与项目概况中的目录说明相关 |
| [modules/模块索引.md](../modules/模块索引.md) | 模块索引是项目知识总入口 |