What a script is
Lives in: story/script.txt
A VN-Mikro script is meant to read like a play or screenplay: who speaks, what they say, and short stage directions for the scene. The player turns that text into the game.
You write it in any text editor. Empty lines matter. Square brackets and a few marks do the rest.
Scenes, moments, and lines
| Word | In the file | What the player does |
|---|---|---|
| Moment | One block of text between empty lines | Runs that block’s directions, types the text, then waits for a click (or a choice / timer) |
| Scene | A moment with a name: :: park | Something you can jump to later |
| Line | Text under a speaker, or narrator text | What appears in the dialogue box |
An empty line ends the current moment and starts the next. That is the main “cut” in the script.
A short scene, read top to bottom
:: street
[bg street fade 0.5]
[hana left fade 0.4]
HANA:
You came back.
> Of course. -> stay
> Just passing through. -> leave
:: stay
HANA:
Good. Stay a while.
-> END
:: leave
HANA:
Safe travels.
-> END
What happens:
:: streetnames this moment so other moments can jump here.[bg …]and[hana …]are stage directions — they run when the moment starts.HANA:marks who speaks; the next lines are her dialogue.>lines are choices. Each can jump with-> ….-> ENDends the story.
The marks you will use most
| Mark | Example | Job |
|---|---|---|
| Empty line | New moment | |
# | # note | Comment — ignored by the player |
:: | :: park | Name this moment |
:: start | :: start | Optional New Game entry (first moment if omitted) |
NAME: | HANA: | Speaker |
[…] | [bg street] | Stage direction or flag |
> | > Stay. -> stay | Choice |
-> | -> park or -> END | Jump / end |
{…} | {score} / {@w} | Flag in text, or a pause mark |
Everything else builds on these.
Dialogue, narration, directions — together
[bg park fade 0.5]
The park is quiet.
[hana left]
HANA:
Sit with me.
- No speaker → narrator (or the story’s voice).
HANA:→ her name plate and focus.- Bracket lines → change the stage; they are not spoken aloud.
Those names only work if the pictures exist on disk (characters/, backgrounds/, …) — Pictures, sound, and folders.
What you do not put in the script
Looks (fonts, dialogue-box colour), title menus, and dense production usually live in other files (game.json, themes/, screens.json, sometimes story/story.json). The script stays readable on purpose.
One project normally has one story folder and one script.txt. Several scripts in one game (episodes / packs) is early — In development.
When a moment needs more than brackets can say: When the script is not enough.
Next
Open examples/example-01-hello-vn/story/script.txt while you read.