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 .dataasset from 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.
  • engines states which engine versions work ("turian": ">=1.0 <2"), dependencies other bricks, nuget the NuGet packages prebuilt assemblies need, license an SPDX expression.
  • turian-cli brick pack --precast compiles the assemblies into Precast~/. 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:

  1. Use it as it is, by id.
  2. 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.
  3. Change how a brick's assets import in ProjectSettings/PackageImportOverrides.json ({ "<asset id>": { "GenerateMips": false } }).
  4. Copy an asset into the project (brick copy): it gets a new id and stops following the brick.
  5. Embed the whole brick (brick embed): a writable copy in Bricks/<id> that wins over the installed one. brick diff lists your changes; brick rebase merges 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.


← All docs Edit this page