tsumugi.json

tsumugi.json tells Tsumugi how your game names things: which sprites are portraits, which objects draw backgrounds, how big the text area is. It sits next to your game’s .yyp file.

It is optional. Without it, Tsumugi still opens and checks your story files. With it, Tsumugi can find your art, draw the preview, and tell you what is missing.

Commit it with your game, so your whole team shares it.

Making it

Run Set up this project (Getting started). Tsumugi guesses from your project:

portraits from a sprite folder with portrait or face in its name,
items from a sprite folder with item or inventory in its name,
areas from objects that share a parent with area, scene, background or backdrop in its name,
map markers from objects whose parent has marker, location or map in its name,
story files from every .yarn file.

It shows what it found, and asks before it writes. Check the guesses: they are only guesses.

Editing it

Open it in VS Code like any JSON file. VS Code knows its shape: point at a key to see what it does, and a key Tsumugi doesn’t know is underlined. Press ⌃ Space for a list of keys.

Some parts are also saved for you from the Story Writer’s Settings tab: the text area, spelling, numbered options, the inventory and health hearts. Other parts change as you work, like words added to the dictionary.

Tsumugi changes only the keys it needs, and keeps the rest of the file as you wrote it.

An example

{
  "dialogue": ["datafiles/ChapterOne.yarn", "datafiles/ChapterTwo.yarn"],
  "portraits": { "spriteFolder": "Character Portraits", "prefix": "sPortrait_" },
  "items": { "spriteFolder": "Items", "prefix": "sItem_" },
  "textbox": { "lines": 3, "width": 900 },
  "preview": { "room": "rDialogue" },
  "words": ["Ayumi", "Onigiri"]
}

The main parts

VS Code shows the full, up-to-date list as you type. These are the parts most games use:

Key	What it is for
`dialogue`	The story files. Every `.yarn` file in `datafiles` when not set.
`portraits`, `items`	How those sprites are named, and which folder they are in.
`areas`, `locations`	The objects that draw each area, and the map’s markers.
`entryPoints`	Other places in your game’s code that start the story.
`actions`, `conditions`	Events and checks that are more than one function.
`textbox`	The text area: lines, width, font, and how lines are shown.
`preview`	The room the preview draws, and the health hearts.
`inventory`	How the game gives, takes and counts items, and where it draws them.
`unlocks`	The kinds of unlocks, and where their icons go.
`maxOptions`, `numberedOptions`	How many options fit at once, and whether they are numbered.
`words`, `spelling`	The game’s own words, and British or American English.
`warnings`	Checks this game turns off.
`gml`	Code to skip when reading your game.
`generated`	The names of the scripts Tsumugi writes.

Tip

If Tsumugi can’t read tsumugi.json, for example after a typo, it shows a warning and uses none of it until it is fixed. It never writes over a file it can’t read.