Tools
Ways to write, check and play Bruja outside a game.
- Web IDE: write and play in the browser, share stories as links
- Command line: play, check, compile and disassemble
- VS Code extension: highlighting and live errors
- Tests: for people working on the language itself
Web IDE
web/ is a browser app with an editor on the left and the story playing on the right. It runs
the real compiler and VM (compiled to WebAssembly), so a story behaves exactly as it will in a
game. See web/README.md to build and serve it.
Writing. The editor helps while you learn:
- Suggestions as you type (or press Ctrl+Space): keywords, your own variables, functions and
threads (after
->,<-and insidevisits("…")), built-in functions, methods after a.(items.push,math.floor,g.next), and text variations after[in dialogue. Each one comes with a short explanation and an example. Pick one with Enter or Tab. - Templates for the building blocks. Type
question,if,for,func,generator,#… and pick the template, or use the Insert menus above the editor (Dialogue, Choices, Threads, Logic, Functions, Game), which show the syntax each one writes. Tab jumps between the parts to fill in. - Hover help: point at a keyword, a built-in, a
>*+#->mark, a tag or one of your own names to see what it is. - Go to definition: Ctrl+click (Cmd+click on a Mac) or F12 on a thread or name jumps to where it’s defined.
- Automatic indentation: after a line ending in
:and after a choice, the next line is indented for you. - Plain-language errors: errors and warnings are underlined as you type and listed under the
editor, with a tip and, where the fix is obvious (a missing
:,=instead of==, a choice that isn’t indented, a misspelled thread or variable), a button that fixes it.
Localizing. Localize in the top bar adds line IDs and exports the lines to a .csv
tab; add a tab per language (fr.csv), translate its text column, and pick the language above
the player. Share links carry the tables, and the player page has the same language picker.
See localization for the whole workflow.
Files. + File above the editor adds a file to the story and an import line for it.
Each file has a tab; errors in other files are counted under the problems list (click to go
there), Ctrl+click on a name defined in another file opens it, and clicking a line in the
player opens the file it came from. Share links carry every file.
Every change recompiles the story and replays your choices up to where you were, so you can tweak a line and see it in place. If a choice you took no longer exists, replay stops there and tells you. The line that’s playing is highlighted in the editor, and clicking a line in the player shows its code.
Playing. Lines appear one at a time (click, or press Space); tick Instant to show them
all at once. Pick choices with the mouse or keys 1–9. Rewind undoes the last choice;
Restart starts over. wait shows as a chip with a Continue button.
Debugging. The tabs under the player show:
| Tab | |
|---|---|
| Variables | every global and its value. Objects and arrays open with ▸ to show what’s inside. Click any value, including one inside an object or array, to change it; type any expression (10, "Ash", gold * 2). |
| Threads | each thread with its visit count. Jump goes straight there. |
| Output | print(...) output, and calls to game functions (extern), which are stubbed to do nothing and return null. |
| Tags | the tags on the last line and on the current choices. |
The Seed field fixes the dice and random text, so a playthrough is repeatable.
Files on your computer. Open → Open a folder on your computer… opens a story folder (the
one with story.bruja, for example MyGame/Story/ in your game’s git repo) and edits the files
there: changes are saved to them as you type, and you commit them with your usual git tool.
Changes made outside the app (another editor, git pull, switching branches) are picked up when
you come back to the tab; if a file changed in both places, the app asks which version to keep.
Save to a folder… in the Files panel moves a story from the browser into a folder. This works
in Chrome, Edge, Opera, Vivaldi, Arc and Brave on a computer (Brave has it off by default: turn on
brave://flags/#file-system-access-api). Firefox, Safari and phone browsers don’t let websites
edit your files; there the button explains this, and Download .zip / Open .zip move
stories in and out instead.
Your stories are saved in the browser as you type (Open lists them). Examples has a few stories that show off the language, and ? opens the tutorial and the language reference.
Sharing. Share gives you:
- a play link that opens a clean reading view of the story, with no editor. The story is packed into the link itself, so nothing is uploaded anywhere. The player remembers how far each reader got. Links are roughly 40% of the story’s size: fine for short stories, but past about 2,000 characters (around a 4–5 KB story) they’re too long for a Discord message, and the dialog warns you.
- an editor link that opens the story in the web IDE (it becomes one of the recipient’s stories).
- a file link for long stories: put the
.brujafile online (a raw file on Gitea or GitHub, a gist, your own server) and paste its address. The link stays short, and updating the file updates the story. The file’s server must allow cross-origin requests. - Download .bruja.
The reading view works well on phones. Its View source button opens the story in the web IDE.
Command line
bruja plays stories in the terminal and checks them. Install it as a .NET tool with
dotnet tool install -g Bruja.Cli, or run it from the repo with
dotnet run --project src/Bruja.Cli -- <arguments>.
| Command | |
|---|---|
-f story.bruja |
Play a story (.bruja, or compiled .brujac). Enter shows the next line (with its speaker in front: Mira (sad): Hello.); type a number to choose; input() prints its prompt (and default in brackets) and reads a line. At any prompt: /save file, /load file, /quit. |
| (no arguments) | A REPL: type code and see its value. Type . alone on a line to start and end multi-line input. /exit quits. |
check -f story.bruja |
Print every error and warning, in the story and the files it imports, as story.bruja:12:5: error: message. Exit code 1 if there are errors. --stdin reads the source from standard input (the file name is still used in messages); with --stdin-for chapter2.bruja, standard input replaces that imported file instead. |
lines add -f story.bruja |
Give every line, question and choice without an ID a #line: ID (edits the story and the files it imports in place). |
lines export -f story.bruja [-o lines.csv] |
Write the lines with IDs as CSV for translators: id, text (a template: {0}… for expressions and variations), speaker, file, line and a comment (the // comment above the line, and what each {n} is). |
lines import -f story.bruja -i fr.csv |
Check a string table (one language): unknown or repeated IDs, placeholders that don’t match the original, markup that doesn’t match. Exit code 1 on errors. |
outline -f story.bruja |
Print the names the story and its imports define (threads, functions, variables, enums, speakers…) as JSON, for editors. Takes --stdin and --stdin-for like check. |
compile -f story.bruja [-o out.brujac] |
Compile to bytecode, for games that ship without the compiler. |
disasm -f story.bruja |
Print the compiled instructions. |
Every command exits with 0 on success, 1 when the story has errors, and 2 for bad arguments or
missing files. --help lists the options and --version prints the version.
VS Code extension
editors/vscode adds .bruja highlighting, errors and warnings as you type (it runs
bruja check), Go to Definition (F12, Ctrl+click) for threads and names, also across
files, and a Run button that plays the file in a terminal. #line: IDs are dimmed. A file that another .bruja file in
the workspace imports is checked as part of that story, so names from the other files are known.
To install it from the repo:
- Install the CLI (
dotnet tool install -g Bruja.Cli), or build it withdotnet build. - In
editors/vscode, runnpm installandnpm run packageto make a.vsix. - In VS Code, run Extensions: Install from VSIX… and pick the file. To work on the
extension, open
editors/vscodein VS Code and press F5.
The extension uses bruja from your PATH, or a build in src/Bruja.Cli/bin/… of
the open folder. Elsewhere, set Bruja: Cli Path (bruja.cliPath) in the settings.
Tests
dotnet test
This runs the golden scripts in tests/Bruja.Tests/Scripts/ and the API and unit tests. The same
scripts also run on Mono and in the browser. Every test suite, and how to run it, is listed in
CONTRIBUTING.md; how to write a golden script is in
tests/Bruja.Tests/README.md.