Bricks

本页面为自动翻译，可能包含错误。如果发现问题，请通过“编辑此页面”链接帮助修正。

brick 是一个带有 package.json 的文件夹,里面装着其他项目可以安装的脚本、资源和程序集定义。引擎自带的相机机架和游戏内 UI 也是 bricks,所以不使用它们的游戏不会附带它们。package.json、锁文件和 Bricks/ 文件夹保留包这个名称;而你直接打交道的一切都叫 brick。

安装

项目在 Bricks/manifest.json 中列出它的 bricks;旁边的 packages-lock.json 精确记录解析结果,应当提交。新项目从内置的 bricks 开始。

{
  "dependencies": {
    "org.mass4.turian.cameras": "builtin:org.mass4.turian.cameras",
    "user.mateo.inventory": "^1.0.0",
    "com.acme.rules": "git+https://github.com/acme/rules.git#v1.2.0",
    "com.acme.levels": "file:../bricks/com.acme.levels-1.0.0.brick"
  }
}

来源	含义
`builtin:<id>`	随引擎发布
`file:<文件夹>`	就地使用的文件夹,用于你正在开发的 brick
`file:<x.brick>`	打包好的 brick,一次性解压到存储中
`git+<url>[#ref]`	git 仓库,在锁中固定到某个提交
`^1.0.0`(版本范围)	取自作用域包含该名称的注册表

bricks 每台机器只存储一次,位于 ~/.gaya/bricks(设置 GAYA_BRICKS 可以移动它,例如移到 CI 缓存中),永远不会复制进项目。一个项目对每个 brick 恰好只有一个版本。

命令行

turian-cli brick … 与 Studio 中的 Project → Bricks… 功能相同。

命令
`add`、`remove`、`list`	修改并显示项目安装的内容
`restore [--locked]`	获取全部内容;`--locked` 在清单与锁不一致时失败(在 CI 中使用)
`update [id…]`	把 git bricks 更新到最新提交
`search`、`registry add\\|list\\|remove`	查找 bricks;选择注册表和你信任的密钥
`new <id>`	新建 brick:清单、程序集定义、脚本
`verify [--against <brick>]`	每个资源都有唯一的 `.meta`;使用 `--against` 时,检查 stub 仍与真实 brick 匹配
`pack [--precast]`、`publish`	写出 `.brick`,或将其加入注册表文件夹
`embed`、`diff`、`rebase`	把 brick fork 进项目、查看你的改动、合并它的下一个版本
`copy`	用新 id 把 brick 的部分资源复制到 `Assets`
`stub`	具有相同 id 的占位符,供基于尚未完成的 brick 开发的团队使用

制作 brick

turian-cli brick new user.you.inventory 创建文件夹。id 是小写的反向 DNS:使用你的域名(com.acme.inventory),没有的话用 user.<名称>.…。

脚本位于程序集定义之下(通过 New → Scripting → Assembly Definition 创建的 .dataasset)。每个脚本和资源都附带 .meta,因为其中的 id 正是其他项目引用的对象;请保持稳定。
名称以 ~ 结尾的文件夹(Samples~、Documentation~、Precast~)不会被导入。
engines 声明哪些引擎版本可用("turian": ">=1.0 <2"),dependencies 声明其他 bricks,nuget 声明预构建程序集所需的 NuGet 包,license 填写 SPDX 表达式。
turian-cli brick pack --precast 把程序集编译到 Precast~/。安装该文件的人加载这些程序集,而不是编译你的代码。

一个可复用的 GitHub workflow MASS4ORG/Turian/.github/workflows/brick.yml 可以验证、打包并发布 brick。

修改已安装的内容

已安装的 bricks 是只读的。按工作量从小到大:

原样使用,通过 id 引用。
制作预制体变体或数据资源变体(turian-cli variant):原件加上你覆盖的值,原件变化时它会跟随。
在 ProjectSettings/PackageImportOverrides.json 中更改 brick 资源的导入方式({ "<asset id>": { "GenerateMips": false } })。
把资源复制到项目中(brick copy):它获得新 id,不再跟随 brick。
嵌入整个 brick(brick embed):在 Bricks/<id> 中得到一份可写副本,优先于已安装的版本。brick diff 列出你的改动;brick rebase 把原版的下一个版本合并进去。

注册表

注册表是带签名索引的静态网站(格式见引擎仓库中的 docs/bricks/registry.md)。项目对其作用域包含的名称从注册表获取 bricks,并只信任自己列出的密钥:

"scopedRegistries": [
  { "name": "studio", "url": "https://bricks.studio.example/v1", "scopes": ["com.studio"], "keys": ["ssh-ed25519 AAAA… studio"] }
]

锁记录每个 brick 的版本、文件哈希和签名密钥。签名是 OpenSSH ed25519 签名,因此发布者使用他们已有的密钥即可。

导入 Unity 包

turian-cli import unitypackage Crates.unitypackage --brick user.you.crates --out bricks/(或 --project <文件夹>)会转换可以对应的内容并报告其余部分。纹理、模型和音频保留它们的 Unity id 和文件夹,Turian 中存在的纹理设置也会一并带来。材质和预制体/场景会被转换;脚本、着色器和动画会列为已跳过。请检查包的许可证:该工具不会更改它。

← 所有文档编辑此页面