> ## Documentation Index
> Fetch the complete documentation index at: https://nonkit.rlaneth.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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
```

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

## Working with Yarn Scripts

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

```yarn title="scripts/Main.yarn" theme={null}
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

<CardGroup cols={2}>
  <Card title="Nodes" icon="cube">
    Self-contained dialogue segments identified by `title:`. Use `<<jump NodeName>>` to transition between nodes.
  </Card>

  <Card title="Line IDs" icon="hashtag">
    Tags like `#line:identifier` link dialogue lines to localization entries for translation support.
  </Card>

  <Card title="Commands" icon="terminal">
    Game actions wrapped in `<<command>>`. Control characters, backgrounds, audio, and game state.
  </Card>

  <Card title="Options" icon="list">
    Player choices marked with `->`. Can contain nested dialogue or commands.
  </Card>
</CardGroup>

## Running Nodes

nonkit-vsc provides multiple ways to run your scripts:

<Steps>
  <Step title="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".
  </Step>

  <Step title="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.
  </Step>

  <Step title="Command Palette">
    Run `nonkit: Run Selected Node` from the Command Palette to run the currently selected node.
  </Step>
</Steps>

<Note>
  Running a node temporarily overwrites the game's dialogue code. For best results, run nodes while on the guild view.
</Note>

## 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:

```yarn theme={null}
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:

```csv title="localization/zh-cn.csv" theme={null}
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                                                               |

<Note>
  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`).
</Note>

## 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.

<Warning>
  **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.
</Warning>

### TbMapEvent.json

Defines map events (quests and encounters):

```json title="config/TbMapEvent.json" theme={null}
[{
  "ID": 900001,
  "PlaceID": 9,
  "Title": "My Custom Quest",
  "DialogID": "MyQuestStart",
  "UnlockCondition": 900001,
  "Nonkit": { "IconSourceId": 10084 }
}]
```

### TbCondition.json

Defines unlock conditions for events:

```json title="config/TbCondition.json" theme={null}
[{
  "ID": 900001,
  "Conditions": "get_value(\"my_quest_available\") == 1"
}]
```

### TbLocalizationAutoGenerated.json

Stores generated localization entries for config table strings:

```json title="config/TbLocalizationAutoGenerated.json" theme={null}
[{
  "ID": "MapEvent_900001_Title",
  "EN": "My Custom Quest",
  "ZH-HANS": "我的自定义任务"
}]
```

<Card title="Quest Creation Guide" icon="map" href="/essentials/quest-creation">
  Learn how to create complete quests with events, conditions, and rewards.
</Card>

## 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.

<Warning>
  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.
</Warning>

## Next Steps

<CardGroup cols={2}>
  <Card title="Yarn Basics" icon="file-code" href="/essentials/yarn-basics">
    Deep dive into Yarn Spinner syntax.
  </Card>

  <Card title="Quest Creation" icon="scroll" href="/essentials/quest-creation">
    Complete guide to creating custom quests.
  </Card>

  <Card title="Limitations" icon="triangle-exclamation" href="/essentials/limitations">
    Understand what nonkit can and cannot do.
  </Card>

  <Card title="Yarn Reference" icon="book" href="/yarn-reference/introduction">
    Browse all commands and functions.
  </Card>
</CardGroup>