VN-Mikro

Write a visual novel the way you would write a play. VN-Mikro turns your script, pictures and music into a finished game — with menus, saves, rollback and builds for every platform already done.

This handbook matches runtime 0.1.0.

Two ways in

Making a game? Start at What VN-Mikro is and read the sidebar top to bottom. Each part adds one layer to your game:

Looking for something? Open Reference:

• File maps — see a whole file at once, every key clickable.
• Everything A–Z — one flat list of every command, key and action.
• How these docs work — guide vs map vs detail.

Worked projects live in the examples/ folder next to the player.

What VN-Mikro is

VN-Mikro is a player for visual novels. You give it a folder — your script, your pictures, your music — and it plays that folder as a finished game.

my-game/
  game.json          your game's name and settings
  story/script.txt   the story, written like a play
  characters/        character pictures
  backgrounds/       scene pictures
  audio/             music and sound effects

There is no editor to learn and no project file to keep in sync. You write in any text editor, press one key, and the player shows the change.

What you write

Most of your time goes into script.txt. It reads like a script for the stage or screen:

[bg street fade 0.5]
[hana left]
HANA:
You came back.

> Of course I did. -> stay
> I'm just passing through. -> leave

Who speaks, what they say, where the scene goes next. The bracket lines are stage directions: show this place, bring in this character.

When a scene needs more — a precise camera move, a custom menu, a character with blinking eyes — you add a small settings file next to the script. The script stays readable.

What the player does

Everything a player expects from a visual novel is already there: text that types out, a name plate, choices, save and load, stepping back through lines, a history log, title and pause menus, a settings screen, and builds for desktop, web and phones.

You do not build these. You decide how they look and when they appear. The next page lists them: What VN-Mikro handles for you.

Who it is for

VN-Mikro is made for story-first games: kinetic novels, dialogue-heavy stories, branching romances, mysteries. If your plan is “write the scenes, then dress them”, you are in the right place.

It is not a general game engine. If your game is mostly a custom minigame with some dialogue around it, a full engine suits you better.

The spirit is closer to classic Japanese script engines (think KiriKiri / KAG) than to a full game IDE: plain script, data beside it, player runs the folder. Those tools went quiet; the habit of writing VNs as text didn’t.

Built on a proven engine

The player is built with the Godot engine, so it runs smoothly on Windows, macOS, Linux, the web and Android. You never open Godot yourself — you only work with your project folder.

Next

What VN-Mikro handles for you

What VN-Mikro handles for you

Every visual novel needs the same hundred small things before a single player enjoys it. Most of them are invisible when they work and painful when they do not. VN-Mikro ships them ready, so your work is the story.

Below: what the player does on its own, and what you can change when you want to.

Reading the text

Who is speaking

Characters and scenes

Choices and input

Saving and going back

This is where most homemade visual novels break. VN-Mikro keeps it stable.

Menus and screens

More than one language

Checking your work

While you write, the author player helps you catch mistakes before players do:

Shipping the game

What it does not do (yet)

A few things other tools offer are not in VN-Mikro today: skipping already-read text, gamepad controls, and picture thumbnails on save slots.

Multi-scripting (several story packs / scripts in one project) and the Save/Load menu polish (slots work; finished UI still early) — details: In development.

Next

In development · How you work

In development

These are planned or only partly finished. Do not build your whole game around them yet.

Save and load menus

Saving, loading, autosave, and Continue already work. session.save_slots sets how many manual slots you get (1–99). You build Save / Load screens yourself in screens.json.

What is not ready: a polished, finished slot UI (layout, picture thumbnails, the overall Save/Load experience authors expect out of the box). Slot count and early screens are usable tooling; the menu finish may change.

Until that lands, keep Save/Load screens simple. Details while setting the count: Save, Back and story end.

Multi-scripting (several stories in one project)

One project can already list more than one story pack in game.json (stories: each pack has its own folder and script.txt). Saves know which pack you were in. Unlock flags can gate the next episode.

What is not ready: a polished story-select / campaign hub. Today you wire that menu yourself in screens.json. Labels, hub layout, and the overall flow may change.

Until that settles, prefer one story/ folder and one script for a shipped game. Treat multi-pack as early tooling, not a finished feature. Keys and hub wiring: Several stories in one project.

3D models (Blender → the stage)

The direction: use Blender models (GLTF) as characters, props, and eventually backgrounds — not only flat PNGs. Named animation clips play from the story (idle loops, one-shot gestures).

Parts of this already exist in experiments (characters and sprites can mount a model; clips can run and stop). What is not ready for handbook authors: a stable, documented way to export, place, and light models in a normal project folder; full background / room integration; and a finish that matches the 2D path for save, shaders, and interaction.

Until that lands, ship with PNG and layered 2D characters. Treat 3D as upcoming, not as something to depend on for a release.

Character idle (2D layered packs)

The direction: soft breathe / sway / bob on layered character packs so standing characters feel alive without a new expression every beat. Pack settings would choose an idle motion; talking and focus reactions stay separate.

This may already appear as early pack options in some builds. What is not ready: a calm, final set of motions, tuning that looks good at every resolution, and clear docs for when idle fights with expression swaps or talking mouths.

Prefer still poses and your own blink / mouth layers today. Idle motion is polish on top — not required to finish a story.

Stage locations (richer rooms)

The direction: backgrounds that behave more like places than single pictures — when the room resets between beats, layered background packs, clickable hotspots in the room, and a simple room camera (pan / focus) driven from the story.

Schema and tests for a stage-style flow are under work. What is not ready: author handbook pages, a finished Mode A spelling for everyday use, and a player-facing room editor. Clickable props today are still normal sprites / objects / screen hooks.

Keep using [bg …] and stage sprites for shipped games. Stage locations will extend that world later, not replace your current backgrounds overnight.

Video on the stage

The direction: play video as stage pictures — sprites / layers you place like any other prop — with simple controls from the story (play, pause, seek, loop, stop).

Nothing here is handbook-ready yet. Ship with still images and flipbooks (frames) for motion. Treat video layers as upcoming polish, not a release dependency.

Blend modes (sprites and layers)

The direction: choose how a sprite or character layer blends with what is behind it. A small set of common modes ships first (the usual multiply / add / screen family). Extra Photoshop-style looks would come from small built-in shaders you pick by name, not from a free-form editor.

What is not ready: author keys, a finished way to write it in the script, and docs for when blend mode fights with existing shaders or save/restore. Today, tint and opacity are the safe tools — Sprites and objects · Shaders.

Not scheduled here (but missing today)

Skipping already-read text, gamepad controls, and picture thumbnails on save slots — listed under What VN-Mikro handles for you. Thumbnails sit with the unfinished Save/Load UI above.

Panel height ceiling and body scroll for dialogue text are available now (theme max_height / sticky panel max_height). Choice-list scrolling inside a capped plate is still not a separate feature — a choice list taller than the ceiling can still clip.

Next

How you work

How you work

Making a game with VN-Mikro is a short loop you repeat all day:

write  →  play  →  reload  →  check  →  …  →  build

The two players

You write and test in the author player. When the story is ready, you build your released game from it.

Write

Open your project folder in any text editor. Almost everything is in:

• story/script.txt — the story itself
• game.json — your game’s name and settings
• picture and sound folders

Save the file. That is all “writing” means here — there is nothing to export.

Play and reload

Edit a line, press F5, see it. You do not restart the game to test a change.

Check

F12 opens the author tools beside the game. Full tab list (Meta, Nodes jump modes, Vars, Validation, Prefs, Build): Author tools.

Run Validation before you share a build.

Build

When you are ready, the Build tab packs your game for Windows, macOS, Linux, the web or Android. You get one folder per platform to give to players. Details: Build and hand off · Author tools.

How to read these docs

• Parts 1–7 in the sidebar follow the order you build a game in. Read them top to bottom the first time.
• Reference at the bottom is for looking things up once you know what you want.

You do not need to read everything. Most games use only a small part of what is here.

Next

What is JSON — then Reusing settings — then Your first ten minutes

Author tools (F12)

While you are writing, the author player includes a debug overlay. Use it to inspect the running story, jump around, edit flags, validate the project, and open Build.

Player builds you ship do not include this overlay (and they strip the F1–F12 author shortcuts).

Open and close

Press F12 (default; remappable in keybindings.json as the debug toggle action).

Prefs and Build choices are remembered in vn-mikro-debug.cfg next to the player.

Quick keys outside the overlay: How you work (F5 / F6 / F2).

Tabs

Meta

Current node summary, optional raw JSON, and quick controls. The compact status line starts with vn-mikro and the runtime version (separate from your project’s game.json → version).

Nodes

List of story nodes. Sort by story order or id. Jump with:

You can seed flags before a jump. Jump history backs and forwards through recent targets.

Vars

Live flags: sort by name, type, or recent change. Set, add, remove, or reset values while playing.

Validation

Run project checks and browse warnings/errors with detail text. Useful before a build. Refresh includes broken links, flag-aware reachability (branches that can never run), and missing character / background / screen / sprite refs for the active story pack. Activate a row with a node id to jump there.

When a check fails, the Validation tab label turns red and shows the error count, so you can spot a broken project without opening the tab. F5 re-reads your project files and reruns the checks — fix a missing comma or bracket, press F5, and the error and the red label clear. The Refresh button reruns the same checks without reloading gameplay.

Prefs

While the overlay is open, the software cursor is suppressed so the OS pointer stays usable on the tools.

Build

Visible only in the author player. Packaging steps, modes, and what to ship: Build and hand off.

Author vs player

You write and test in the author player. When the story is ready, build from the Build tab and distribute that output.

How these docs work

Three layers, one sidebar. You do not need every layer on day one.

Guide (Welcome through Ship)

Short pages in story order: write → set up → direct → stage → look → polish → ship. Read top to bottom the first time. Later, jump in from search or the sidebar.

Reference

When you already know what you want:

Guide pages teach when; maps and detail teach every key.

Examples vs docs

If an example does not use a key, the key still exists. Check the map or detail page for that surface.

Author tools

Overlay, jumps, flags, Validation, Build: Author tools · Build and hand off.

Checking a project

The author kit can validate your folder (broken jumps, missing assets, schema). Prefer that over guessing from memory — Reference.

What is JSON

JSON is a way to write structured notes in a plain text file. The player reads those notes. You do not “run” JSON like a program — you fill in names and values that the docs list.

If you already know forms and spreadsheets, you are closer than you think: names are column headers, values are cells, and groups of fields are like a row under a heading.

A tiny example

{
  "title": "Cold Down",
  "window": {
    "width": 1280,
    "height": 720
  }
}

In words:

• Curly braces { } wrap a group of named fields.
• "title" is a name (always in double quotes).
• "Cold Down" is the value for that name.
• "window" is another group nested inside the first one.

Commas separate fields. The last field in a group has no comma after it.

The shapes you will see

Colours are usually text like "#343a52e0". Paths are text relative to your project folder.

Why VN-Mikro uses it

The script is great for lines and flow. JSON is better when many small settings must stay together and stay checkable:

• Your game’s name and defaults (game.json)
• How the dialogue box and menus look (themes/)
• Title, pause and settings screens (screens.json)
• Precise direction on one moment (story/story.json)
• Layered characters, choice looks, cursors

You do not write JSON for every line of dialogue. Most of the story stays in script.txt. Settings files hold everything that is not a spoken line.

The file maps show every allowed name in a file. Stick to those names so projects stay stable and easy to edit later — including with help from an assistant.

Common mistakes (and how they feel)

A good editor underlines broken JSON. The author tools (F12 → Validation) and project check also name the file and line for broken settings JSON (game.json, themes, screens, characters, story overlays).

You do not need to memorise it

Copy an example from these docs or from examples/, change the values, reload (F5). Open a settings page only when you need a key.

When one look or expression should start from another and change only a few things, see Reusing settings.

Next

Reusing settings · then Pictures, sound, and folders · then Your first ten minutes

Reusing settings

You often want this: start from something that already works, change only what differs. VN-Mikro does that in several places. The idea is the same; the words and rules are not. This page keeps them apart.

When a later chapter says extends or source, it will point at one row of the table below — not at “inheritance” in general.

The kinds (start here)

Objects under sprites/*.obj.json do not reuse another object this way. They are a flat list of parts; you change an instance with update and live links to flags. See Sprites and objects.

One example per kind

Character expression (layers)

"default": [
  { "path": "base.png" },
  { "path": "mouth.png" }
],
"happy": {
  "extends": "default",
  "override": [{ "layer": 1, "path": "mouth_happy.png" }]
}

happy starts as default, then replaces layer 1. "add" would append extra layers. This is not the same tool as panel "extends".

Dialogue-box look (keys)

"panel": {
  "default": { "width": "100%", "bg": "#1e2133e0" },
  "whisper": {
    "extends": "default",
    "width": "60%",
    "bg": "#00000099"
  }
}

whisper keeps everything from default except the keys you set. Full story: Theme and the dialogue box.

Pack look (source / style)

{ "style": "choice_plain" }
{ "source": "choice_plain", "gap": 12 }

"style": "name" means the same as "source": "name". The pack loads from themes/<name>.json, then your local keys merge on top. Used for buttons, choices and name-entry — not for character packs, cursors, or name-plate style keys.

Splash per platform

"splash": {
  "logo": "splash/logo.png",
  "web": { "logo_max_width": 280 },
  "desktop": { "min_seconds": 0.6 }
}

Shared keys at the root; web / android / desktop only change what that platform needs. Details: Title, icon, splash.

Shared merge rule (deep merge)

These places merge key by key (panel extends, pack source, splash platforms, scene mood files):

Character expression "extends" is different: it works on layers (override / add), not this key table alone.

Do not mix these

When you need this page

• First time you copy a look and change one field → read the matching row above.
• Later chapters link here instead of re-explaining merge rules.

Glossary: Words used in these docs.

Next

Pictures, sound, and folders · then Your first ten minutes

Pictures, sound, and folders

Lives in: your project folder

The script names people and places. Those names only work if the files exist. The simplest game still needs pictures (and usually a little sound) on disk — not only script.txt.

This page is the map. Deeper character packs come under Characters; props under The stage.

A tiny project that can run

my-game/
  game.json                 required — name and defaults
  story/
    script.txt              your play
  characters/
    hana/
      hana.png              default look
      hana_happy.png        optional expression
  backgrounds/
    street.jpg              a place
  audio/                    optional at first
    bgm/
    sfx/
  themes/
    default.json            dialogue-box look (copy from an example)
  screens.json              title / pause (copy from an example)

Copy examples/example-00-boilerplate or example-01-hello-vn and replace pictures — you do not need to invent game.json from scratch on day one.

Characters = folders of pictures

Rules that matter:

• One folder per character id — folder name is the id (hana), case-insensitive in the script.
• File name = id or id_expression, plus an image extension.
• You do not need a JSON pack for a first game. One PNG per expression is enough.
• Layered packs (blinking, talking mouths) are optional later — Characters, Reusing settings.

People often call these “sprites.” In VN-Mikro, character pictures live under characters/. The separate sprites/ folder is for props and gadgets on top of the scene — optional; skip it until you need a lamp, phone overlay, or HUD widget.

Places (background pictures)

Write the name without the extension. Formats: .png, .jpg / .jpeg, .webp, .svg.

Sound (when you want it)

Formats: .ogg or .mp3. Name without extension in commands.

Title music can also be set once in game.json — Music and sounds by default.

Formats at a glance

What can wait

Next

Your first ten minutes if you have not run an example yet · otherwise What a script is

Your first ten minutes

You will open a small example, change it, and see your change play.

1. Open the example

1. Start the author player.
2. When it asks for a project, pick examples/example-01-hello-vn.
3. Click through a few lines. Space, a mouse click, or the Continue button moves on.

2. Open the script

Open examples/example-01-hello-vn/story/script.txt in any text editor. You will recognise what you just saw:

[bg street fade 0.5]
Hello! This is the smallest story you can run.

[hana left fade 0.45]
HANA:
Hi - I'm Hana.

• A line in square brackets is a stage direction: show the street, bring Hana in on the left.
• HANA: means Hana speaks the lines below it.
• A line with no speaker is the narrator.
• An empty line starts the next moment of the story.

3. Change something

Change Hana’s line:

HANA:
Hi! I rewrote this line myself.

Save the file, go back to the player, press F5. Hana now says your line.

Other keys you will use (F2, F6, F12): How you work.

4. Add a moment

Add these lines at the end of the file, after an empty line:

[bg parknchairs fade 0.5]
[hana left fade 0.4]
HANA [closed]:
The park is quieter than I thought.

Press F5 and click through to the end. You changed the place, brought Hana back, and gave her a different expression (closed uses the picture hana_closed.png).

Those pictures live under characters/ and backgrounds/ — Pictures, sound, and folders.

5. Break something on purpose

Change parknchairs to parkchairs (a typo), save, press F5, then press F12 and open Validation. The missing background is listed. Fix the typo and reload.

That is the whole loop: write, reload, check.

Where next

If settings files are new to you: What is JSON and Reusing settings. What those [bg] / [hana] lines load from disk: Pictures, sound, and folders.

Continue with What a script is. The rest of the examples in examples/ add one idea each:

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

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:

1. :: street names this moment so other moments can jump here.
2. [bg …] and [hana …] are stage directions — they run when the moment starts.
3. HANA: marks who speaks; the next lines are her dialogue.
4. > lines are choices. Each can jump with -> ….
5. -> END ends the story.

The marks you will use most

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

Lines and speakers

Open examples/example-01-hello-vn/story/script.txt while you read.

Lines and speakers

Lives in: story/script.txt

Who talks, how their name appears, and how each line waits for a click.

Speaker marks at a glance

These can combine, for example ???|HANA [happy] (silent): or ???|HANA [happy] & SORA (silent):.

Speakers

HANA:
Hello.

HANA: (any case) maps to the folder characters/hana/. The name plate usually shows that character’s display name. What to put in that folder: Pictures, sound, and folders.

Several lines under the same speaker stay in the same moment until an empty line:

HANA:
First click.
Still Hana — same moment, another click.

Expression while speaking

HANA [happy]:
Good morning.

That looks for characters/hana/hana_happy.png (or the pack’s happy look). Folders and naming: Pictures, sound, and folders. Details later: Characters.

Narrator

A line with no NAME: is narrator voice — no name plate from a character:

The street is empty.

Unknown name / custom plate

Show a different name on the plate while still using a character folder:

???|HANA:
Who's there?

Left of | is the plate text; right is who is talking (for focus and assets).

Two speakers at once

HANA & SORA:
Together:

Both are in focus for that line. One name plate covers the group (auto names, or a custom Label|… for the whole line). The line uses the routed panel for this moment — usually the first speaker’s preferred panel, unless you set panel_id in data — How text finds a panel.

Each name can take its own [expression] and/or (silent):

HANA [happy] & SORA (silent) & DADDY [sad] (silent):
They speak as a group.

To silence everyone, mark each name: HANA (silent) & SORA (silent):.

Silent line (no talking mouth)

HANA (silent):
(She doesn't answer.)

Same speaker and plate; typing mouth (and beep) stay off. Only the literal (silent) mark — not free-form (anything). Mouths in depth: Talking and focus.

Style inside a line

BBCode works in dialogue:

HANA:
That was [b]not[/b] the plan.
[color=#ff8888]Careful.[/color]

Unknown [word] tags that are not commands stay visible as text. To show real brackets: [lb] / [rb].

Print a flag in the text

HANA:
Your score is {score}.

Curly braces insert the current flag value. To print a literal {, write {{.

Usually you need

Next

Stage directions

Stage directions

Lives in: story/script.txt

Bracket lines change the scene. They are not spoken. They run when the moment starts — unless they appear after dialogue has already begun, in which case they fire mid-line as {@cN} cues; see Pacing.

[bg street fade 0.5]
[hana left fade 0.4]
[bgm city_loop]
[sfx door]

Places

[bg street]
[bg street fade 0.5]
[bg park slide_left 0.6]

Loads a picture from backgrounds/ (extension resolved for you). Optional fade / slide and duration. Naming: Pictures, sound, and folders.

More: Backgrounds.

Characters

[hana left]
[hana happy left fade 0.4]
[hana hide]
[sora right fade 0.3]

• First word is the character folder name (characters/hana/).
• left / center / right are places on stage (defaults; you can rename them later).
• An expression word (happy) and a fade are optional.
• hide removes them from their place.

Speaking with HANA [happy]: also stages that expression. Bracket lines are for show / move / hide without a line of dialogue.

Pictures on disk: Pictures, sound, and folders. Packs and places: Characters.

Music and sound

[bgm theme]
[bgm theme fadein 1.5]
[sfx door]

Files live under audio/bgm/ and audio/sfx/. Title music defaults belong in game.json — Music and sounds by default. Mid-story cues: Music and sound.

Flags (also brackets)

[score = 0]
[helped = true]
[score += 1]

Same bracket shape, different job: memory, not staging. Full use: Choices and memory.

Why several directions feel “instant”

All enter directions in one moment run as a batch when that moment starts. That is why two [hana …] and [sora …] lines can appear together. To time something with the spoken line, put the bracket after text has started — Pacing ({@cN}).

Comments

# This is only for you — the player ignores it

Usually you need

Keyword directions also include things like panel, screen, animate — look them up in Reference when you need them. Character folder names without a keyword are treated as show/move/hide for that character.

Next

Scenes and jumps

Scenes and jumps

Lives in: story/script.txt

Name moments and move between them so the story can branch and meet again.

Name a scene

:: park
HANA:
We're here.

:: park sets this moment’s id to park. Use letters, numbers, and underscores. Every jump target must match an id (or the special end).

If you omit ::, the player still builds a moment — it just has no stable name to jump to. Named scenes are how you build routes.

Where New Game starts

New Game looks for a moment named start (JSON: "id": "start"). In the script that is:

:: start
[bg street fade 0.5]
HANA:
Good morning.

You can omit :: start. The player then uses the first moment in the file. Small examples do that on purpose. Name it when you care about a stable entry (saves, jumps to START, or a pack that sets a different entry).

For several stories in one project, each pack can set its own entry id with stories[].start — Several stories.

Jump

-> park

alone on a line (or after text in some setups) sets where to go when this moment finishes. Common pattern:

HANA:
Let's go.
-> park

End the story

-> END

Ends play (then credits / title follow your session settings — Save, Back and story end).

Branch and merge

:: choice
> Left path. -> left
> Right path. -> right

:: left
HANA:
Left.
-> after

:: right
HANA:
Right.
-> after

:: after
HANA:
Both roads meet here.

Both branches jump to the same after moment. That is how routes rejoin.

Visit a beat and come back

For a reusable insert (a menu of facts, a short cutaway), use call and return:

[call encyclopedia]

…and at the end of that scene:

[return]

call remembers where you were; return goes back. Prefer plain -> for normal story flow; reserve call/return for side visits.

Conditional jump

[if helped -> thank_you]

If the expression is true, go there instead of the normal next moment. Expressions use flag names and && / || / ! — Choices and memory.

Order tips

• Give every important moment a :: id early — renaming later can break old saves.
• Keep merge points (:: after) obvious in the file.
• One -> per moment for the default exit; choices carry their own targets.

Usually you need

Next

Choices and memory

Try examples/example-02-choices-and-flags/story/script.txt.

Choices and memory

Lives in: story/script.txt

Let the reader decide, and remember what they decided.

Open examples/example-02-choices-and-flags/story/script.txt while you read.

Flags

A flag is something the story remembers for the rest of the playthrough (and in saves).

[score = 0]
[helped = false]
[player_name = 'Hero']

Change later:

[score += 1]
[helped = true]

Print in dialogue:

HANA:
Score is {score}. Helped is {helped}.

Strings use single quotes inside the bracket: [some_text = 'hello'].

Choice menus

:: park
HANA:
What do you do?
> Help her. -> help_branch
> Stay back. -> skip_branch

:: help_branch
[helped = true]
HANA:
Thanks.
-> after

:: skip_branch
HANA:
Alright.
-> after

:: after
HANA:
helped is {helped}.

• Each > line is one option.
• -> label is where that option goes.
• A bare > with no arrow continues to the next moment in file order (NEXT).

Look and shuffle defaults live in game.json — Choice and character layout. Rich choice rules (show only if…, disable if…) need the direction file — Adding direction.

Branch on a flag

[if helped -> thank_you]

or, with more cases in data form, jump_if — same expression language. Use &&, ||, ! (not the words and / or).

[if score > 3 && helped -> good_ending]

Ask for a name

[input player_name "Your name?" default "Hero"]

The field starts empty with ghost text Hero. Enter with nothing typed stores Hero; or the reader types a name. On confirm the flag player_name is set. To start with real text the reader can edit, use prefill instead of default:

[input player_name "Your name?" prefill "Hero"]

Then:

HANA:
Nice to meet you, {player_name}.

More options (max_length, pattern, …): Reference when you need them. Look of the field: Choice and input looks.

Usually you need

Try this

1. Add a third choice that does [score += 2].
2. Print {score} after the branches meet.
3. Play twice and pick different options.
4. After the branches meet, ask for a name with [input] and use {player_name} in an ending.

Next

Pacing

Pacing

Lives in: story/script.txt

Control the rhythm of reading: pauses, speed, auto-advance, and fades when leaving a moment.

Soft pause in the line

HANA:
Wait…{@w} there.

{@w} waits for a click (skipped when the reader holds fast-forward). Timed pause:

HANA:
One second…{@w=1.0} go.

Clear the page, then continue

HANA:
First page.{@p}Second page.

{@p} pauses and clears the dialogue box on resume. It is not skipped by fast-forward.

Change speed mid-line

HANA:
Slow.{@cps=8} Faster now.{@cps}

{@cps=N} sets letters per second; {@cps} resets to your project default (Text speed).

Auto-advance a moment

After the text finishes, move on without a click:

HANA:
No click needed.
[auto 2]

[auto 2] means “auto-advance after 2 seconds.” Ignored when the moment is a choice menu.

Exit directions (leave cleanly)

Run directions when leaving this moment — useful for fades out before the next place enters:

:: goodbye
HANA:
See you.
[exit: hana hide fade 0.4]
[exit_delay 0.5]
-> street

• [exit: …] — a stage direction that runs on leave (same language as enter brackets).
• [exit_delay 0.5] — wait after those exit directions before the next moment.

Enter directions still run at the start of the next moment as usual.

Directions in the middle of a line

A bracket after spoken text has already started fires when typing reaches that word — not when the moment begins:

HANA:
I was fine.
[sfx click]
Then I wasn't.

The script compiler inserts an invisible {@c1} (then {@c2}, …) at that spot and stores the direction in flow_commands. Typing does not pause; the command runs as the cursor passes the mark.

Prefer {@w} / {@cps} for timing-only. Use a mid-line bracket when something must fire at a word. In Mode B / JSON you can write {@c1} in text yourself and fill flow_commands — Command flow. Dense cases: Directing.

Usually you need

Try this

1. Put {@w} in the middle of a line; click to resume.
2. Put [sfx …] after a spoken line has started; hear it fire mid-type.
3. Add [auto 1.5] on a short narrator moment.
4. Hide a character with [exit: …] into the next scene.

Next

Writing techniques

Writing techniques

Lives in: story/script.txt

Common visual-novel patterns, written in the script. Steal these shapes; change the words.

Inner voice vs spoken line

Use a plain line (no NAME:) for narrator voice and thoughts; a normal speaker line for speech:

The letter feels heavier than it should.

HANA:
I'm fine.

Or keep the same character, silent, so the mouth does not move (how (silent) works):

HANA (silent):
(Don't say it.)

HANA:
Everything's fine.

Flashback with a different look

A simple script-only flashback: change place, maybe hide the present cast, mark the voice, then jump back.

:: present
[bg street]
HANA:
I keep thinking about that day.
-> flashback

:: flashback
[bg park fade 0.8]
# Optional: switch dialogue-box look for this stretch — see Look / theme_style
Three years earlier.

HANA [closed]:
We should have left sooner.
-> present_return

:: present_return
[bg street fade 0.8]
HANA:
…Anyway.

For a lasting mood change (dimmer panel, different colours), use a second panel preset, a sticky panel command, or a theme_style mood file — Theme and the dialogue box · How a panel looks.

Phone or chat messages

Treat the phone as narrator lines or a dedicated “speaker” folder with its own pictures:

[phone center]
PHONE:
hey, you free?

HANA:
In a minute.

Or plain narrator with style:

[color=#88aaff]hey, you free?[/color]

Free-floating bubbles and custom layouts need direction data — Sprites and objects, Adding direction.

Split into routes, then join

:: fork
> Trust her. -> route_a
> Walk away. -> route_b

:: route_a
[trusted = true]
HANA:
Thank you.
-> join

:: route_b
[trusted = false]
HANA:
…Alright.
-> join

:: join
HANA:
Either way, we keep moving.
[if trusted -> trusted_extra]
-> after_join

:: trusted_extra
HANA:
I'm glad you stayed.
-> after_join

:: after_join
…

One merge moment (join) keeps the file readable. Optional extras use [if …].

A scene the reader can revisit

Share one labeled moment from several places with call / return:

:: hub
> Ask about the park. -> ask_park
> Leave. -> leave_hub

:: ask_park
[call park_info]
-> hub

:: park_info
HANA:
It's quieter after dark.
[return]

Normal story flow still uses ->. Call/return is for side visits that should resume where you left off.

Name entry at the start

:: start
[bg street fade 0.5]
What should we call you?
[input player_name "Your name?" default "Hero"]
-> intro

:: intro
HANA:
Nice to meet you, {player_name}.

Put name entry before the first long scene so {player_name} works everywhere after.

Where to go next

You can draft a whole game with only this part. When you need project defaults (text speed, saves, Back): Setting up your game. When brackets are not enough for one moment: Directing a scene.

The game.json file

Lives in: game.json

Every project has one settings file in the project root. The player reads it when the game starts. Anything you leave out uses a sensible default.

A minimal file

{
  "title": "My Novel",
  "window": { "width": 1280, "height": 720 }
}

That is enough to open a named window at a base size. Story text, choices and pictures still come from story/ and your asset folders.

A fuller starter (still small):

{
  "title": "My Novel",
  "version": "0.1",
  "window": { "width": 1280, "height": 720 },
  "typing": { "cps": 28 },
  "session": { "allow_back": true }
}

See examples/example-00-boilerplate/game.json and examples/example-01-hello-vn/game.json.

What most games touch

Later parts of the handbook cover the rest (transitions, cursor, splash, screens look, and so on). Those keys still live in this same file. Advanced: custom extension packs under extensions.

Full map

Every allowed key in one view: game.json file map. Click a key to open the page that teaches it.

Usually you need

Next

Name, window, language

Name, window, language

Lives in: game.json

What the window is called, how large the picture is drawn, and which language the game starts in.

Title and version

{
  "title": "My Novel",
  "version": "1.0.0",
  "authors": ["Your Studio"]
}

To take the title from a translations file instead, use title_key — Translations.

Window size

"window": {
  "width": 1280,
  "height": 720
}

This is the base size your art and layouts are written for. The player scales the picture to whatever window or screen the reader uses.

Starting language

"locale": "en"

That is the language the game opens in. Offering several languages in Settings is i18n — again Translations.

App icon

"icon": "icon.png"

A picture in the project folder, converted for each platform when you build. Details: Title, icon, splash.

Usually you need

Full key list: game.json map.

Next

Text speed and voice beeps

Text speed and voice beeps

Lives in: game.json → typing

How dialogue letters appear, and the optional voice beep while they type. Mid-line pauses and speed tags stay in the script — Pacing. A panel preset can override most of these keys for one surface — Panel.

Letters per second

"typing": {
  "cps": 28,
  "cps_fast": 100
}

If you omit cps, the player can use delay / delay_fast (seconds per letter) instead. speed_scale and auto_advance_default are Settings-owned — they cannot be set on a panel preset.

How letters look

"typing": {
  "cps": 28,
  "reveal": "typewriter"
}

Optional extras (pending_alpha, reveal_soft, caret mark, …) are on the game.json map.

Voice beep

"typing": {
  "beep": {
    "sample": "typing_beep",
    "volume": 0.5,
    "pitch_min": 0.9,
    "pitch_max": 1.1
  }
}

Ids point at files in your audio folders — Pictures, sound, and folders. Readers can turn the beep off in Settings (sounds.defaults.typing_enabled seeds the first launch). Script [typing_sfx …] overrides the sample until reset — typing_sfx.

Line start / end sounds

Optional one-shots when a whole line begins or finishes typing. Useful for phone chat (“incoming message”) without writing [sfx] on every node. Not fired on {@w} pauses, and not on Back / load restore. Uses the SFX bus (master × SFX × volume) — the Typing Sound toggle does not mute these.

"typing": {
  "start_sfx": { "sample": "msg_in", "volume": 0.6 },
  "end_sfx": { "sample": "msg_done", "volume": 0.3 }
}

Same objects work on a panel preset — Typing per preset.

Mouth motion while typing is a character pack feature, not a typing key — Talking and focus. Script (silent) turns it off for a speaker — Lines and speakers.

Usually you need

Next

Music and sounds by default

Music and sounds by default

Lives in: game.json → sounds

Title music and UI clicks. The typing beep lives under typing.beep — Text speed and voice beeps. Scene music and one-shot effects in the script are separate — Music and sound.

Title music

"sounds": {
  "main_bgm": "title_theme",
  "main_bgm_volume": 0.8,
  "main_bgm_fade_in": 1.5,
  "main_bgm_fade_out": 1.5
}

main_bgm is a music id from your audio folders. Fade keys are in seconds; volume is 0–1.

UI clicks

"sounds": {
  "button_click": "click",
  "button_hover": "hover",
  "button_volume": 0.5
}

Used for menus, Continue / Back on the dialogue panel, and normal choice buttons (unless a look pack overrides them).

Typing beep

Set typing.beep — Text speed and voice beeps.

First-launch volumes

"sounds": {
  "defaults": {
    "master": 1.0,
    "bgm": 1.0,
    "sfx": 1.0,
    "typing_enabled": true
  }
}

Seeds Settings the first time someone plays. After they save prefs, those win.

Usually you need

Ids and folders: Pictures, sound, and folders. Full key list: game.json map.

Next

Save, Back and story end

Save, Back and story end

Lives in: game.json → session · save files next to the player · screen actions

A session is one playthrough from New Game / Continue / Load until you return to title (or quit). Progress lives next to the player as manual slots, one autosave, and a separate prefs file.

Early — not final UX. Multi-slot save/load grids and multi-story packs are shipped and usable, but menus, labels, hub screens, and overall player comfort are still a first cut. Prefer the simple one-slot "save" / "load" wiring unless you need the grid or packs — In development.

Most stories

• Keep pause/title hooks as "save" / "load" for a simple one-slot feel (always slot 1).
• Or point menus at screen:save / screen:load for a multi-slot picker — define your own save / load screens with the save_slots block; none ship built-in.
• Title Continue resumes the autosave.
• Set session.allow_back if you want Back / rollback.
• Set session.post_story_screen (and usually post_story_return_to_title) for credits after the last line.
• Changing node ids or restructuring the story can invalidate old saves — that is intentional.

Where this lives

{
  "session": {
    "allow_back": true,
    "back_retype": false,
    "back_limit": 0,
    "save_slots": 9,
    "boot": "title",
    "hud_screen": "hud",
    "post_story_screen": "credits",
    "post_story_return_to_title": true
  }
}

"hud_screen": "hud" (default) auto-shows that screens.json entry with role: "hud" when a session starts. Set "hud_screen": "" to disable. Extra HUD mid-story: screen command.

{ "label": "Save", "interaction": { "hooks": { "on_click": "save" } } }

{ "label": "Save game", "interaction": { "hooks": { "on_click": "screen:save" } } }

Players never write save files by hand. Authors configure session and the screen actions that read those files.

session keys

If post_story_screen is empty and post_story_return_to_title is false, the runtime still returns to title.

Map: game.json → session.

Files on disk

Immediate actions: "save" / "load" always use slot 1.
Keyboard: S quick-saves the last-used slot (fallback 1); L in play loads that slot. Title L still prefers Continue when an autosave exists.
New Game starts a fresh session; it does not delete these files.

Title buttons typically use show_if: "has_save" / "has_autosave". Those checks also require a compatible file, so broken or outdated saves hide Continue/Load. has_save is true if any slot is occupied and compatible.

Author vs player encode

Obfuscation is comfort (raise the bar vs peeking), not DRM. Prefs stay plain so volumes/locale remain easy to inspect.

Where files live

Saves are player progress, not part of your project folder.

What a save holds

Story cursor: current node id, flags, shuffle seed, plus save_version, story_id (pack), and story_hash for compatibility.

Stage and chrome (restored in a fixed order): background, character layout profile, on-stage characters, BGM, sprites, objects, screen shader, running animations, panels, theme_style / choice_style overrides, cursor profile.

Also: rollback history (only if allow_back), dialogue backlog. Preferences live only in prefs.json (volumes, display, UI, last_used_slot, last_story_id, campaign unlock flags).

Node-local overrides are not kept; drivers re-sync after load or Back.

Multiple stories (early)

One shared slot list + one autosave for the whole game. Each save stamps story_id. Hub screen: new_game:<id> and optional show_if: story_unlocked:<id>. Slot labels can use {story} / {story_title}. Full contract: Several stories in one project.

Back / rollback

Requires allow_back, enough history, and room under back_limit.

• History snapshots are taken after a node’s command batch finishes.
• Back restores the previous snapshot and skips “transit” nodes (no text and no choices) so the player lands on something interactive.
• Successful Back also writes a live autosave.
• Backlog trims to the restored node.

Default Back key is remappable (dialogue_back in keybindings.json) — Keys.

Story end

When there is no valid next (or a choice targets null):

1. Fade out.
2. Clear autosave — Continue is gone for that finished run.
3. End session (reset stage/flags; title if configured).
4. Fade in.
5. Optionally push post_story_screen.

Manual slots and prefs are not cleared on story end.

Usually you need

Related

Title, pause and settings screens · Gameplay HUD · save_slots content block · Sticky state and clear · Several stories

Choice and character layout

Lives in: game.json → layout

Project defaults for choice menus, name entry, and where characters stand. A story moment can override these for one scene; this file sets the usual look.

Choice menus

"layout": {
  "choices": {
    "show_numbers": true,
    "shuffle": false,
    "gap": 10,
    "style": "choice_button"
  }
}

container and item hold where the menu sits and per-button defaults — shapes shared with other UI: Shared shapes. Visual packs: Choice and input looks. Writing the options themselves stays in the script — Choices and memory.

Name entry

"layout": {
  "text_input": {
    "style": "input_default",
    "confirm": { "label": "OK" }
  }
}

Defaults for [input …] moments. Field placement and chrome use the same container shapes as choices.

Character places

"layout": {
  "characters": {
    "mode": "adaptive",
    "adaptive": {
      "slot_count": 3,
      "slot_width": 400,
      "slot_height": 720
    }
  }
}

Script stage directions like [hana left] use those place names. Full explanation: Planes and slots · Places on stage.

Usually you need

Full key list: game.json map.

Next

When a line of script is not enough: When the script is not enough. Or jump to The stage for pictures and music in scenes.

Several stories in one project

Lives in: game.json → stories

Early — not final UX. Multi-story packs are implemented (catalog, save story_id, unlock / clear_flag, new_game:<id>). There is no polished shipped story-select / campaign UI — you wire a hub in screens.json yourself. Labels, hub layout, and comfort flows may change.

Optional catalog of story packs in one project (episodes or separate stories). Omit the key for a single pack at story/ (id main).

"stories": [
  {
    "id": "main",
    "title": "Episode 1",
    "path": "story",
    "start": "start",
    "mode": "episode",
    "unlock": { "always": true },
    "clear_flag": "ep1_cleared"
  },
  {
    "id": "ep2",
    "path": "stories/ep2",
    "mode": "episode",
    "unlock": { "flag": "ep1_cleared" }
  }
],
"session": {
  "default_story": "main"
}

Usually you need

All pack keys

Session

Actions / show_if

Saves

All packs share one slot list and one autosave (same early multi-slot surface). Each save stores story_id. Load grid tokens: {story}, {story_title} (plus {n}, {node}).

In development · Save, Back and story end · Screens · game.json map

When the script is not enough

Lives in: story/script.txt and (when needed) story/story.json

Most of a game stays in the script: speakers, lines, jumps, choices, and short stage directions. Add a direction file only when a moment needs more than brackets can say cleanly.

What the script is good at

That is enough for a whole first draft — Writing your story.

When brackets get awkward

Reach for story/story.json when you need things like:

• An object or widget tied to a flag (a meter, a lamp)
• Choice menus with custom layout or look packs in detail
• Dense animation, shaders, or panel chrome on one beat
• A command that should run only if a condition is true (when)
• Something that sticks for the session, or lasts only this moment (apply)

If you can say it in one clear bracket line, keep it in the script.

Three ways to work

With script + direction, each direction entry matches a scene by id (the same name as :: park). Dialogue and jumps stay in the script; the data file adds or overrides what that moment needs.

Start in the script

1. Write and play the scene as script.
2. Give important moments a stable :: id.
3. Only then add a story.json patch for the moments that need it.

Next: see one moment in both shapes — The same beat as data.

The same beat as data

Lives in: story/script.txt and story/story.json

A moment is the same thing whether you write it as script or as a data entry. The player runs one shape either way.

Side by side

Script:

:: park
[bg street fade 0.5]
[hana left]
HANA [happy]:
Watch the meter.
-> after

Same moment as data (fields the player cares about):

{
  "id": "park",
  "talking": "hana",
  "text": "Watch the meter.",
  "commands": [
    { "type": "bg", "value": "street", "transition": "fade", "duration": 0.5 },
    { "type": "char", "name": "hana", "position": "left" },
    { "type": "char", "name": "hana", "expression": "happy" }
  ],
  "next": "after"
}

You rarely type the whole data form by hand. The script is sugar for this. Direction files usually hold only the extra fields you could not say in brackets.

Fields most moments use

Mid-line tags ({@w}, {@cN}, {@talk:…}) live inside text. Batches for {@cN} sit in flow_commands; leave actions use exit_commands — Adding direction to a script scene · Command flow.

Watch it live

In the author player, F12 → Nodes lists every moment. Open one to see the live fields after script and direction are merged. Vars shows flags; Validation catches broken jumps and missing assets — How you work.

Usually you need

Full map

Every moment field in one view: story/story.json file map. Full tables for choices, script sugar, and Mode B: Story detail.

Next

Adding direction to a script scene

Adding direction to a script scene

Lives in: story/script.txt + story/story.json

Keep dialogue and flow in the script. Put precise staging in a direction entry with the same id.

Name the scene

:: park
HANA:
Watch the meter.
-> after

The :: park name is the link. Without a stable id, the direction file cannot find the moment.

Add a patch

story/story.json is a list of objects. Each object matches one script moment:

[
  {
    "id": "park",
    "commands": [
      {
        "type": "obj",
        "object": "meter",
        "instance_id": "score_meter",
        "show": true,
        "x": 16,
        "y": 16
      }
    ]
  }
]

How merge works

So the line and HANA: stay in the script; the meter object is only in the direction file.

A worked meter / flag bind lives in the presentation examples under examples/ (search for story.json next to a script.txt).

When commands run

Everyday timing stays in the script: Pacing. Use direction when the mid-line or leave action is too heavy for a bracket. Batches and indexing: Command flow.

Choices and other overlays

You can also replace or flesh out choices, panel fields, auto, and similar on the matched id. Prefer replacing only what you must; leave speakers and text in the script when they are already clear.

Usually you need

Next

Reacting to flags live · Commands

Reacting to flags live

Lives in: story/story.json (and object / sprite packs)

Make something on screen follow what the story remembers — a meter, a lamp, a command that only runs if a condition is true.

A flag drives a picture

Set a flag in the script:

[score = 3]
HANA:
Watch the meter.

An object (or sprite part) can bind a property to that flag — position, colour, and similar — so it updates when the flag changes. The bind lives on the object file; the moment only shows the object:

{
  "id": "park",
  "commands": [
    {
      "type": "obj",
      "object": "meter",
      "instance_id": "score_meter",
      "show": true
    }
  ]
}

Building the meter parts and bind map: Sprites and objects. Characters can bind opacity, modulate, scale, and shader uniforms the same way — Expressions and packs. Worked examples also live under examples/.

Flags themselves: Choices and memory.

Run a command only if…

On a command in the direction file, add when with an expression:

{
  "type": "sfx",
  "value": "chime",
  "when": "score >= 3"
}

If the expression is false (or errors), that command is skipped; the rest of the moment continues. Expressions use the same language as [if …] — Choices and memory.

when is data-only (no script sugar for it yet).

Things that stick, things that last one beat

Some commands change the stage for the whole play until you change them again. Others should apply only this moment.

Used on surfaces such as panel look, name plate, objects, and some layouts. To clear a sticky override, send that command family again or use "reset": true where the command allows it.

For many shaders: leave the key out = keep what is there; set the key to null = clear. Check the stage / polish page for that surface when you use it.

Usually you need

Next

Stage pictures and sound in depth: Backgrounds. Or return to Setting up your game for project defaults.

Sticky state and clear

Some story commands change the stage for the whole session. Others last one moment. Omitting a key often means “leave as-is”; null often means “clear.” Getting that wrong is how backgrounds and shaders “stick forever.”

Most stories

• Default: stage changes persist until you change them again (or reset / new session).
• Use "apply": "node_local" when a panel / layout / labelplate should revert after this beat.
• Use "reset": true (or an explicit clear) when a sticky override must go away.
• For shaders and similar: omit = keep current; null = clear.
• Character modulate / opacity / scale are not sticky — set them again on each char command when you want them to carry on — Characters on stage.

Where this lives

{ "type": "panel", "preset": "whisper", "apply": "persistent" }
{ "type": "panel", "preset": "whisper", "apply": "node_local" }
{ "type": "labelplate", "reset": true }
{ "type": "bg", "value": "street", "shader": null }

apply

Used on (among others): panel, labelplate, char_layout, obj, screen_shader. Shape: Shared shapes.

when is separate: skip this command if the expression is falsy (JSON / Mode B only).

Absent vs null (common sticky fields)

Always check the command’s detail page when unsure — a few surfaces treat absent differently (panel shader on the node is the common surprise).

How to undo

Save / back: sticky stage is part of cumulative save; node_local is not meant to outlive the moment. Save, Back and story end.

Related

Command flow · Shared shapes · Shaders · Commands

Planes and slots

Two ideas decide where things appear on screen. A render plane decides what draws on top of what. A slot is a named place on the character plane where one character stands.

Everything on one screen: planes stack from back to front, slots hold characters left to right.

Most stories

You can ignore most of this page until you need it.

• Background at the back, characters in the middle, dialogue panel in front.
• Default layout gives you three slots: left, center, right. Write [hana left] and you are done.
• Put a character over the panel with draw_layer: "above_panel" on the char command (or in their pack / slot).
• Switch arrangements mid-scene with char_layout once you have named profiles in game.json.

Where this lives

{
  "layout": {
    "characters": {
      "mode": "adaptive",
      "adaptive": { "slot_count": 3, "slot_width": 600 }
    }
  }
}

{ "title": { "role": "modal" } }

{ "type": "sprite", "value": "alert", "layer": "overlay" }

Keys: Choice and character layout · Theme: panel for panel slots.

Render planes

Planes are fixed. You cannot add or renumber them; you choose which plane your content goes to.

Higher layer numbers draw on top. Four planes share layer 0, so their order comes from scene tree order instead, bottom to top: background, scene UI, characters, panel. That is why a role: "scene" screen sits behind your characters while a role: "hud" screen sits in front of everything in the story.

Where the screen shader goes

screen_shader is not on the ladder above. It moves itself based on target. Details: Shaders.

Sprite layers

The sprite command has three layers, and they are not one contiguous band — they interleave with characters and the panel:

Character slots

A slot is a rectangle on the chars plane that holds one character. Each slot has two names:

• A slot id (slot_0, slot_left, …) — internal, used inside a layout profile.
• An alias (left, center, right, …) — what you write in a story: position: "left".

You always write aliases. The alias-to-slot mapping belongs to a layout profile, and switching profiles is how you rearrange the stage mid-scene.

Profiles come from layout.characters in game.json, in one of two modes.

Adaptive mode (default)

You state how many characters can be on screen and how big they are; slot rectangles are generated to fit the window.

{
  "layout": {
    "characters": {
      "mode": "adaptive",
      "base_texture_size": 600,
      "adaptive": {
        "slot_count": 3,
        "slot_width": 520,
        "snap": "bottom",
        "margin": 0
      }
    }
  }
}

base_texture_size sits one level up, directly under layout.characters, and defaults to 600.

Canonical alias names depend on the slot count:

"indexed" always gives slot_1 … slot_N regardless of count. "custom" uses your aliases array in left-to-right order; if the array is the wrong length or has duplicates, it falls back to canonical names and warns.

Explicit mode

You place every slot by hand. Use this when characters should not be evenly spaced, when slots overlap deliberately, or when different scenes need different arrangements.

{
  "layout": {
    "characters": {
      "mode": "explicit",
      "explicit": {
        "active_profile": "default",
        "profiles": {
          "default": {
            "aliases": { "left": "slot_left", "right": "slot_right" },
            "auto_selection_policy": "nearest_center_out",
            "slots": [
              { "id": "slot_left",  "x": 0,   "y": 20, "width": 700, "height": 700, "z": 1, "order": 0 },
              { "id": "slot_right", "x": 580, "y": 20, "width": 700, "height": 700, "z": 1, "order": 1 }
            ]
          },
          "closeup": {
            "aliases": { "center": "slot_big" },
            "slots": [
              { "id": "slot_big", "x": 290, "y": 0, "width": 900, "height": 900, "z": 2, "order": 0 }
            ],
            "transition": { "kind": "fade", "duration": 0.35 }
          }
        }
      }
    }
  }
}

A profile has four keys:

A slot has these keys:

Which plane a character ends up on

draw_layer is resolved in this order, first match wins:

1. draw_layer on the char command
2. ui.draw_layer in the character’s pack JSON
3. draw_layer on the slot in the layout profile
4. "behind_panel"

Placing a character without naming a slot

When a char command omits position:

1. If that character is already on screen, they stay in their current slot.
2. Otherwise the first free alias in auto_selection_policy order is used.
3. If every alias is taken, nothing is shown and a warning is logged.

Showing a character in a slot also removes them from any other slot, instantly and without a transition, so a character can never be in two places.

Switching profiles mid-scene

The char_layout command activates a different profile.

[char_layout closeup fade 0.35]
[char_layout reset]

Characters keep their alias across the switch. If the new profile still defines that alias, the character moves to the new rectangle. If it does not, the character overflows: they are hidden with a 0.2 second fade, and a warning names the alias and character. Two characters resolving to the same slot id is also an overflow for the second one, ordered by the old slot order.

policy decides what happens when anything overflows:

transition decides how slots move. "instant" snaps. "fade" glides surviving slots to their new position over duration seconds, easing out. If the command omits transition, the target profile’s own transition block is used; if that is also missing, the switch is instant. A fade with no duration anywhere uses 0.3 seconds.

Only slots that exist before and after the switch glide. Characters appearing or disappearing are handled by their own char show and hide transitions.

Panel slots

The dialogue panel has its own small slot system for chrome such as a speaker portrait pinned to the panel. Those are declared in the theme under panel.<preset>.slots, not in layout.characters, and they follow the panel rather than the window. See Theme: panel. Stage props: Sprites and objects. UI screens: Title, pause and settings screens.

Backgrounds

Lives in: backgrounds/

Places your story happens in. Folders and formats: Pictures, sound, and folders. Script sugar: Stage directions.

Pictures on disk

Write the name without the extension. Formats: .png, .jpg / .jpeg, .webp, .svg.

Change place

[bg street]
[bg street fade 0.5]
[bg park slide_left 0.6]
[bg clear]

As data:

{ "type": "bg", "value": "street", "transition": "fade", "duration": 0.5 }

value: null clears. Same-track music rule does not apply here — each bg sets the place.

Effects on a background

You can attach a shader (and optional parameters) on the background command. Leave the shader key out to keep what is there; set it to null to clear. Full shader authoring: Shaders. Sticky omit vs null: Sticky state and clear.

Command fields opacity, modulate, and visible set how the plate looks; live binds can drive the same look from flags — including image to swap the picture (same stems as value, under backgrounds/). Bind image swaps are instant; use [bg … fade …] when you want a transition.

Day / night from a flag:

{
  "type": "bg",
  "value": "street",
  "bind": {
    "image": {
      "flag": "time",
      "map": { "day": "street", "night": "street_night" },
      "default": "street"
    }
  }
}

Prefer a sprite/object for small overlays; keep bg for the full scene picture. Show/hide hooks on the command still work as elsewhere.

Richer rooms

Backgrounds that behave like multi-layer places (hotspots, room camera) are still early — In development. Ship with single pictures and [bg …] today.

Usually you need

Next

People on stage: What a character is · then Sprites and objects

Sprites and objects

Lives in: sprites/

Props and gadgets on top of the scene — not character folders. Skip this folder until you need a chair, lamp, phone overlay, or flag-driven meter.

A picture on the scene (sprite)

Sprites are data-only (direction file / story data — no [sprite …] sugar in the script today):

{
  "type": "sprite",
  "id": "chair",
  "value": "chair",
  "layer": "bg_front",
  "x": 625,
  "y": 494
}

You can also draw a plain rect or polygon (kind) instead of an image. Optional fade, tint, shader (one per sprite), and live binds work here too.

Reusable objects (*.obj.json + obj)

A catalog object is a file like sprites/meter.obj.json: an id, a default layer, and a list of parts (images or shapes).

{
  "id": "meter",
  "layer": "overlay",
  "parts": [
    { "id": "bg", "kind": "rect", "width": 40, "height": 120, "color": "#343a52e0" },
    {
      "id": "ptr",
      "kind": "polygon",
      "points": [[12, 0], [0, 10], [12, 20]],
      "bind": {
        "y": { "flag": "score", "map": { "1": 90, "3": 50, "5": 10 }, "default": 50 }
      }
    }
  ]
}

Show an instance on a moment:

{
  "type": "obj",
  "object": "meter",
  "instance_id": "score_meter",
  "show": true,
  "x": 16,
  "y": 16
}

A shader on an object applies to the whole instance (all parts composited), not per part.

Objects do not use character-style extends. Parts are a flat list; change them with update and binds — Reusing settings.

Putting the obj on a script scene: Adding direction to a script scene. Flag-driven examples: Reacting to flags live.

Usually you need

Full map

objects file map · Objects detail

Next

Music and sound

Music and sound

Lives in: audio/bgm/ and audio/sfx/

Music beds and one-shot effects during the story. Title defaults and UI clicks live in game.json — Music and sounds by default. Folders: Pictures, sound, and folders.

Names and formats

Formats: .ogg or .mp3. Use the name without the extension.

Music

[bgm theme]
[bgm theme fadein 1.5]
[bgm stop]

As data:

{ "type": "bgm", "value": "theme", "volume": 0.7, "fadein": 1.0 }
{ "type": "bgm", "value": null, "fadeout": 1.0 }

Playing the same track again does not restart it (volume can still update). Different track with both fade-in and fade-out → crossfade.

Title screen music uses sounds.main_bgm* in game.json, not these command defaults.

Sound effects

[sfx door]

{ "type": "sfx", "value": "door" }

One-shot. Optional volume and similar fields exist in data form. Button clicks and typing beeps are separate defaults under sounds — Text speed and voice beeps.

On a moment vs on a button

Usually you need

Next

Look of the dialogue box and menus: Theme and the dialogue box. Or directing heavy staging: When the script is not enough.

What a character is

Lives in: characters/<id>/

A character is a folder whose name is the id (hana). The script uses that id for speakers (HANA:) and stage directions ([hana left]). Folders and file names: Pictures, sound, and folders.

The simple path

characters/hana/
  hana.png
  hana_happy.png

[hana left fade 0.4]
[hana happy left]
[hana hide]
HANA [happy]:
Good morning.

HANA [happy]: both speaks and stages that expression. Bracket lines show, move, or hide without a line of dialogue — Stage directions.

What comes next in this part

Props and backgrounds are not characters — The stage.

Usually you need

Next

Expressions and packs

Expressions and packs

Lives in: characters/<id>/*.json

When one PNG per look is not enough, a pack lists stacked pictures (layers) for each expression. Same folder as the PNGs; often named default.json.

A small pack

{
  "display_name": "Hana",
  "default": [
    { "path": "base.png" },
    { "path": "mouth.png" }
  ],
  "happy": {
    "extends": "default",
    "override": [{ "layer": 1, "path": "mouth_happy.png" }]
  }
}

This is layer reuse, not the same as panel "extends" — Reusing settings.

Unknown expression names fall back to default.

Pack root (not layers)

Keys at the top of the file describe the character, not one expression:

Reserved filenames (not packs): sprites.json, objects.json, metadata.json, profiles.json.

Pack ui

Layer keys

A layer is usually a picture; it can also be a flipbook — Motion and frames.

Several pack files

Keep a simple default.json and a richer full.json (or similar). Switch with:

[char_pack hana full]

{ "type": "char_pack", "name": "hana", "pack": "full" }

Or set "pack": "full" on a single char command. char_pack alone does not redraw — the next show / expression change uses the new pack.

If the named pack is missing, the player tries default, then the first pack it finds.

Locale overlays

For a translated art set, add default_ja.json (or <pack>_<locale>.json) beside the base pack. The player picks the overlay that matches the active language when it exists.

Simple PNGs still work

If there is no pack, the player keeps using hana.png / hana_happy.png. Adding a pack is optional polish, not a rewrite of the script.

Story look (tint, shader, bind)

Separate from the pack file — on a char command (direction file or data):

{
  "type": "char",
  "name": "hana",
  "position": "left",
  "opacity": 0.85,
  "bind": {
    "opacity": { "flag": "trust", "linear": [0, 0.3, 10, 1.0] }
  }
}

Show/hide fades in the script ([hana left fade 0.4]) are stage enter/leave — expression-to-expression blends live in the pack — Expression fades.

Usually you need

Full map

Pack keys at a glance: characters pack map. Full tables: Character pack detail.

Next

Expression fades · Talking and focus

Expression fades

Lives in: character pack → composition_transitions

Two different fades:

This page is the second kind.

Pack policy

"composition_transitions": {
  "default": { "kind": "fade", "duration": 0.2, "swap_mode": "auto" },
  "pairs": {
    "happy->angry": { "kind": "fade", "duration": 0.4, "swap_mode": "crossfade" }
  }
}

Payload

auto: fade → crossfade; slide → in_only; otherwise in_only.

Resolve order: exact pair → from-wildcard → to-wildcard → *->* → from map → to map → default → instant.

When the command wins

If the char command names a transition (transition, transition_in / transition_out, or a duration), that command wins for that beat — including show/hide.

If the command says nothing about transitions:

• Expression change on someone already visible → pack composition_transitions
• Otherwise → instant

Force blend style with "swap_mode": "crossfade" (and friends) on the command when you need a one-off.

Usually you need

Next

Talking and focus

Talking and focus

Lives in: character packs (drive on layers / pack root) and the story’s speakers

While text types, the player can drive mouth (and similar) layers. Focus can emphasise who the line is about. Speakers and (silent): Lines and speakers.

Drive reacts to live UI state (typing, focus, open choices). It is not the same as a bind, which follows a story flag — Reacting to flags live.

Mouth layers

"default": [
  { "path": "base.png" },
  { "path": "mouth_closed.png", "drive": "!typing" },
  {
    "frames": ["m1.png", "m2.png"],
    "fps": 10,
    "loop": true,
    "drive": "typing"
  }
]

Text still types either way. (silent) on a speaker (or on one name in a joint line) turns that character’s typing driver off — mouths stay on the closed layer.

Voice beep is separate (game.json sounds) — Text speed and voice beeps.

Pack-root drive (focus and more)

At the pack root, drive can change the whole look while a driver is on — swap expression, tint, scale, nudge:

"drive": {
  "focus": {
    "use": "happy",
    "priority": 10,
    "scale": 1.05
  },
  "choice_open": {
    "modulate": "#ddddff",
    "priority": 5
  }
}

Drivers are recomputed after load or Back — they are not stored in the save. Flag overlays stay on bind.

Joint lines

HANA [happy] & SORA (silent): — both in the group; only non-silent names get the typing mouth. One name plate for the group — Lines and speakers.

Usually you need

Next

Places on stage

Places on stage

Lives in: game.json → layout.characters, plus char / char_layout in the story

Where people stand, and whether they draw under or over the dialogue box.

Default places

[hana left]
[sora center]
[emi right]

By default the project offers an even row of places — usually left, center, right. Counts, sizes, and names come from:

"layout": {
  "characters": {
    "mode": "adaptive",
    "adaptive": {
      "slot_count": 3,
      "slot_width": 400,
      "slot_height": 720
    }
  }
}

Project defaults: Choice and character layout. Full key list: game.json map.

Change arrangement mid-story

Use a char_layout command (usually from a direction file) to switch to another profile — close-up, three-wide, off-stage row, and so on — when you have named those profiles in layout.characters.

Behind or above the dialogue box

Characters usually draw behind the dialogue panel so text stays readable. Panel system: What a panel is.

Set it on the pack (ui.draw_layer) or on a single char command.

This is not the same as sprite/object layer bands (bg_front / fg / overlay) — those are for props — Sprites and objects.

A character shader applies to the whole slot (all layers composited), not to one layer.

Usually you need

Next

Motion and frames

Motion and frames

Lives in: character pack layers

How a layer can animate while someone is on stage. Soft idle sway and 3D models are still early — see below.

Flipbook layers

A layer can be one picture (path) or a short flipbook:

{
  "frames": ["blink1.png", "blink2.png", "blink1.png"],
  "fps": 8,
  "loop": true
}

Combine with drive so a mouth flipbook runs only while typing — Talking and focus.

What is not ready yet

Ship with still poses and flipbooks you control. Treat idle and 3D as upcoming, not release blockers.

Story animation presets

Separate from pack flipbooks: story animate commands and shared presets — Animation. Use those for scripted moves; use layer frames for blink / mouth cycles on the character itself.

Usually you need

Next

Back to the room: Backgrounds · Sprites and objects · Music and sound.

What a panel is

Lives in: theme panel.<preset> + story routing

A panel is the dialogue box — the place text, the name plate, and on-panel choices appear. Most games need only one. Extra panels are for side commentary, whisper boxes, or a second speaker’s sticky line.

Two names that matter

Id = which box. Preset = how that box is drawn. You can put look whisper on id main, or look default on id side.

One box is enough

Ship with a single main panel and a default preset. Speakers write into main unless you say otherwise. Name plate and Continue / Back live on that box.

HANA:
Good morning.

No panel fields required.

Where the pieces live

Fonts and whole-theme colours sit under Look. Character preference for a panel: pack ui — Expressions and packs.

Usually you need

Next

How text finds a panel

How text finds a panel

Lives in: story nodes, character packs, and the panel command

Each dialogue moment draws text on one panel — the routed panel. Routing picks the id and the preset.

Which panel id gets the text

First match wins:

1. Node field panel_id
2. Pack ui.default_panel_id for the first speaker on the line (talking[0])
3. Otherwise main

{
  "id": "side_note",
  "panel_id": "side",
  "talking": ["hana"],
  "text": "She muttered aside."
}

With several speakers and no panel_id, only the first speaker drives routing (and panel speaker art). Joint lines: Lines and speakers.

If the id is not main and that panel does not exist yet, the player creates it (there is a small cap on extra panels). main is never destroyed.

Which preset (look) it uses

First match wins:

1. Node field panel (preset name)
2. preset on a panel command aimed at that panel
3. Character ui.default_panel_preset, if that preset exists in the theme
4. A preset whose name matches the panel id (e.g. id side → panel.side)
5. default

Unknown names fall back to default.

{
  "id": "soft",
  "panel": "whisper",
  "talking": ["hana"],
  "text": "…"
}

Character pack defaults:

"ui": {
  "default_panel_id": "main",
  "default_panel_preset": "whisper"
}

Sticky vs one-shot

Script sugar [panel whisper] sets the preset on main. Direction files can set panel_id and policy fields when the script is not enough — Adding direction.

Usually you need

Next

How a panel looks

How a panel looks

Lives in: themes/default.json → panel.<preset>

Presets are named looks. The story picks a preset; the theme decides size, colour, padding, name-plate docking, and how tall the box may grow before the text scrolls.

{
  "panel": {
    "default": {
      "width": "100%",
      "anchor_v": "bottom",
      "min_height": 200,
      "padding": { "top": 20, "left": 24, "right": 24, "bottom": 24 },
      "bg": "#1e2133e0",
      "corner_radius": 12
    },
    "whisper": {
      "extends": "default",
      "width": "60%",
      "anchor_h": "center",
      "bg": "#00000099"
    },
    "side_log": {
      "extends": "default",
      "width": "36%",
      "anchor_h": "right",
      "offset_x": -16,
      "anchor_v": "stretch",
      "max_height": "full",
      "scrollbar_layout": "reserve"
    }
  }
}

default is the fallback preset. Other names are yours. "extends" merges another preset’s keys — Reusing settings.

Same box, two moments. The plate grows with its text, holds the name plate and portrait, and hosts choices when they appear. Continue is hidden while choices are up.

Same stage, two presets. Only the preset name changed — size, colour, and where the plate sits come from panel.<preset> in the theme.

Usually you tune

Height and body scroll

The plate grows with text (and panel-hosted choices) up to max_height. Past that ceiling, the body text scrolls inside the plate. Name plate, panel-placed Continue / Back, and choices stay outside the scroll area.

A sticky { "type": "panel", "max_height": … } overrides the theme preset until reset.

Scrollbar column

Use reserve on logs, phone panels, or any fixed-height plate that scrolls often. Leave normal ADV boxes on default.

Panel-hosted choices (host: "panel") share the plate and shrink the body. Overlay choices sit on the screen and do not take body space. A choice list taller than the ceiling can still clip — body scroll is for dialogue text, not a separate choice scroller.

Mood for one scene

A scene can load another theme/mood file that overrides panel presets for that stretch — Theme and the dialogue box. Otherwise, prefer a second preset (whisper) or a sticky panel command.

Bind and shader

A panel command can tint or hide from flags (bind on opacity / visible) and attach a panel shader. Flag binds in depth: Reacting to flags live.

Usually you need

Next

Several panels

Several panels

Lives in: theme presets + story panel_id / panel commands

Use more than one panel when two conversations should stay visible, or a side box holds a note while main advances.

Create another box

Ask for a new id on a node or command:

{ "id": "aside", "panel_id": "side", "panel": "side", "talking": ["hana"], "text": "…" }

{ "type": "panel", "panel_id": "side", "preset": "side", "show": true }

If theme panel.side exists, routing can pick that preset by matching the id name. Otherwise set "panel": "…" or pack default_panel_preset explicitly.

main always exists. Extra ids are created when first used (capped — keep the cast of boxes small).

Stacking

Higher z draws above. Keep the active reading box easy to see.

Patterns that work

Stage character places (left / center) are a different system — Places on stage. Drawing characters above/behind the box is draw_layer, not a second panel.

Side log (append + scroll)

A common second box: full-height (or tall) side panel that collects lines and scrolls inside the plate.

1. Theme preset with "max_height": "full" (or "80%") and "scrollbar_layout": "reserve" — How a panel looks
2. Sticky { "type": "panel", "panel_id": "side", "preset": "side_log", "text_mode": "append" }
3. Moments that write to "panel_id": "side" (or pack default_panel_id)
4. Optional [panel panel_id side clear_append] when the thread should restart — Appending text

Keep main on normal replace dialogue while the log accumulates.

Usually you need

Next

Presence and quiet panels

Presence and quiet panels

Lives in: panel policy on pack / panel command / node fields

The routed panel is the one receiving this moment’s text. Other panels are non-talking — policy decides whether they hide or stay as a dim reminder.

Policy fields

Practical recipe: keep a side box around without the speaker → always_visible + readonly_last_text. Plain hide when unused → leave defaults.

Today talk_only and visible_with_char do not differ for show/hide; prefer always_visible when you need “stay up.”

Where policy is set

Order (later wins for sticky layers as noted in the live rules):

1. Built-in defaults
2. Character pack ui.panel_policy
3. Sticky fields from a panel command (presence_mode, non_talking_mode, …) — beat the pack
4. Node fields panel_presence_mode, panel_non_talking_mode, panel_readonly_style_key — this node only

policy_reset or full reset on a panel command clears sticky policy.

Show hold

show: true on an off-route panel sticks: policy cannot instantly hide it until show: false, reset, or policy_reset. Use that for a deliberate “pin this box.”

Node hide_panel hides the routed panel for that node only — different from non_talking_mode: "hide" on other panels.

Text modes

Default is replace — each line clears the panel. To stack lines in the same box, use append — full fields and sticky vs node: Appending text.

Usually you need

Next

Appending text · Speaker art on the panel

Appending text

Lives in: story moment fields and the panel command (text_mode)

By default each new moment replaces what was in the panel. Append keeps earlier text and adds this moment’s text — useful for a running log, a chat-style beat, or a sticky side panel that accumulates notes.

A moment is one click-through step of the story (also called a node in tools and data) — Words used in these docs.

Replace vs append vs plates

Per-plate transition_in / transition_duration animate the live plate chrome inside the body scroll on each new beat (see Theme: panel → Plates).

plates uses the same append_direction, append_gap_px, append_push_duration, and clear_append keys as append.

Not mid-line typing: while one moment’s text is revealing, that is still one block. Append decides what happens when the next moment writes to the same panel.

{
  "id": "log_1",
  "panel_id": "side",
  "text_mode": "append",
  "talking": ["system"],
  "text": "Door unlocked."
}

For a lasting chat, prefer a sticky command so later moments keep appending:

{ "type": "panel", "panel_id": "side", "text_mode": "append", "max_height": "full" }

[panel panel_id side text_mode append]
[panel clear_append]

Direction and gaps

When append fills past the panel height ceiling, the body scrolls and keeps the newest edge in view (down → bottom, up → top). Set the ceiling with theme max_height or a sticky panel max_height — How a panel looks.

Changing append_direction on a panel that already has a thread keeps that history and re-pins it for the new direction (newest at the bottom for down, at the top for up). It does not start a fresh log — use clear_append when you want a wipe.

Editing the script in author mode while you are mid-thread re-reads sticky panel keys (append_direction, text_mode, gaps) along the moments you already played — including the moment that opened the thread — then reorients the live thread. You do not need to be on the same moment as the sticky command. Going back after that keeps the rehydrated direction (it does not restore the pre-edit value).

Sticky vs one moment

A moment’s text_mode overrides a sticky panel setting for that moment only.

Clear the thread, keep the mode

clear_append wipes history on that panel but keeps sticky append mode, direction, preset, and policy. Use it for a fresh chat on the same box without a full reset.

[panel panel_id side clear_append]

Same-moment clear_append applies before that moment’s first paint.

Script sugar for everyday append is limited — use the direction file / moment data, or a panel command before the stretch of moments ([panel … text_mode append] / [panel clear_append] exist).

With several panels

Append is per panel id. main can stay on replace while side or a phone panel appends. A quiet append panel keeps its history until you write to it again. Presence / readonly on quiet panels is separate — Presence and quiet panels. Tall log recipe: Several panels.

Usually you need

Next

Speaker art on the panel

Speaker art on the panel

Lives in: theme panel slots + character pack ui.panel_slots

Some panel presets reserve a slot for a picture — a bust, icon, or object that follows who is talking. That art is not a stage character place; it is chrome inside the box.

Theme slot

The preset declares a slot id (for example speaker_art) with position and size. Details grow with the theme map; copy a working preset from examples/ when you want a portrait strip.

Pack map

Point the slot at an object (or sprite) id the character owns:

"ui": {
  "panel_slots": {
    "speaker_art": "hana_portrait"
  }
}

When this character is first speaker / routed, the panel can show that art. Theme binding "bind": "talking" on panel chrome is speaker art, not a story-flag bind — Expressions and packs · Reacting to flags live.

With joint lines

Only the first speaker in talking drives panel routing and slot art unless you set panel_id yourself — Lines and speakers.

Usually you need

Next

Look chrome around the box: Theme and the dialogue box · Name plate

Theme and the dialogue box

Lives in: themes/default.json

Fonts, colours, and shared chrome for the whole game. The dialogue box (presets, routing, height, scroll) lives in its own part of the handbook:

→ What a panel is · How a panel looks

Where the theme lives

Put font files under fonts/. Locale overlays can sit beside the base theme as default_<locale>.json. Pack files for choices and inputs are separate stems under themes/ — Choice and input looks.

"extends" on a panel preset merges keys — Reusing settings.

Fonts and sizes

"typography": {
  "font": "Jupiteroid",
  "font_menu": null,
  "font_dialogue": null,
  "font_label": "Jupiteroid",
  "size_scale": 1.0,
  "sizes": {
    "speaker": 45,
    "dialogue": 30,
    "choice": 30,
    "button": 30,
    "notification": 30
  }
}

Change sizes.dialogue or font, reload (F5 / F6 for look), and play a line.

Colours

"colors": {
  "background_default": "#dfdcd7",
  "speaker_text": "#c4693a",
  "dialogue_text": "#e8e5e0",
  "choice_text": "#c5cad5",
  "notification_text": "#dfdcd7"
}

Panel plate colour is usually panel.<preset>.bg, not colors — How a panel looks.

Full map

Every allowed key in one view: themes/default.json file map. Panel, buttons, and choice/input packs: Theme detail.

Mood for one stretch of story

A mood profile is another theme file (for example themes/flashback.json) that merges over default.json for a while:

{ "type": "theme_style", "profile": "flashback" }
{ "type": "theme_style", "reset": true }

Sticky until you reset or start a new game. It does not switch choice packs — use a choice style command / pack for that — Choice and input looks.

Until you add a mood file, a second panel preset or a sticky panel command is enough for a quieter box.

Usually you need

Next

Name plate

Name plate

Lives in: themes/default.json → labelplate.*, plus character packs (display_name / ui)

The box that shows who is speaking.

What the character pack sets

Packs: Expressions and packs. Which box shows the name: How text finds a panel. Speakers and joint labels: Lines and speakers.

Theme styles

Named looks under labelplate.<style_key>:

"labelplate": {
  "default": {
    "font_color": "#ffffff",
    "font_size": 20,
    "bg": "#00000099",
    "padding_left": 12,
    "padding_right": 12,
    "padding_top": 6,
    "padding_bottom": 6
  },
  "whisper": {
    "font_color": "#cccccc",
    "bg": "#00000066"
  }
}

Resolution: start from labelplate.default (if present), then overlay labelplate.<style_key>.

Who picks the style

First match wins:

1. Explicit style_key on a labelplate command / moment field
2. Panel preset labelplate_style_key
3. Character pack ui.default_labelplate_style_key

Inline vs docked

By default the name sits inline above the dialogue text. If the panel preset sets labelplate_layout (anchors + offsets), the plate can dock to a panel edge instead — How a panel looks.

Story override

A direction labelplate command (or moment field) can change text, style, or visibility for a beat:

{
  "type": "labelplate",
  "panel_id": "main",
  "text": "???",
  "style_key": "whisper",
  "apply": "persistent"
}

Prefer pack display_name for everyday cast names; use the command for mystery labels and one-off looks.

Usually you need

Next

Choice and input looks

Choice and input looks

Lives in: themes/<pack>.json, plus layout / story fields

How choice buttons and the name-entry field look. Story choices and input flow: Choices and memory. Layout defaults: Choice and character layout.

Choice packs

A pack is a JSON file under themes/. The name is the file stem: "style": "choice_button" → themes/choice_button.json.

Two common roles:

"style" / "source" merge rules: Reusing settings. Locale overlays: themes/<name>_<locale>.json.

Button pack (usual ADV)

{
  "min_width": 220,
  "padding_left": 18,
  "padding_right": 18,
  "padding_top": 4,
  "padding_bottom": 6,
  "normal_texture": "sprites/button-normal.png",
  "hover_texture": "sprites/button-hover.png",
  "pressed_texture": "sprites/button-down.png",
  "texture_9slice": [6, 6, 6, 6],
  "font_color": "#3a2a1a",
  "font_hover_color": "#6b4420"
}

Flat colour keys (normal_bg, borders, …) work when textures are omitted or empty. Optional click_sfx / hover_sfx override default UI sounds for button choices.

Choice packs do not restyle screen/menu buttons (those use theme buttons) or the dialogue panel plate.

Sticky choice look

{ "type": "choice_style", "style": "choice_plain" }

Stays until you change it. Separate from theme_style mood profiles — Theme and the dialogue box.

Text input packs

Optional pack for story name-entry / text fields. No pack required — omit style and the field uses dialogue colours and flat fills.

Precedence: moment input.style → sticky input_style → layout.text_input.style → defaults.

theme_style does not restyle input chrome (same rule as choice packs).

Usually you need

Next

Free choices · Title, pause and settings screens · Choice packs · Text input packs

Free choices

Most menus are a stack of buttons. Free choices place options at absolute positions — hotspots on the stage, sprite faces, inspect scenes. Same story choices object; different container.layout.

Most stories

• Keep script > lines for ordinary menus (stack).
• For clickable art: write the choice as JSON in story.json with "mode": "free", item x / y, often "render_mode": "sprite".
• Do not combine shuffle or stack gap with free.

Where this lives

"choices": {
  "show_numbers": false,
  "container": {
    "layout": { "mode": "free", "host": "overlay", "render_mode": "sprite" }
  },
  "items": [
    { "text": "Door", "target": "enter", "layout": { "x": 420, "y": 280 } },
    { "text": "Leave", "target": "NEXT", "layout": { "x": 900, "y": 600 } }
  ]
}

Worked pack: examples/example-05-ui-and-polish/themes/choice_yes_no.json.

Same items, same mode: free and render_mode: sprite. The only difference is host: overlay leaves them floating at their absolute x / y, while panel puts them inside the dialogue plate, which grows to fit.

Stack vs free

Hover / pressed looks: Shared shapes → state_visual. Full keys: Choices (story). Ordinary menus: Choices and memory · Choice and input looks.

Title, pause and settings screens

Lives in: screens.json

Menus and boards around the story — title, pause, settings, credits, custom galleries. Separate from the dialogue panel and from stage sprites.

Most stories

{
  "defaults": { "transition_duration": 0.3 },
  "title": {
    "role": "modal",
    "layers": [
      { "type": "background", "order": 0 },
      {
        "type": "menu",
        "order": 10,
        "buttons": [
          { "label": "New Game", "interaction": { "hooks": { "on_click": "new_game" } } },
          { "label": "Continue", "interaction": { "hooks": { "on_click": "continue" } }, "show_if": "has_autosave" }
        ]
      }
    ]
  }
}

Copy a working screens.json from examples/ and change labels first — Your first ten minutes.

Full map

Every allowed key in one view: screens.json file map. Layers, blocks, and actions: Screens detail.

Roles

Auto HUD id comes from game.json → session.hud_screen (default "hud"; "" turns it off) — Save, Back and story end.

Layers

Each screen is a list of layers drawn in order:

Open and close

Screens stack. Top modal usually owns input; HUDs can stay underneath. Return to title clears persistent HUD strips.

show_if on buttons (and some blocks) hides them unless a condition is true — e.g. "has_autosave".

Save / load and history

Slot UI and history logs are content blocks inside your screens. Slot count is session.save_slots — Save, Back and story end. Polished slot chrome is still early — In development.

Usually you need

Next

Gameplay HUD · Buttons and actions

Gameplay HUD

Lives in: screens.json → screen with role: "hud"

A small bar (or corner controls) shown while the story plays — pause, backlog, and similar.

Default strip

"hud": {
  "role": "hud",
  "layers": [
    {
      "type": "menu",
      "order": 10,
      "layout": {
        "host": "panel",
        "anchor_h": "right",
        "anchor_v": "top",
        "offset_x": 8
      },
      "buttons": [
        {
          "label": "",
          "icon": "sprites/ico-pause.png",
          "interaction": { "hooks": { "on_click": "screen:pause" } }
        }
      ]
    }
  ]
}

Several different HUD ids can be up at once. Story can push another strip:

{ "type": "screen", "value": "minimap" }
{ "type": "screen", "value": "minimap", "show": false }

Usually you need

Menus around the story: Title, pause and settings screens. Button actions: Buttons and actions.

Next

Buttons and actions

Buttons and actions

Lives in: screens.json buttons · theme buttons / named packs

What menu and HUD buttons do, and how they look.

Actions you use most

Hooks can use the same strings, e.g. "on_click": "screen:pause". Conditions: "show_if": "has_autosave" (and similar) hide a button until it makes sense.

Full screen structure: Title, pause and settings screens.

How buttons look

Typical theme keys (flat or textured): normal / hover / pressed / focus colours or textures, corner radius, padding, font colours. Named packs under themes/ can override a screen’s button look the same way choice packs do — Reusing settings.

Default click / hover sounds come from game.json → sounds unless the pack sets click_sfx / hover_sfx — Music and sounds by default.

Usually you need

Next

Polish for menus: Transitions · Cursor · or back to Theme and the dialogue box

Transitions

Lives in: commands · game.json → transitions · packs / screens

How pictures and menus appear, leave, and swap. Three related systems use the word “transition” — keep them apart.

Kinds (stage and chrome)

Fields: transition (or transition_in / transition_out) and duration (or transition_duration).

[bg street fade 0.5]
[hana left slide_left 0.3]

{ "type": "bg", "value": "street", "transition": "fade", "duration": 0.5 }
{ "type": "char", "name": "hana", "transition_in": "slide_left", "duration": 0.3 }

Defaults (when you omit fields)

Do not fight opacity with animate on the same surface at the same time — Animation.

Scene fade (full-screen veil)

Separate from per-command fades. Timing in game.json:

"transitions": { "fade_default": 0.35 }

Used for the full-screen scene veil and as a fallback when a screen has no own transition. Not the same as the bg command’s 0.5s default.

Expression swaps (characters)

Same person, new look while already on stage → pack composition_transitions, not show/hide sugar — Expression fades.

Screens

Screen push/pop can set transition_in / transition_out / transition_duration on screens.json defaults or per screen — Title, pause and settings screens.

Panel plates (thread chrome)

Named plates under panel.<preset>.plates can set their own transition_in / transition_duration for each new beat. That motion stays inside the panel body scroll and is separate from whole-panel show/hide — Theme: panel → Plates.

Usually you need

Next

Animation

Animation

Lives in: story animate / stop_animate · optional animations/presets.json

Tweens (or steps) a property on something already on stage. Show/hide fades are a different system — Transitions. Character flipbooks live in the pack — Motion and frames.

Most stories

{
  "type": "animate",
  "target": "char:left",
  "property": "position_x",
  "to": 20,
  "duration": 0.3,
  "relative": true
}

{ "type": "animate", "preset": "shake", "intensity": 8, "duration": 0.5 }
{ "type": "animate", "preset": "bob", "target": "sprite:fairy", "distance": 8 }
{ "type": "stop_animate", "target": "char:left" }
{ "type": "stop_animate", "all": true }

Built-in presets: shake, pulse, flash, bob. Author presets: files under animations/presets.json (locale overlays allowed).

Targets

Common properties: opacity, position_x / position_y, scale, modulate, shader:<uniform>. Give an id when you need a precise stop_animate.

Do not animate opacity on a surface while a transition is also fading that surface.

Usually you need

Full map

animations/presets.json map · Animation presets · animate

Next

Shaders