Extensions / Plugin API

TaleNode supports a plugin system for custom export and import formats. Create a plugin directory with a manifest file and a template, and TaleNode will discover and run it.

Overview

Plugins are directories containing a plugin.json manifest and an entry point file (usually a template). TaleNode discovers plugins from two locations:

1. Global: ~/.talenode/plugins/ (or platform-equivalent config directory)
2. Project-local: ./plugins/ (relative to the current working directory)

Managing Plugins

Open the Extensions panel via View > Extensions in the menu bar. The panel appears as a dockable tab.

Panel Controls

Button	Description
Refresh	Re-scan plugin directories for new/changed plugins
Open Plugins Folder	Shows the global plugins folder path

Plugin List

Each discovered plugin shows:

• Name and Version from the manifest
• Author if specified
• Description if specified
• Type badge: Export, Import, or Export + Import
• Run Export / Run Import buttons (based on plugin type)

Creating a Plugin

Directory Structure

~/.talenode/plugins/
  my-plugin/
    plugin.json       # Manifest (required)
    template.txt      # Entry point file

Manifest Format

Create a plugin.json file:

{
  "id": "my-custom-format",
  "name": "My Custom Format",
  "version": "1.0",
  "author": "Your Name",
  "description": "Exports dialogue in my custom format",
  "plugin_type": "Export",
  "entry_point": "template.txt"
}

Field	Required	Description
id	Yes	Unique plugin identifier
name	Yes	Display name in the Extensions panel
version	No	Version string
author	No	Plugin author name
description	No	Short description
plugin_type	No	"Export", "Import", or "ExportImport" (default: "Export")
entry_point	No	Filename of the template/entry file

Plugin Types

Type	Capabilities
Export	Can export the current graph to a custom format
Import	Can import a file into the current graph
ExportImport	Can do both

Export Plugins

Export plugins use template substitution. TaleNode reads the entry point file and replaces placeholders with graph data.

Available Placeholders

Placeholder	Replaced With
{{json}}	Full JSON export of the dialogue graph (same as File > Export JSON)
{{name}}	Project name
{{version}}	Plugin version string

Example Template

template.txt:

# Generated by {{name}} v{{version}}
# Dialogue data:

{{json}}

When you click Run Export, TaleNode:

1. Reads the template file
2. Exports the graph to JSON
3. Substitutes all placeholders
4. Opens a file save dialog
5. Writes the result to the chosen file

Advanced Example — Lua Table

-- Dialogue: {{name}}
-- Generated with plugin v{{version}}

local dialogue_data = load_json([[
{{json}}
]])

return dialogue_data

Import Plugins

Import plugins attempt to parse the selected file as a JSON DialogueGraph. This is useful for re-importing TaleNode project files or JSON data from other tools.

When you click Run Import, TaleNode:

1. Opens a file picker dialog
2. Reads the selected file
3. Parses it as a JSON DialogueGraph
4. Creates an undo snapshot
5. Replaces the current graph with the imported data

Status Messages

The Extensions panel shows colored status messages:

• Green: Success (e.g., "Exported to /path/to/file.txt")
• Red: Error (e.g., "Cannot read template", "Import parse error")

Tips

Tip

Start simple — a template with just {{json}} wrapped in your format's header/footer is often enough for a useful export plugin.

Tip

Share plugins with your team by placing them in the project's plugins/ directory. They'll be discovered automatically.

Tip

Use the plugin id to name your exported files. TaleNode suggests {id}_export.txt as the default filename.

Tip

For complex import logic, pre-process your data into TaleNode's JSON format externally, then use an Import plugin to load it.