# Unity Package 开发与 Git 分发指南

## 概述

本文档描述如何将 Unity 代码组织为 Package 结构，并通过 Git 仓库进行版本管理和分发更新。适用于 FlowScope 框架各模块的独立开发与集成。

## Package 标准结构

```text
com.flowscope.xxx/
├── package.json              # 必须 — 包的元数据与依赖声明
├── README.md                 # 包说明
├── CHANGELOG.md              # 版本变更记录
├── LICENSE                   # 许可证
├── Runtime/
│   ├── ExampleScript.cs
│   └── com.flowscope.xxx.Runtime.asmdef
├── Editor/
│   └── com.flowscope.xxx.Editor.asmdef
├── Tests/
│   ├── Runtime/
│   │   └── com.flowscope.xxx.Tests.Runtime.asmdef
│   └── Editor/
│       └── com.flowscope.xxx.Tests.Editor.asmdef
└── Samples~/                 # 可选示例（~ 后缀表示在 Package Manager 中隐藏）
    └── Demo/
        └── ...
```

## package.json 说明

```json
{
  "name": "com.flowscope.xxx",
  "version": "0.1.0",
  "displayName": "FlowScope XXX",
  "description": "模块描述",
  "unity": "2022.3",
  "dependencies": {
    "com.flowscope.core": "0.1.0"
  },
  "author": {
    "name": "FlowScope Team"
  },
  "repository": {
    "type": "git",
    "url": "https://github.com/flowscope/xxx.git"
  }
}
```

关键字段：

| 字段 | 说明 |
|------|------|
| `name` | 反向域名格式，全局唯一 |
| `version` | 语义化版本（SemVer） |
| `unity` | 最低兼容 Unity 版本 |
| `dependencies` | 该包依赖的其他 Package |

## 开发工作流

### 推荐：在 Unity 项目内开发

直接在目标 Unity 项目的 `Packages/` 目录下创建包文件夹，Unity 自动识别，开发体验与 `Assets/` 中写脚本一致。

```text
MyUnityProject/
├── Assets/
│   └── Scenes/
│       └── Test.unity          # 测试场景
├── Packages/
│   ├── manifest.json
│   └── com.flowscope.xxx/      ← 在这里开发
│       ├── package.json
│       ├── Runtime/
│       └── Editor/
```

`manifest.json` 中自动生成引用：

```json
{
  "dependencies": {
    "com.flowscope.xxx": "file:com.flowscope.xxx"
  }
}
```

### 迁移已有代码

如果代码已在 `Assets/` 中：

1. 在 `Packages/` 下建好包结构和 `package.json`
2. 将脚本从 `Assets/` **移动**到 `Packages/com.flowscope.xxx/Runtime/`
3. 创建 `.asmdef`（Assembly Definition），Packages 下的脚本不会自动编译到 `Assembly-CSharp.dll`
4. Unity 重新编译，确认引用无误

## Assembly Definition (.asmdef)

Packages 下的代码必须通过 `.asmdef` 显式声明程序集。

**Runtime 层：**

```json
{
  "name": "FlowScope.XXX.Runtime",
  "rootNamespace": "FlowScope.XXX",
  "references": [],
  "includePlatforms": [],
  "excludePlatforms": [],
  "allowUnsafeCode": false,
  "overrideReferences": false,
  "precompiledReferences": [],
  "autoReferenced": true,
  "defineConstraints": [],
  "versionDefines": [],
  "noEngineReferences": false
}
```

**Editor 层：**

```json
{
  "name": "FlowScope.XXX.Editor",
  "rootNamespace": "FlowScope.XXX.Editor",
  "references": ["FlowScope.XXX.Runtime"],
  "includePlatforms": ["Editor"],
  "excludePlatforms": [],
  "allowUnsafeCode": false,
  "overrideReferences": false,
  "precompiledReferences": [],
  "autoReferenced": true,
  "defineConstraints": [],
  "versionDefines": [],
  "noEngineReferences": false
}
```

## Git 分发与版本管理

### 推送到 Git 仓库

```powershell
cd Packages/com.flowscope.xxx
git init
git add .
git commit -m "初始化 FlowScope XXX Package"
git remote add origin https://github.com/flowscope/xxx.git
git push -u origin main
```

### 在其他项目中引用

修改目标项目的 `Packages/manifest.json`：

```json
{
  "dependencies": {
    "com.flowscope.xxx": "https://github.com/flowscope/xxx.git"
  }
}
```

### 版本引用方式

| 方式 | 写法 | 适用场景 |
|------|------|----------|
| 最新 main | `"https://github.com/flowscope/xxx.git"` | 内部开发 |
| 指定版本 | `"https://github.com/flowscope/xxx.git#v1.2.0"` | 正式项目 |
| 指定分支 | `"https://github.com/flowscope/xxx.git#dev"` | 测试分支 |
| 指定 commit | `"https://github.com/flowscope/xxx.git#abc1234"` | 精确锁定 |
| 本地路径 | `"file:../../com.flowscope.xxx"` | 本地联调 |

### 版本发布流程

```powershell
# 开发完成后打 tag
git tag v1.0.0
git push origin v1.0.0
```

其他项目引用指定版本：

```json
"com.flowscope.xxx": "https://github.com/flowscope/xxx.git#v1.0.0"
```

### 更新已安装的 Package

- Unity 编辑器：Window → Package Manager → 选择对应包 → 点击 Update
- 手动：删除 `Library/PackageCache/` 中对应缓存后重启 Unity

## .gitignore 注意事项

Package 仓库的 `.gitignore`：

```gitignore
# Unity 生成的 meta 文件不要忽略（Package 需要）
# 但 Library/ 下的内容不提交
[Ll]ibrary/
[Tt]emp/
[Oo]bj/
[Bb]uild/
[Bb]uilds/
[Ll]ogs/
[Uu]ser[Ss]ettings/

# IDE
.vs/
.vscode/
.idea/
*.csproj
*.unityproj
*.sln
*.suo
*.tmp
*.user
*.pidb
*.booproj
```

## FlowScope 模块化策略

根据 FlowScope Core Kernel 的架构原则，各模块独立为 Package：

```text
FlowScope/
├── Core/          → com.flowscope.core        （纯 C#，无 Unity 依赖）
├── UI/            → com.flowscope.ui           （MVVM + uGUI 适配）
├── Flow/          → com.flowscope.flow         （时间线编排）
├── Events/        → com.flowscope.events       （事件流）
├── Config/        → com.flowscope.config       （配置加载隔离）
├── Res/           → com.flowscope.res          （资源生命周期）
└── Modules/       → 各扩展模块
```

每个模块为独立 Git 仓库，通过 `package.json` 的 `dependencies` 声明模块间依赖关系。