Bricks
A brick is a folder with a package.json that holds scripts, assets and assembly definitions other projects can
install. The engine's own camera rigs and in-game UI are bricks, so a game that does not use them does not ship them.
package.json, the lock file and the Bricks/ folder keep their package names; everything you talk to is called a
brick.
Installing
A project lists its bricks in Bricks/manifest.json; packages-lock.json next to it records exactly what was
resolved and should be committed. New projects start with the built-in 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"
}
}
| Source | Meaning |
|---|---|
builtin:<id> |
ships with the engine |
file:<folder> |
a folder used in place, for a brick you are developing |
file:<x.brick> |
a packed brick, extracted once into the store |
git+<url>[#ref] |
a git repository, pinned to a commit in the lock |
^1.0.0 (a version range) |
taken from the registry scoped to the name |
Bricks are stored once per machine in ~/.gaya/bricks (set GAYA_BRICKS to move it, for example into a CI cache) and
never copied into projects. A project has exactly one version of each brick.
From the command line
turian-cli brick … and Project → Bricks… in Studio do the same things.
| Command | |
|---|---|
add, remove, list |
change and show what the project installs |
restore [--locked] |
fetch everything; --locked fails when the manifest and lock disagree (use it in CI) |
update [id…] |
move git bricks to their newest commit |
search, registry add\|list\|remove [--studio] |
find bricks; choose the registries bricks come from |
new <id> |
start a brick: manifest, assembly definition, script |
verify [--against <brick>] |
every asset has a unique .meta; with --against, a stub still matches the real brick |
pack [--precast], publish |
write a .brick, or upload it to an asset store or a registry folder |
login, releases, yank [--undo], deprecate |
manage what you published on an asset store |
embed, diff, rebase |
fork a brick into the project, see your changes, merge its next release |
copy |
copy some of a brick's assets into Assets under new ids |
stub |
placeholder with the same ids, for teams building on a brick that is not finished |
Making a brick
turian-cli brick new user.you.inventory creates the folder. Ids are lowercase reverse-DNS: use your domain
(com.acme.inventory), or user.<name>.… if you have none.
- Scripts live under an assembly definition (a
.dataassetfrom New → Scripting → Assembly Definition). Every script and asset ships its.meta, because the ids in them are what other projects refer to; keep them stable. - Folders whose name ends in
~(Samples~,Documentation~,Precast~) are not imported. enginesstates which engine versions work ("turian": ">=1.0 <2"),dependenciesother bricks,nugetthe NuGet packages prebuilt assemblies need,licensean SPDX expression.turian-cli brick pack --precastcompiles the assemblies intoPrecast~/. People who install that file load the assemblies instead of compiling your code.
A reusable GitHub workflow, MASS4ORG/Turian/.github/workflows/brick.yml, verifies, packs and releases a brick.
Changing what you installed
Installed bricks are read-only. In order of effort:
- Use it as it is, by id.
- Make a prefab variant or a data asset variant (
turian-cli variant): the original plus the values you override, and it follows the original when it changes. - Change how a brick's assets import in
ProjectSettings/PackageImportOverrides.json({ "<asset id>": { "GenerateMips": false } }). - Copy an asset into the project (
brick copy): it gets a new id and stops following the brick. - Embed the whole brick (
brick embed): a writable copy inBricks/<id>that wins over the installed one.brick difflists your changes;brick rebasemerges the original's next release into them.
Registries
A registry serves a signed index of bricks: the MASS4 asset store, or a static site (format: docs/bricks/registry.md
in the engine repository). The public MASS4 registry is already configured. To add another, give its address:
turian-cli brick registry add store.example.com # or --studio for the studio's own bricks
Turian reads the rest from the registry: its name (the host), the brick names it serves (its scopes, such as
com.studio) and the key it signs with. It prints the key's fingerprint; remove the registry if you do not recognize
it. In Studio, open Bricks → Registries, type the address and save. Everything can also be written by hand:
"scopedRegistries": [
{ "name": "studio", "url": "https://bricks.studio.example/v1", "scopes": ["com.studio"], "keys": ["ssh-ed25519 AAAA… studio"] }
]
When several registries serve the same names, a brick comes from the first that has it. The lock records each brick's version, file hash, registry and signing key. Signatures are OpenSSH ed25519 signatures, so publishers use the keys they already have.
Publishing to the asset store
Create an access token on the store's Manage page with the publish permission, then:
turian-cli brick login store.mass4.org # asks for the token, saves it in ~/.gaya/credentials.json
turian-cli brick publish path/to/brick --store store.mass4.org --key registry-signing-key
turian-cli brick releases store.mass4.org
turian-cli brick yank store.mass4.org com.acme.rules 1.2.0 # --undo puts it back
turian-cli brick deprecate store.mass4.org com.acme.rules 1.2.0 --reason "Use 2.x"
Versions are never deleted or replaced: publish a new version instead. A yanked version stays available to projects
whose lock already pins it, and is never chosen again. A release outside the store's auto-approved names waits for
approval before consumers see it; publish says when that is the case.
Bricks in CI
Commit Bricks/manifest.json and packages-lock.json, point GAYA_BRICKS at a cached folder and restore with
--locked, so the build installs exactly what the lock records. Public bricks need no token; for private ones, store
a read token as the secret GAYA_REGISTRY_TOKEN_<REGISTRY> (the registry name upper-cased, other characters as _).
GitHub Actions:
env:
GAYA_BRICKS: ${{ github.workspace }}/.bricks
steps:
- uses: actions/checkout@v4
- uses: actions/cache@v4
with:
path: .bricks
key: bricks-${{ hashFiles('Bricks/packages-lock.json') }}
- run: turian-cli brick restore --locked
- run: turian-cli export
GitLab CI:
build:
variables:
GAYA_BRICKS: $CI_PROJECT_DIR/.bricks
cache:
key:
files: [Bricks/packages-lock.json]
paths: [.bricks/]
script:
- turian-cli brick restore --locked
- turian-cli export
restore also runs --locked by itself whenever CI=true, which both services set.
Importing a Unity package
turian-cli import unitypackage Crates.unitypackage --brick user.you.crates --out bricks/ (or --project <folder>)
converts what maps and reports the rest. Textures, models and audio keep their Unity ids and folders, and texture
settings that exist in Turian come along. Materials and prefabs/scenes are converted; scripts, shaders and animation are
listed as skipped. Check the package's license: the tool does not change it.