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
| Shape | Looks like | Means |
|---|---|---|
| Text | "hana" | Names, paths, dialogue keys |
| Number | 0.5, 14 | Amounts, seconds, sizes |
| On / off | true / false | A switch (always lowercase) |
| Empty / clear | null | None — for example stop music, or clear a setting |
| Group | { "a": 1, "b": 2 } | Named fields together |
| List | [ "a", "b" ] or [ {…}, {…} ] | Items in order |
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)
| Mistake | What happens |
|---|---|
| A missing comma, or a comma after the last field | The file is skipped and defaults apply; author tools report the file and line of the problem |
| Missing quotes around a name | Invalid JSON — same report with file and line |
True / False (capital T/F) | Use true / false |
Comments (// or #) | Standard JSON has no comments — put notes in a README instead |
Single quotes '…' | Use double quotes "…" |
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