240 lines
5.8 KiB
Markdown
240 lines
5.8 KiB
Markdown
# 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` 声明模块间依赖关系。
|