Skip to content

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 inside visits("…")), 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 .bruja file 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:

  1. Install the CLI (dotnet tool install -g Bruja.Cli), or build it with dotnet build.
  2. In editors/vscode, run npm install and npm run package to make a .vsix.
  3. In VS Code, run Extensions: Install from VSIX… and pick the file. To work on the extension, open editors/vscode in 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.

Edit this page