Project Development

Project structure, scripts, localization, and config files

Project Structure

A typical nonkit project contains Yarn scripts, localization files, and config tables:

my-project/
├── Project.nonkit.json          # Project configuration file
├── scripts/
│   ├── main-quest.yarn
│   └── side-events.yarn
├── config/
│   ├── TbMapEvent.json
│   ├── TbCondition.json
│   └── TbLocalizationAutoGenerated.json
└── localization/
    └── zh-cn.csv              # Chinese translations

The Project.nonkit.json file defines your project. The directory structure is the default; you can configure different paths in the project file.

Working with Yarn Scripts

Yarn files contain one or more dialogue nodes. Each node has a title, body, and ends with ===:

scripts/Main.yarn

title: ModQuest_Example
---
<<close_all_view>>
<<back_creat bg-4 true 0.0 1 0.7>>
<<char_creat Lilith 1 3 true 0,-1200 0.7 0 0.3>>

Lilith: Welcome to the example quest! #line:modquest_welcome
Lilith: This demonstrates custom content creation. #line:modquest_intro

<<line_hide>>
<<char_remove Lilith true 0.7>>

<<event_end>>
<<next_period>>
<<open_view GuildView>>
===

Key Concepts

Nodes

Self-contained dialogue segments identified by title:. Use <<jump NodeName>> to transition between nodes.

Line IDs

Tags like #line:identifier link dialogue lines to localization entries for translation support.

Commands

Game actions wrapped in <<command>>. Control characters, backgrounds, audio, and game state.

Options

Player choices marked with ->. Can contain nested dialogue or commands.

Running Nodes

nonkit-vsc provides multiple ways to run your scripts:

1. CodeLens Run Button

   Click the Run button that appears above each title: line in the editor. When connected to the game, it shows ”▶ Run”; when disconnected, it shows ”⊘ Not Connected”.

2. Nodes Panel

   Use the Yarn Nodes panel in the sidebar to browse all nodes across your project. Click a node to select it, then use the Run command.

3. Command Palette

   Run nonkit: Run Selected Node from the Command Palette to run the currently selected node.

Running a node temporarily overwrites the game’s dialogue code. For best results, run nodes while on the guild view.

Localization

nonkit expects you to write dialogue in English as your primary language directly in .yarn files, then provide translations for other languages.

Writing Localizable Dialogue

Add #line: tags to dialogue lines that need translation:

Lilith: Welcome to the example quest! #line:modquest_welcome
Lilith: This demonstrates custom content creation. #line:modquest_intro

The English text is written directly in the script. The line ID connects to translation files.

Translation Files (CSV)

Translations are stored in CSV files in the localization/ directory:

localization/zh-cn.csv

language,id,text,file,node,lineNumber,lock,comment
zh-cn,line:modquest_welcome,"欢迎来到示例任务！",Main.yarn,ModQuest_Example,5,,
zh-cn,line:modquest_intro,"这演示了自定义内容创建。",Main.yarn,ModQuest_Example,6,,

Column	Description
language	Locale code (e.g., zh-cn) - determines which language this file provides
id	Line ID matching the #line: tag in your script
text	Translated text
file	Source filename (for reference)
node	Source node name (for reference)
lineNumber	Line number (for reference)
lock	Optional lock flag
comment	Optional comment

The locale is determined by the language column in the CSV data rows. When creating a new localization file via the command palette, nonkit suggests naming the file after the locale (e.g., zh-cn.csv) as a convention, but what matters is the value in the language column of each row. Currently, the game supports English (primary) and Simplified Chinese (zh-cn).

Config Tables

Config tables define game data like quests, conditions, and map events. These are JSON files that mirror the game’s internal table structure.

Config tables are identified by filename. A file named TbMapEvent.json is recognized as the TbMapEvent table. Renaming the file would cause it to be treated as a different table.

TbMapEvent.json

Defines map events (quests and encounters):

config/TbMapEvent.json

[{
  "ID": 900001,
  "PlaceID": 9,
  "Title": "My Custom Quest",
  "DialogID": "MyQuestStart",
  "UnlockCondition": 900001,
  "Nonkit": { "IconSourceId": 10084 }
}]

TbCondition.json

Defines unlock conditions for events:

config/TbCondition.json

[{
  "ID": 900001,
  "Conditions": "get_value(\"my_quest_available\") == 1"
}]

TbLocalizationAutoGenerated.json

Stores generated localization entries for config table strings:

config/TbLocalizationAutoGenerated.json

[{
  "ID": "MapEvent_900001_Title",
  "EN": "My Custom Quest",
  "ZH-HANS": "我的自定义任务"
}]

Quest Creation Guide

Learn how to create complete quests with events, conditions, and rewards.

Hot Reloading

When you run a node, nonkit-vsc:

1. Compiles the Yarn script to bytecode
2. Sends it to nonkit-plugin via named pipe
3. The plugin merges it into the game’s dialogue system
4. Dialogue plays immediately

Changes to scripts take effect on the next run—no game restart required.

Config table changes require running the Load Config Tables command (nonkit.loadConfig) to take effect. You can also use Load All (nonkit.loadAll) to reload scripts, localization, and config together.

Next Steps

Yarn Basics

Deep dive into Yarn Spinner syntax.

Quest Creation

Complete guide to creating custom quests.

Limitations

Understand what nonkit can and cannot do.

Yarn Reference

Browse all commands and functions.