Bruja in 15 minutes
A quick read through the parts of Bruja you’ll use every day, built around one small story.
Every example is a complete story you can paste into the web IDE
(or run with bruja -f story.bruja) and play.
This is the short version. To learn everything step by step, with tasks checked as you go, take The Quest, the free interactive course. For the exact rules of any feature, see the language reference.
Contents
- Lines and speakers
- Choices
- Variables and conditions
- Threads
- Text that changes
- Talking to the game
- The whole story
- Mistakes everyone makes
- Where next
1. Lines and speakers
A line that starts with > is dialogue: text the player reads, one line per “click to
continue”. Start it with @Name: to say who’s talking; a word in parentheses before the : is
their mood, for a portrait. Lines that start with // are comments, for you only.
// The ferry, the night of the storm.
> The rain hasn't stopped for three days.
> @Ferryman: Last crossing tonight.
> @Ferryman (tired): After this, nobody goes over until spring.
2. Choices
To ask something, write the question as dialogue and indent the choices under it. Whatever is indented under a choice happens when the player picks it, then the story carries on after the question.
> @Ferryman: Front of the boat, or the back?
* The front
> Spray stings your face.
* The back
> You sit by the warm engine.
> The ferry pulls away from the dock.
Indentation is how Bruja knows what belongs to what, like Python: 4 spaces per level (the web IDE and VS Code do this for you). Blocks can hold anything, even more questions.
There are two kinds of choice. A * choice disappears once picked; a + choice stays. That
matters when the same question comes back, which you’ll see in Threads.
3. Variables and conditions
A variable is a name for a value. Set it with =, change it with += and -=, and show it
in dialogue with {braces}. Anything can go in braces: {coins * 2}, {name + "!"}.
{condition} at the start of a choice shows it only when the condition is true:
coins = 3
> You have {coins} coins. The fare is 2.
* {coins >= 2} Pay
coins -= 2
> Coins left: {coins}.
* Haggle
> @Ferryman: Two, or swim.
if picks a branch without asking the player:
coins = 1
> @Ferryman: Two coins, please.
* Turn out your pockets
coins += 1
> Behind the lint, a second coin!
* Shrug
> You count again. Still one.
if coins >= 2:
> You pay, and the ferry pulls away with you on board.
else:
> You watch the ferry leave without you.
Compare with ==, !=, <, >, <= and >=, and combine with and, or and not. Only
false and null count as false: 0 and "" are true.
4. Threads
A line starting with # begins a thread, a named part of the story. -> name jumps to one.
Names are lowercase with _ for spaces, so # The Dock is -> the_dock.
has_ticket = false
-> the_dock
# The Dock
> [Rain on the planks.|The ferry bell rings.|The ferryman is waiting.]
* Read the timetable
> Last ferry: tonight.
* Buy a ticket
has_ticket = true
> The ferryman punches a hole in your ticket.
+ {has_ticket} Board the ferry
-> crossing
-> the_dock
# Crossing
> The ferry pulls away. You paced the dock [count: visits("the_dock") | not at all | once | {visits("the_dock")} times] before you left.
The question repeats until the player boards: the * choices are used up one by one, and + Board the ferry stays once there’s a ticket. Some things to know:
visits("the_dock")counts how many times the story entered a thread: the easiest way to write “the first time you come here…”.- A story reads top to bottom, straight into the next thread, unless it jumps. End a thread
with
->when it shouldn’t fall through. <- nameplays a thread and comes back, for text you reuse.##makes a thread inside a thread, andimport "file.bruja"splits a long story into files.- A jump to a thread that doesn’t exist is an error before the story runs, so typos never reach players.
5. Text that changes
Square brackets make text that varies. The [Rain on the planks.|…] line above is a
sequence: each option once, in order, then it sticks on the last. A few more:
bag = ["a lamp", "some rope"]
coins = 1
> You carry [and: bag].
> You have [count: coins | no coins | one coin | {coins} coins] left.
> A gull cries [any: once|twice|from somewhere above].
> The lamp is <b>very</b> old.
roll = d20
> You roll {roll}. [if: roll >= 10 | You keep your footing. | You slip on the wet deck.]
[and: …] writes a list as a sentence, [count: …] picks by number, [any: …] is random each
time, <b>…</b> makes text bold, and d20 is a dice roll (also
d6, 2d6…). The language reference lists them all.
6. Talking to the game
A story usually runs inside a game. Three things connect them:
- Tags: words after a
#at the end of a line. The player never sees them; the game reads them, to play a voice clip or shake the screen.@Name:is a shortcut for aspeaker:tag. - Game functions: declare them with
extern, then call them like any function. In the web IDE they only show up in the Output tab. waitpauses the story until the game says to go on, after an animation or a fight.
extern play_sound
> @Ferryman: Hold on to something. #vo:ferryman_07 #shake
play_sound("thunder")
wait "wave_hits"
> The ferry lurches, then steadies.
Using stories in games shows the game’s side, in C# and Unity. To play a story in other languages, see localization.
7. The whole story
Everything above in one short story. Paste it into the web IDE and open the Variables and Threads tabs while you play.
// The Last Ferry
extern play_sound
coins = 1
has_ticket = false
> The rain hasn't stopped for three days.
-> the_dock
# The Dock
> [Rain on the planks.|The ferry bell rings.|The ferryman taps his watch.]
* Read the timetable
> Last ferry: tonight. Fare: 2 coins.
* Help unload the crates
coins += 1
> @Ferryman: Thanks for the hand. Here's a coin for your trouble.
+ {not has_ticket} Buy a ticket
if coins >= 2:
coins -= 2
has_ticket = true
> @Ferryman: Hop on. You have [count: coins | no coins | one coin | {coins} coins] left.
else:
> @Ferryman (stern): Two coins, or swim.
+ {has_ticket} Board the ferry
-> crossing
+ Go home
-> home
-> the_dock
# Crossing
> @Ferryman: Hold on to something. #shake
play_sound("thunder")
wait "wave_hits"
roll = d20
> [if: roll >= 8 | You keep your footing. | You slide across the wet deck.]
> The lighthouse rises out of the rain.
-> the_end
# Home
> You go home. You stood on the dock [count: visits("the_dock") | never | once | {visits("the_dock")} times].
-> the_end
# The End
8. Mistakes everyone makes
- Choices not indented under their question. A
*line must be indented under the>line that asks. - Uneven indentation. 4 spaces per level, and lines in the same block must line up exactly.
- Falling through threads. The story reads on into the next
#thread unless you jump. //or#inside dialogue. In a>line,//is text and#starts the tags. Write\#for a real#.0is true.if coins:is true even whencoinsis0. Writeif coins > 0:.- A second
{…}at the start of a choice. Everything in braces before a choice’s text is a condition.* {hungry} {food} pleasehides{food}; write* {hungry} Some {food}, please. - “is never assigned” warnings. Usually a typo in a name, or a game function called without
extern.
9. Where next
- The Quest: the full course, 36 short lessons that build one whole story, The Lighthouse, with loops, functions, lists, generators, events and more.
- Language reference: every feature, with an example each.
- Using stories in games: the C# API and the Unity package.