# UnityProjectTools

**Repository Path**: CGameTools/unity-project-tools

## Basic Information

- **Project Name**: UnityProjectTools
- **Description**: 这是收集整理unity项目级别的工具仓库
- **Primary Language**: C#
- **License**: GPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-22
- **Last Updated**: 2026-05-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# UnityProjectTools

## 介绍

这是一个用于收集、整理和维护 Unity 项目级第三方工具的本地 package 仓库。

仓库目标不是把所有工具直接导入当前项目，而是统一维护可复用的工具包，在业务项目中按需接入、独立升级。

## 仓库定位

- `Tools/Assets/Third` 是本地 package 仓库根目录。
- `Third` 下面的每个工具都是一个独立 Unity package。
- 每个工具必须有自己的 `package.json`，用于管理包名、版本和依赖。
- 业务项目按需接入具体工具包，不使用“一个大总包内嵌多个子包”的结构。

推荐目录结构：

```text
Tools/Assets/Third
  com.company.tools.core
    package.json
  com.company.tools.asset-cleaner~
    package.json
  com.company.tools.build-helper~
    package.json
```

## 命名与启用规则

- `Third` 目录本身不加 `~`。
- `~` 只加在具体工具目录名后面，用于表示该工具当前禁用。
- 需要启用某个工具时，将目录名从 `com.company.tools.xxx~` 改为 `com.company.tools.xxx`。
- 工具禁用时，Unity 会忽略该目录内容。
- 工具启用后，才允许被业务项目作为本地 package 引用。

示例：

```text
com.company.tools.asset-cleaner~   // 禁用
com.company.tools.asset-cleaner    // 启用
```

## Package 规范

每个工具都必须是标准 Unity package，并满足以下要求：

- 根目录下必须存在 `package.json`。
- `package.json.name` 使用稳定包名，不随目录是否带 `~` 改变。
- `package.json.version` 作为该工具唯一版本来源。
- 包之间的依赖通过 `package.json.dependencies` 声明。
- 不依赖 README 或人工步骤表达“先装哪个再装哪个”。

推荐包结构：

```text
com.company.tools.xxx
  package.json
  Runtime
  Editor
  Tests~
  Documentation~
  Samples~
```

说明：

- `Runtime` 放运行时代码和资源。
- `Editor` 放编辑器扩展。
- `Tests~`、`Documentation~`、`Samples~` 默认可忽略，按需启用或分发。

## 为什么不做总包嵌套子包

不采用以下结构：

```text
Third/com.company.tools
  package.json
  tool-a/package.json
  tool-b/package.json
```

原因：

- Unity package 的识别单位是“一个根目录 + 一个根目录下的 `package.json`”。
- 子目录里的多个小包不会自动作为独立 package 仓库进行管理。
- 这种结构不利于按工具独立版本、独立依赖、独立导入和独立升级。

因此，正确做法是：

- 每个工具作为 `Third` 下并列的一级 package。
- 如果后续需要“全量安装”，可额外提供一个聚合包，由它在 `dependencies` 中依赖多个工具包。

## 业务项目接入方式

业务项目应通过 local package 方式按需接入工具，不直接把工具当普通 `Assets` 资源拷入使用。

推荐方式：在业务项目的 `Packages/manifest.json` 中添加 `file:` 依赖。

示例：

```json
{
  "dependencies": {
    "com.company.tools.core": "file:F:/Ugit/Tools/unity-project-tools/Tools/Assets/Third/com.company.tools.core"
  }
}
```

规则：

- 路径必须指向具体工具包根目录。
- 只能引用当前未加 `~` 的工具目录。
- 使用正斜杠 `/`。

如果某个工具当前目录为：

```text
Tools/Assets/Third/com.company.tools.core~
```

则业务项目不应引用它。应先去掉 `~`，再添加依赖。

## 版本与升级策略

- 每个工具独立维护版本号。
- 每个工具独立升级，不绑定其他工具同步发版。
- 第三方原始包与自定义适配层尽量分离，避免升级时混杂修改。
- 业务项目默认通过 `file:` 引用本仓库，便于持续联调与升级。
- 当业务项目需要冻结版本或做项目内定制时，可复制到业务项目 `Packages/` 下作为 embedded package。

## 维护原则

- 一个工具只承担一个明确职责，避免演变成巨型杂包。
- 不混用普通 `Assets` 插件模式和 package 模式。
- 依赖关系显式写入 `package.json`，不要依赖隐式目录顺序。
- 工具禁用与启用只通过目录名是否带 `~` 控制，不引入额外的静默回退逻辑。