包
包 是一个可分发功能单元——包含资源、Zig源代码、原生库和运行时插件的任意组合——你可以将其安装到项目中，无需手动复制文件。它是Turian对Unity包管理器与资源商店的回应，构建在Zig自身的包管理器之上。
状态： MVP版本实现了资源包的端到端流程（安装→构建→运行）。源代码、原生代码和插件包已在清单中设计，将在后续版本中启用。
概念
| 术语 | 含义 |
|---|---|
| 包 | 创作/分发单元：包含 turian-package.json 清单以及资源、源码、原生库和/或插件入口点。 |
OAP (.oap) |
游戏发布时使用的已烹饪运行时资源容器。包的资源在构建时被烹饪到项目的 game.oap 中。 |
| 模块 | Zig编译单元（b.addModule）——相当于Unity的 asmdef。 |
| 插件 | 包的运行时/编辑器注册入口点。 |
完整的原理和架构请参见 ADR 0001。
project.json 是唯一数据源
每个Turian项目都有一个 project.json，记录项目的标识和声明的依赖关系。项目的 build.zig.zon 是从 project.json 生成的——就像Unity和Flax重新生成它们的 .csproj/.sln 一样。你永远不需要手动编辑 build.zig.zon；CLI和Studio会修改 project.json，并在每次构建时重新生成ZON。这样可以将依赖管理保持在安全、熟悉的JSON中，避免ZON语法错误。
{
"turian_version": "0.16",
"name": "My Game",
"version": "0.0.0",
"dependencies": {
"com.acme.physics": { "url": "git+https://example.com/physics#v1.2.0", "hash": "..." }
}
}
依赖解析（版本、冲突、哈希、锁文件）委托给Zig的包管理器。Turian的层增加了引擎集成清单、发现、资源流水线注入和引擎兼容性检查。
清单：turian-package.json
一个包通过其根目录下的 turian-package.json 声明自身：
{
"name": "com.example.color-palette",
"version": "1.0.0",
"author": "Example",
"description": "A sample asset-only package",
"license": "MIT",
"engine_compat": ">=1.0.0",
"types": ["asset"],
"assets": ["assets"]
}
| 字段 | 必需 | 说明 |
|---|---|---|
name |
✓ | 反向DNS格式，全局唯一。 |
version |
✓ | 语义化版本。 |
types |
✓ | 一个或多个：asset、source、native、plugin。 |
assets |
相对于包根目录的资源目录（默认为 ["assets"]）。 |
|
modules |
导出的Zig模块：{ "name", "root" }（源码包）。 |
|
native |
原生库：{ "name", "kind", "lib", "include" }。 |
|
plugin |
运行时入口点：{ "register", "entry" }。 |
|
engine_compat |
语义化版本范围，与运行中的引擎版本进行校验。 | |
dependencies |
包名 → 语义化版本范围的映射。 |
安装包
# 从本地目录
turian-cli package install ./path/to/package --project my-game
# 从git仓库
turian-cli package install git+https://example.com/my-package --project my-game
默认情况下，包安装到所有项目共享的中央存储库——
$TURIAN_PACKAGE_HOME，否则为 ~/.cache/turian/packages（Windows上为
%APPDATA%\turian\packages）——按 <name>/<version>/ 布局，以便多个版本共存。项目在 project.json 中记录其使用的包和版本；每个项目不会重复。公司也可以通过这种方式建立内部资源商店：一个共享存储库，多个项目。
传递 --vendored 可将包复制到 <project>/packages/ 下（用于与项目一起提交，
或离线工作）。供应商副本优先于存储库。
turian-cli package install ./pkg # → 中央存储库（默认）
turian-cli package install ./pkg --vendored # → <project>/packages/
turian-cli package list --project my-game
turian-cli package info com.example.color-palette --project my-game
turian-cli package remove com.example.color-palette --project my-game # 保留共享存储库副本
下一次 turian-cli build 会发现所有已安装的包（存储库 + 供应商）并自动将其资源烹饪到 game.oap 中——无需手动复制。
已安装包的资源会在 Studio → 资源浏览器 中的只读 包 部分显示：你需要在包本身中编辑，而不是在消费项目中。
冲突与兼容性
- 重复的包名和两个包共享GUID是硬错误，会以明确的诊断信息使构建失败——包作者必须保持资源GUID全局唯一。
- 如果包的
engine_compat范围排除了当前运行的引擎版本，会产生警告（构建仍会继续）。