TsumugiComing soon
ChangelogReport a bug

Getting started

What you need

  • VS Code, VSCodium, Cursor or Windsurf. VS Code must be version 1.90 or newer.
  • Windows, macOS or Linux.
  • A GameMaker project that uses Chatterbox.

Note

Tsumugi does not add Chatterbox to your game. Add it the way the Chatterbox documentation explains, then open the game with Tsumugi.

Install Tsumugi

  1. In your editor, open the Extensions view.
  2. Search for Tsumugi, then click Install.

You can also install it from the Visual Studio Marketplace. VSCodium, Cursor and Windsurf find it with the same search.

The first time Tsumugi runs, VS Code shows Get Started with Tsumugi: a short page with the guide and your licence. Open it again any time with the Tsumugi: Get Started command.

Open your game

Open the folder that holds your game’s .yyp file, with File › Open Folder….

Tsumugi finds the game by itself. The Tsumugi icon appears in the Activity Bar (the column of icons at the side of the window). Click it to see Story files: every dialogue file in your game.

Set up the project

Click Set up this project in the Tsumugi sidebar. It shows while your game has no tsumugi.json file. You can also run Tsumugi: Set up this project from the Command Palette.

Tsumugi looks at your game and guesses how it names things: which sprites are portraits and items, which objects draw backgrounds and map markers, and which files hold dialogue. It shows what it found and asks before it writes anything.

It writes one file, tsumugi.json, next to your .yyp, and opens it so you can check the guesses. See tsumugi.json.

Tip

You can write without setting up. Tsumugi still opens and checks your .yarn files. Setting up lets it find your art, so it can draw the preview and tell you what is missing.

Open a story file

  • In the Tsumugi sidebar, click a file under Story files. It opens in the Story Writer.
  • Or open a .yarn file, then click Open in Story Writer (the book icon at the top right of the editor).

.yarn files open as text unless you pick the Story Writer. Both show the same file. See Editing .yarn as text.

No story file yet?

Click New story file… in the sidebar. Type a name, like ChapterOne. Tsumugi shows what it will do and asks first. Then it:

  1. makes ChapterOne.yarn in your game’s datafiles folder,
  2. adds it to your game’s Included Files, so it ships with the game,
  3. opens it in the Story Writer.

Your game must also load the file with Chatterbox. Tsumugi tells you the line to add, and can add it for you. See How Tsumugi reads your game.

Learn with the guides

The first time you open the Story Writer, the full guide opens. It builds a small node with you, step by step. Every step can be skipped.

  • Non-Technical: for story games. Characters, backgrounds, options and simple checks. No programming.
  • Technical: everything in Non-Technical, plus items, typed answers, skills, the game’s map and testing in GameMaker.
  • I don’t know: answer a few questions, and Tsumugi suggests one.

In a hurry? Take the short guide instead shows the main parts in a few minutes.

The light bulb at the top left of the Story Writer opens the guides again. So does Tsumugi: Open the Full Guide (step by step) in the Command Palette.

Free trial and licence

Tsumugi starts with a free trial, with everything included. After it, the Story Writer needs a licence. Editing .yarn files as text, and the checks, stay free. See Pricing and Licence and privacy.

Next

Your first story walks through a node, an option and a jump.