File Operations¶

TaleNode uses two file formats: .talenode for project files (full editor state) and .json for game engine export.

Project Files (.talenode)¶

Save¶

Shortcut: Ctrl+S
Menu: File > Save

If the project hasn't been saved before, this opens a "Save As" dialog. Otherwise, it overwrites the existing file.

Save As¶

Menu: File > Save As...

Opens a file dialog to choose a new save location.

Open¶

Shortcut: Ctrl+O
Menu: File > Open...

Opens a file dialog to load a .talenode project file.

New Project¶

Shortcut: Ctrl+N
Menu: File > New

Clears the current graph and starts fresh. A confirmation dialog will appear to prevent accidental data loss — click Yes to proceed or No to cancel.

Auto-Save¶

TaleNode automatically saves your project every 60 seconds if:

The project has been saved at least once (a file path exists)
Changes have been made since the last save

A brief "Auto-saved" message appears in the status bar when auto-save triggers.

What's in a .talenode File?¶

The .talenode format is pretty-printed JSON containing:

{
  "version": "1.0.0",
  "name": "My Dialogue",
  "graph": {
    "nodes": {...},
    "connections": [...],
    "variables": [...],
    "characters": [...],
    "groups": [...]
  }
}

This includes everything: node positions, port data, all connections, variables, characters, groups, and metadata.

When version snapshots exist, they are stored in a separate sidecar file named project.talenode.versions alongside the main .talenode file. This keeps the main file small and diff-friendly.

Note

.talenode files are backward compatible — new fields use #[serde(default)] so older files open in newer versions without issues. Old files with inline versions also load correctly.

Version Control (Git)¶

.talenode files are designed to work well with Git and other version control systems.

Deterministic Serialization¶

TaleNode ensures that saving the same project twice produces byte-identical output:

Sorted keys — Node maps, tags, review statuses, and all keyed data use sorted maps. Keys always appear in the same order regardless of insertion order.
Sorted lists — Connections, variables, characters, groups, comments, quests, world entities, and timelines are sorted by name (or composite key) before saving.
No random shuffling — Two people saving the same graph state get identical JSON, eliminating spurious diffs.

Minimal Diffs¶

When you change a single node, only that node's JSON block changes in the file. This means:

git diff shows exactly what was edited
Merge conflicts are limited to the lines that actually changed
Code review of .talenode changes is practical

Version Snapshots as Sidecar¶

Version history snapshots are saved to a separate .talenode.versions file. This prevents version snapshots (which can be large) from bloating the main file and creating noisy diffs.

You can choose to:

Track both files in Git if you want version history shared across the team
Gitignore the sidecar (*.talenode.versions) if you only want the current graph in version control

Recommended .gitignore¶

# Optional: ignore version snapshots to keep repo lean
*.talenode.versions

Export¶

Export JSON¶

Menu: File > Export JSON...

Opens a file dialog to save a .json file for your game engine. See JSON Export Format for the full specification.

Key differences from the project file:

Aspect	.talenode	Export .json
Node positions	Included	Not included
Connections	Separate list	Baked into `next` fields
Node IDs	UUIDs	Human-readable (`dlg_1`, `choice_2`)
Groups	Included	Not included
Port data	Included	Not included

Export XML¶

Menu: File > Export XML...

Exports the dialogue graph in XML format.

Runtime Plugin Export¶

Menu: File > Export Godot Plugin...
Menu: File > Export Unity Plugin...
Menu: File > Export Unreal Plugin...

Exports a drop-in runtime plugin to the selected game engine project folder. See Plugin Export for details.

Export Voice Script (CSV)¶

Menu: File > Export Voice Script (CSV)...

Exports a CSV file listing all dialogue lines with speaker, text, emotion, and audio clip fields — ready for voice actors.

Export Markdown¶

Menu: File > Export Markdown (.md)...

Exports the dialogue as a readable Markdown document with a characters table, variables table, quest checklists, and the full dialogue flow rendered via BFS traversal. Opens natively in any Markdown viewer, VS Code, or GitHub.

Export Word (RTF)¶

Menu: File > Export Word (.rtf)...

Exports the dialogue as an RTF file that opens natively in Microsoft Word, Google Docs, LibreOffice, and other word processors. Contains the same content as the Markdown export in formatted rich text.

Batch Assign Audio¶

Menu: File > Batch Assign Audio...

Opens the Batch Audio Assignment window for matching audio files to dialogue nodes in bulk.

Click Select Folder and choose a folder containing audio files (.wav, .ogg, .mp3)
TaleNode scans and matches files to dialogue nodes using two strategies:
- By readable ID: e.g., dlg_1.wav matches the first dialogue node
- By speaker + index: e.g., elder_1.wav matches the first dialogue line by "Elder"
Review the match table — matched files show in green, unmatched show "(none)"
Click Apply Matches to assign all matched audio paths to the dialogue nodes

Click Re-scan after adding files to the folder to refresh the match list.

Export Locale CSV¶

Menu: File > Export Locale CSV... (also available from the Localization panel)

Exports all translatable strings and their translations to a CSV file. The CSV includes columns for each defined locale, ready for professional translators. See Localization for details.

Import Locale CSV¶

Menu: File > Import Locale CSV... (also available from the Localization panel)

Imports translations from a CSV file. Matches rows by string key and updates translations for all locales found in the CSV headers.

Import¶

Import from Yarn¶

Menu: File > Import from Yarn...

Imports a Yarn Spinner .yarn file and converts it into a TaleNode dialogue graph.

Import from Chat Mapper¶

Menu: File > Import from Chat Mapper...

Imports a Chat Mapper JSON file.

Import from articy¶

Menu: File > Import from articy...

Imports an articy:draft XML export file.

Import from Ink¶

Menu: File > Import from Ink...

Imports an Inkle Ink .ink file. Knots and stitches are converted to nodes, choices become Choice nodes, diverts become connections, and VAR declarations become project variables.

Note

Importing replaces the current graph. The operation supports undo — press Ctrl+Z to revert.

For detailed information on each import format, see Import Formats.

Undo/Redo Memory Management¶

TaleNode uses snapshot-based undo — each edit saves a copy of the full graph. To keep memory usage reasonable on large projects:

The 5 most recent snapshots are kept as full in-memory graphs for instant undo
Older snapshots are automatically compressed to JSON bytes, reducing memory by ~10x
Compressed snapshots are transparently decompressed on demand when you undo far back
Rapid text edits are debounced (300ms minimum interval) to avoid flooding the undo stack

This is automatic — no configuration needed.

Tips¶

Tip

Save your project (Ctrl+S) regularly. Auto-save is a safety net, not a replacement for manual saves.

Tip

Keep your .talenode project files in version control (Git). They're plain JSON with deterministic serialization — diffs show exactly what changed.

Tip

Export JSON only when you're ready to integrate with your game. The .talenode file is your working format.