Dependencies

A dependency is another Balaur project, imported whole into deps/<alias>/. Its scenes, scripts, textures, fonts and sounds are the game's to use and not to change.

# project.toml
[dependencies]
ui_kit = { project = "dragos/ui-kit", branch = "main" }
fonts = { project = "ana/fonts", tag = "v2" }
stash = { path = "../stash" }

• The key is the alias: the folder name and the use path, [a-z][a-z0-9]*(_[a-z0-9]+)*. Two projects named alike import side by side under two aliases.
• project is owner/name on Forge. A branch follows, a tag pins, and neither follows the project's default branch.
• path is a folder on this machine, served under deps/<alias>/ as it is. No symlink, no copy, no lock.

Adding one

balaur add dragos/ui-kit            # alias ui_kit, default branch
balaur add ana/fonts --tag v2
balaur add ../stash --as stash      # a folder
balaur fetch                        # fill deps/ from project.lock
balaur fetch --update               # newest commit of each branch or tag

• balaur add writes the entry, comments kept, and fetches it.
• project.lock records each Forge dependency's project id, commit and a sha256 of its files. Commit it.
• deps/ is not committed: balaur new and balaur add put /deps/ in .gitignore.
• A fetch whose files do not match the lock is refused and writes nothing.
• Fetched blobs are kept once under the editor's data folder, so every game on one dependency shares one download.
• BALAUR_FORGE names the Forge to ask; BALAUR_FORGE_TOKEN is a personal API token for a private project.
• From the editor: the Library's On Forge kind adds one with a click; the project manager's On Forge tab opens a copy of one.

Paths

A dependency's files name each other from its own root.

• deps/ui_kit/scenes/panel.toml naming art/button.png draws deps/ui_kit/art/button.png, whatever the game keeps at art/.
• The game names the same file deps/ui_kit/art/button.png.
• A relative path a dependency's script builds, such as assets::load("art/hit.png"), reads under its own folder.
• use inside a dependency stops at its folder, so it never links a game module of the same name. The game reaches one with use deps::ui_kit::scripts::button;.
• The dependency's application/ignore and [import.<kind>] defaults cover its own files. Its window, plugins and main scene are the game's to decide.

Read-only

• fs.*, assets::save and a scene save refuse a path under deps/.
• A scene from a dependency is a prefab: place it with instance = "deps/ui_kit/scenes/panel.toml" and change it through overrides. An update reaches the instance and the overrides stay.
• Make local in Assets copies a file into the game and points the game's references at the copy. The copy never updates.
• Edit dependency opens a path dependency's folder in a second editor, or a Forge one's page.
• Move to project moves the game's files into a path dependency and points the game at deps/<alias>/: a shelf for assets kept for later.

Export

• An export pack ships each dependency under deps/<alias>/, its documents rewritten to the game's spelling.
• What nothing names under deps/ is dropped, whatever [export] strip says. The dependency's own [export] include globs keep what its scripts build.
• deps/credits.json lists each dependency's alias, project, commit and [application] license, for a credits screen.

Script API

Not yet

• A dependency with dependencies of its own.
• Native or wasm extensions inside a dependency.
• Dependencies kept on GitHub; a Forge-kept project is the only source today.