DYSTEN — Documentation

What is DYSTEN?

DYSTEN is a visual editor for building interactive stories — branching narratives where the reader makes choices, rolls dice, manages an inventory, and shapes the outcome. You build stories as a graph of nodes (scenes) connected by edges (transitions). Conditions and effects make the graph dynamic.

📖

Text Adventure

Branching prose driven by choices and dice rolls. The classic interactive fiction format.

🖼

Graphic Novel

Panel-based storytelling. Each node is an illustrated page; choices branch the art.

🎬

Interactive Movie

Video clips that play per node. The viewer chooses what happens next.

✦

New to interactive fiction? Start with Text Adventure and the Locked Tower template — it gives you a working 6-node story to explore before building your own.

Creating a project

From the Dashboard, click + New Project. You'll configure three things before entering the editor.

Pick a format

Choose Text Adventure, Graphic Novel, or Interactive Movie. This affects what content fields appear on each node. You can change it later in the TopBar.

Name your story and pick a genre

The title appears everywhere — choose something descriptive. The genre auto-populates suggested stat definitions and gear items when you open State Definitions later.

Choose a starting template

Blank — a single placeholder node, nothing pre-wired. Best when you already know your structure.

The Locked Tower — a working 6-node mystery story with stat checks, item gates, and gear. Best for learning how the system fits together.

ℹ

All projects are saved locally in your browser. Use Export JSON regularly to back up your work.

Editor layout

The editor has four zones. Understanding them makes everything faster.

Top Bar

Story title (click to edit), status badge, genre selector, Export button, Play link, and Test Mode button.

Left Sidebar

Searchable list of all nodes. Click a node to select it. Coloured dots indicate node type. Warning/error indicators appear here.

Canvas

The graph. Drag nodes to arrange. Click to select. Use ⚙ Templates to insert pre-wired patterns. Use + Add Node to add bare nodes.

Right Panel

Contextual editor for the selected node. Three tabs: Content, Conditions, and State. Appears when a node is selected.

Overlay panels

Three overlay panels are accessed from the bottom bar:

⚙ State Definitions

Define every stat, flag, counter, and gear item. Source of truth for all player state.

✓ Validation

Live list of errors and warnings. Errors block gameplay; warnings flag potential issues.

▶ Test Mode

Play through your story in a split-screen overlay without leaving the editor.

Nodes

Every moment in your story is a node. There are five node types — choose based on what the moment does.

▣

Scene node_type: "scene"

The workhorse. Contains prose (or media) and one or more actions. Most of your story will be scene nodes.

◌

Placeholder node_type: "placeholder"

An unwritten scene. Use it to map out story structure before writing content. Validation flags these as warnings.

◉

Ending node_type: "ending"

Terminates the story. Mark as success, failure, or neutral. No outgoing edges. Every story needs at least one.

🛒

Shop node_type: "shop"

Presents items for purchase. Players spend a currency stat. Configure items and prices in the Right Panel.

✦

Loot Drop node_type: "loot"

Automatically grants items on arrival. No player choice — items appear in inventory immediately.

Adding & editing nodes

Click + Add Node in the canvas toolbar to open a dropdown of bare node types, or use ⚙ Templates for pre-wired multi-node patterns. Click any node on the canvas to select it and open the Right Panel. To delete a node, select it and click the red trash button at the top of the Right Panel.

⚠

Deleting a node removes all edges connected to it. Actions in other nodes that targeted it will have broken transitions — the Validation panel flags these as missing_target errors.

Connecting nodes

Nodes connect through outcome ports — the amber dots on the right edge of each node. Each port represents one outcome of one action.

Add an action to a scene node

Select the node → Right Panel → Content tab → scroll to Actions → click + Add Action. Give it a label (the button text the player sees).

Add outcomes to the action

Expand the action → click + Add Outcome. Each outcome gets a label (e.g. "Success", "Failure"). A new amber port appears on the node's right edge.

Wire the outcome to a target node

In the outcome's transition settings, pick the target node from the dropdown — or drag directly from the amber port to any node on the canvas.

Read the canvas

Each port shows its outcome label and, in amber, any condition attached to it (e.g. has torch). You can trace the full story path without opening any panel.

✦

Arrange nodes left-to-right following the story timeline — it makes the graph much easier to read as it grows.

Mechanic templates

Templates are pre-wired multi-node patterns. Click ⚙ Templates in the canvas toolbar, pick a template, fill in a few fields, and click Insert Template.

🗝

Item Gate

Requires the player to have a specific item. Branches to a success path (item optionally consumed) or a failure path.

Params: item key, consume toggle

🎲

Stat Check

Rolls a d20 against a difficulty class. Branches to Success or Failure based on the result plus the chosen stat modifier.

Params: stat key, difficulty

⚔

Combat

A fight encounter. Victory and defeat lead to separate paths; defeat applies a health penalty.

Params: health key, difficulty, health loss

🛒

Shop

A pre-wired shop node with a continue action. Configure items for sale in the Right Panel after inserting.

Params: currency key

✦

Loot Drop

A loot node with a continue action. Add item keys to the loot list in the Right Panel after inserting.

Params: scene name

💬

Dialogue Branch

A pure narrative choice with 2–3 options, each routing to its own placeholder node.

Params: 2–3 choice labels

✦

The template picker shows clickable chips from your existing gear and state definitions. Define your stats and gear first, then insert templates.

Writing scenes

Scene content lives in the Right Panel → Content tab when a node is selected.

Content types

text

A prose field. Write the scene description, dialogue, and narration here. Displayed as formatted text in the reader.

image

Provide a URL to an image (JPG, PNG, WebP). Displayed full-width above the action buttons in the reader.

video

Provide a URL to a video file or embed. Plays before the player sees action choices.

Placeholder nodes

A Placeholder node is a reserved spot in your graph with no final content. Use them to map your full story structure before writing any prose, mark scenes you want to return to, and keep the graph connected while content is in draft. To promote a placeholder to a real scene, change its Node Type to scene in the Content tab and write your content.

Naming tips

→Use names that describe the state of the world, not the action: "Cave (Lit)" not "Enter cave with torch"
→Keep names short — they appear on both the canvas node and the left sidebar
→For branching outcomes from the same scene, prefix the name: "Duel — Victory", "Duel — Defeat"

Player state

Player state is every variable you track — health, gold, flags, inventory. Define these in State Definitions (bottom bar). Every key used in a condition or effect must be declared here first.

❤

stat

A numeric value with narrative meaning. Use for health, mana, strength. Displayed as a bar or number in the player sheet.

🚩

flag

A true/false toggle. Use for events that happened: door_opened, quest_complete. Invisible to the player by default.

🪙

counter

A numeric tally used as currency or score. Use for gold, experience, kills.

🎒

inventory

Tracks item keys the player is carrying. Pairs with Gear Definitions for rich display in the player sheet.

Visibility & defaults

Each state key has a visibility setting: visible (shown in player sheet) or hidden (tracked internally, never shown). Enable Visual relevance on a stat to show it prominently (e.g. health bar at the top of the sheet).

Open State Definitions → Defaults to set the player's initial values. Every new session starts from these.

⚠

If you use a key in a condition or effect that isn't declared in State Definitions, the Validation panel will flag it as an undefined_state_key error and gameplay will behave unexpectedly.

Gear & items

Gear definitions describe every physical item in the world — weapons, armour, consumables, key items. Open State Definitions → Gear to manage them.

Key fields

→key — machine-readable identifier used in effects (add_item: torch), conditions (has_item: torch), and loot/shop lists.
→name — the display name shown to the player.
→item_type — weapon, armor, consumable, key_item, or misc. Determines the icon in the player sheet.
→slot — equipment slot (e.g. weapon, armor). Items with the same slot replace each other when equipped.
→stat_bonuses — passive bonuses while equipped. E.g. a sword that adds +3 strength.

Genre presets

In the Gear tab, click Genre Presets to auto-populate suggested stats and gear based on your story's genre. Presets are non-destructive — existing keys are never overwritten.

Actions & rules

Actions are the choices presented to the player. Each action has a rule that decides how the outcome is determined, and a list of outcomes that map results to transitions.

Simple Choice

none

No dice. Outcomes are evaluated in priority order; the first with all conditions passing wins. Use for narrative choices where player agency is the mechanic.

Skill Check

skill_check

Rolls 1d20 + stat modifier vs. a difficulty class (DC). Success if roll ≥ DC. Best for locks, persuasion, acrobatics.

Combat

fight

A fight roll vs. enemy difficulty. Defeat typically applies a health effect. Use the Combat template for a quick setup.

Luck / Dice

probability

A raw dice roll (e.g. 1d20). Each outcome has a min/max range — the roll is matched to the right range. Use for random events.

✦

Use the Stat Check or Combat templates instead of building these from scratch — they pre-wire the rule, outcomes, and range values correctly.

Conditions & effects

Conditions and effects are attached to transitions. Conditions decide if a path is available; effects decide what changes when it's taken.

Conditions

A condition checks a player state key against a value using an operator. Outcomes with conditions are only available when those conditions pass.

has_item: torch

Player has this item in inventory or equipped.

door_opened = true

State key equals (or neq: does not equal) a value.

strength ≥ 12

Numeric key is greater than (or equal to) a value.

health < 20

Numeric key is less than (or equal to) a value.

Add multiple conditions per transition. Set logic mode to ALL (every condition must pass) or ANY (at least one).

Effects

Effects mutate player state the moment a transition is taken. You can stack multiple effects on one transition.

set door_opened = true

Set a flag or stat to an exact value.

increment gold +50

Add to a numeric value.

decrement health -20

Subtract from a numeric value.

add_item: lockpick

Put an item into inventory.

remove_item: torch

Remove an item from inventory (consumed).

equip sword → weapon

Equip an item, removing it from inventory.

Common pattern: item gate

Player must have a torch to enter the dark cave, and the torch is consumed on use:

Outcome A

has_item: torch

→ Cave (Lit) + remove_item: torch

Outcome B

no condition (fallback)

→ Cave (Dark)

Or use the 🗝 Item Gate template — it builds this exact pattern in one click.

Shop & loot nodes

Shop nodes

A Shop node lets players buy items. To configure one:

Add the node

Insert a Shop node via Add Node or the Shop template. The template also wires a "Leave" action automatically.

Define gear items first

Shop items are drawn from your Gear Definitions. Open State Definitions → Gear and make sure your items exist.

Configure shop items

Select the Shop node → Right Panel → Content tab → Shop Items section. Add items: pick the gear key, set a price, and choose the currency key (any stat or counter you've defined, e.g. gold).

Loot drop nodes

A Loot node grants items automatically when the player arrives. No choice is presented — items go straight to inventory. Select the node → Right Panel → Content tab → Loot Items section. Add item keys from your Gear Definitions.

ℹ

Loot and shop items are validated by the Timeline Continuity Checker. If a downstream node checks for an item that can't be obtained on any path leading to it, you'll get an item_never_acquirable warning.

Testing & validation

Test Mode

Click ▶ Test Mode in the TopBar to play through your story in a side panel without leaving the editor. Your node graph stays visible — as you make choices, the currently active node highlights on the canvas. Test Mode is separate from the full Play view — it's faster and keeps your editor context.

Validation panel

Open the Validation panel from the bottom bar to see a live list of issues:

Error

Blocks correct gameplay. Fix before publishing. Examples: missing start node, broken transition target, undefined state key.

Warning

Likely a problem but not always. Examples: placeholder nodes, unreachable nodes, timeline continuity issues.

Info

Suggestions and notices. Reserved for future checks.

Click Jump → on any issue to select the relevant node on the canvas instantly.

Timeline continuity checker

The timeline checker validates that items and flags required by conditions can actually be obtained on some path leading to that node.

🎒

item_never_acquirable

A condition checks for an item that cannot be obtained via loot, shop, or add_item effect on any path that reaches this node.

🚩

state_never_set

A condition checks a boolean flag that is never set to the required value by any effect on any path leading to this node.

✦

These warnings don't mean your story is broken — the path might be intentionally unreachable. But they're worth reviewing to ensure players aren't locked out of content they should be able to access.

Overview

Every DYSTEN story is a single JSON object. This reference covers every field, its type, and whether it is required. Use this when hand-editing exported files or building tools that generate story JSON.

✦

The easiest way to produce valid story JSON is to build your story in the editor and export it. Use this reference to understand what each field means or to make targeted edits.

Import & Export

Minimum required fields for a valid import:

Field	Type	Req	Description
`title`	`string`	✓	Story title — must be non-empty.
`nodes`	`array`	✓	Array of node objects — can be empty but must exist.
`state_definitions`	`array`	✓	Array of state definitions — can be empty.
`status`	`string`	✓	"draft", "published", or "archived".

All other fields are optional on import — missing ones receive safe defaults. The id field is always replaced with a fresh generated ID to avoid collisions.

Story Object

Field	Type	Req	Description
`id`	`string`	✓	Unique identifier. Auto-replaced on import.
`title`	`string`	✓	Display name of the story.
`description`	`string`	—	Short blurb shown on cards and the Discover page.
`status`	`"draft"\|"published"\|"archived"`	✓	Publication state.
`story_format`	`"text"\|"graphic_novel"\|"movie"`	—	Format of the story. Defaults to text.
`genre`	`GenreType`	—	"heroic_fantasy"\|"sci_fi"\|"horror"\|"mystery"\|"modern"\|"western"\|"custom"
`cover_image_url`	`string`	—	URL for the cover image shown on cards.
`monetization_mode`	`"free"\|"paid"\|"freemium"`	✓	Monetization model.
`start_node_id`	`string`	—	ID of the start node. Must match a node in the nodes array.
`nodes`	`StoryNode[]`	✓	All nodes in the story graph.
`state_definitions`	`StateDefinition[]`	✓	All player state keys.
`gear_definitions`	`GearItem[]`	✓	All items that can exist in the world.
`defaults`	`StoryDefaults`	✓	Starting values for all player state.
`created_at`	`ISO 8601`	—	Creation timestamp.
`updated_at`	`ISO 8601`	—	Last modification timestamp.

Nodes

Field	Type	Req	Description
`id`	`string`	✓	Unique node identifier.
`label`	`string`	✓	Human-readable name shown in the editor.
`node_type`	`NodeType`	✓	"scene"\|"placeholder"\|"ending"\|"shop"\|"loot"
`content_type`	`"text"\|"image"\|"video"`	✓	Media type of the scene content.
`content_text`	`string`	—	Prose text for text content type.
`content_media_url`	`string`	—	URL for image or video content types.
`placeholder_summary`	`string`	—	Brief note for placeholder nodes.
`is_start`	`boolean`	✓	True for the starting node only.
`is_ending`	`boolean`	✓	True for ending nodes.
`ending_type`	`"success"\|"failure"\|"neutral"`	—	Required when is_ending is true.
`actions`	`Action[]`	✓	Player choices available at this node.
`shop_items`	`ShopItem[]`	—	Items for sale. Used when node_type is "shop".
`loot_items`	`string[]`	—	Item keys granted on arrival. Used when node_type is "loot".
`position_x`	`number`	✓	X position on the canvas.
`position_y`	`number`	✓	Y position on the canvas.

Node Types

sceneNarrative moment with content and actions.

placeholderUnwritten scene. Flagged by validation.

endingTerminates the story. No outgoing edges.

shopPurchase interface. Requires shop_items.

lootAuto-grants items on arrival. Requires loot_items.

Actions & Outcomes

Action

Field	Type	Req	Description
`id`	`string`	✓	Unique action identifier.
`node_id`	`string`	✓	Parent node ID.
`label`	`string`	✓	Button text shown to the player.
`action_template_type`	`ActionTemplateType`	✓	"simple_choice"\|"risk_luck"\|"skill_check"\|"fight_challenge"\|"advanced"
`display_order`	`number`	✓	Sort order among actions on the same node.
`is_hidden`	`boolean`	✓	Hidden actions are never presented to the player.
`rule`	`Rule`	✓	How the outcome is selected.
`outcomes`	`Outcome[]`	✓	Possible results.

Outcome

Field	Type	Req	Description
`id`	`string`	✓	Unique outcome identifier. Also the canvas port handle ID.
`action_id`	`string`	✓	Parent action ID.
`label`	`string`	✓	Port label on canvas (e.g. "Success", "Failure").
`priority`	`number`	✓	Evaluation order — lower is checked first.
`min_value`	`number`	—	Minimum dice roll to match this outcome.
`max_value`	`number`	—	Maximum dice roll to match this outcome.
`transition`	`Transition`	—	Target node and state changes.

Transition

Field	Type	Req	Description
`id`	`string`	✓	Unique transition identifier.
`source_node_id`	`string`	✓	Origin node.
`outcome_id`	`string`	✓	Parent outcome.
`target_node_id`	`string`	✓	Destination node.
`access_type`	`"free"\|"paid"`	✓	Paid transitions require a purchase.
`condition_group`	`ConditionGroup`	—	Gate conditions for this path.
`effect_group`	`EffectGroup`	—	State mutations applied on take.

Rule Types

rule_type	Extra fields	Req	Description
`none`	—	—	Simple choice. First outcome with all conditions passing wins.
`probability`	`dice_definition`	—	Random roll matched to outcome min/max ranges.
`skill_check`	`skill_key`, `difficulty_level`	—	d20 + modifier vs. DC. easy=8, medium=12, hard=15, very_hard=18.
`fight`	`difficulty_level`	—	Combat roll vs. DC. Defeat typically applies health effects.
`custom`	`custom_expression`	—	Reserved for future scripting.

Conditions

Field	Type	Req	Description
`id`	`string`	✓	Unique condition ID.
`state_key`	`string`	✓	Player state key or item key to check.
`operator`	`ConditionOperator`	✓	eq \| neq \| gt \| gte \| lt \| lte \| has_item
`expected_value`	`string\|number\|boolean`	✓	Value to compare against.

Example

condition_group object"condition_group": {
  "id": "cg_001",
  "logic_mode": "all",
  "conditions": [
    { "id": "c1", "state_key": "torch", "operator": "has_item", "expected_value": true },
    { "id": "c2", "state_key": "health", "operator": "gte", "expected_value": 10 }
  ]
}

Effects

Field	Type	Req	Description
`id`	`string`	✓	Unique effect ID.
`state_key`	`string`	✓	State key or item key to modify.
`operation`	`EffectOperation`	✓	set \| increment \| decrement \| add_item \| remove_item \| equip \| unequip
`value`	`string\|number\|boolean`	✓	Value to apply.

Example

effect_group object"effect_group": {
  "id": "eg_001",
  "effects": [
    { "id": "e1", "state_key": "health", "operation": "decrement", "value": 20 },
    { "id": "e2", "state_key": "gold_key", "operation": "add_item", "value": true }
  ]
}

State Definitions

Field	Type	Req	Description
`id`	`string`	✓	Unique definition ID.
`key`	`string`	✓	Machine-readable key used in conditions and effects.
`state_type`	`"stat"\|"flag"\|"inventory"\|"counter"`	✓	Category of state.
`value_type`	`"integer"\|"boolean"\|"string"`	✓	Data type.
`default_value`	`string\|number\|boolean`	✓	Starting value for new sessions.
`visibility_mode`	`"hidden"\|"visible"`	✓	Whether the player sees this in the character sheet.
`visual_relevance`	`boolean`	✓	If true, shown prominently (e.g. health bar).

Gear Definitions

Field	Type	Req	Description
`id`	`string`	✓	Unique gear ID.
`key`	`string`	✓	Item key used in loot_items, shop_items, effects, and conditions.
`name`	`string`	✓	Display name shown to the player.
`item_type`	`"weapon"\|"armor"\|"consumable"\|"key_item"\|"misc"`	✓	Category for character sheet icon.
`slot`	`string`	—	Equipment slot (e.g. "weapon", "armor"). Items in the same slot replace each other.
`description`	`string`	—	Flavour text in shop and inventory panels.
`stat_bonuses`	`Record<string, number>`	—	Passive bonuses while equipped (e.g. { "strength": 2 }).

Defaults

Field	Type	Req	Description
`starting_stats`	`Record<string, number>`	✓	Initial stat values (e.g. { "health": 100 }).
`starting_flags`	`Record<string, boolean>`	✓	Initial flags (e.g. { "has_map": false }).
`starting_inventory`	`string[]`	✓	Item keys at start (e.g. ["torch", "ration"]).
`starting_counters`	`Record<string, number>`	✓	Initial counters (e.g. { "gold": 50 }).
`starting_equipped`	`Record<string, string>`	✓	Pre-equipped items (e.g. { "weapon": "rusty_dagger" }).

Full Example

A minimal but complete story — one scene, one item gate, two outcomes.

{
  "id": "story_example",
  "title": "The Dark Cave",
  "status": "draft",
  "story_format": "text",
  "genre": "heroic_fantasy",
  "monetization_mode": "free",
  "start_node_id": "node_001",
  "state_definitions": [{
    "id": "sd_001", "key": "health",
    "state_type": "stat", "value_type": "integer",
    "default_value": 100, "visibility_mode": "visible", "visual_relevance": true
  }],
  "gear_definitions": [
    { "id": "gi_001", "key": "torch", "name": "Torch", "item_type": "consumable" }
  ],
  "defaults": {
    "starting_stats": { "health": 100 },
    "starting_flags": {},
    "starting_inventory": ["torch"],
    "starting_counters": {},
    "starting_equipped": {}
  },
  "nodes": [{
    "id": "node_001", "label": "Cave Entrance",
    "node_type": "scene", "content_type": "text",
    "content_text": "You stand at the mouth of a dark cave.",
    "is_start": true, "is_ending": false,
    "position_x": 200, "position_y": 200,
    "actions": [{
      "id": "action_001", "node_id": "node_001",
      "label": "Enter the cave",
      "action_template_type": "simple_choice",
      "display_order": 0, "is_hidden": false,
      "rule": { "id": "rule_001", "action_id": "action_001", "rule_type": "none" },
      "outcomes": [
        {
          "id": "outcome_001", "action_id": "action_001",
          "label": "With torch", "priority": 1,
          "transition": {
            "id": "trans_001", "source_node_id": "node_001",
            "outcome_id": "outcome_001", "target_node_id": "node_002",
            "access_type": "free",
            "condition_group": {
              "id": "cg_001", "logic_mode": "all",
              "conditions": [{ "id": "c1", "state_key": "torch", "operator": "has_item", "expected_value": true }]
            },
            "effect_group": {
              "id": "eg_001",
              "effects": [{ "id": "e1", "state_key": "torch", "operation": "remove_item", "value": true }]
            }
          }
        },
        {
          "id": "outcome_002", "action_id": "action_001",
          "label": "In darkness", "priority": 2,
          "transition": {
            "id": "trans_002", "source_node_id": "node_001",
            "outcome_id": "outcome_002", "target_node_id": "node_003",
            "access_type": "free"
          }
        }
      ]
    }]
  },
  {
    "id": "node_002", "label": "Cave (Lit)",
    "node_type": "placeholder", "content_type": "text",
    "placeholder_summary": "Write the lit cave scene here.",
    "is_start": false, "is_ending": false, "actions": [],
    "position_x": 500, "position_y": 80
  },
  {
    "id": "node_003", "label": "Cave (Dark)",
    "node_type": "placeholder", "content_type": "text",
    "placeholder_summary": "Write the dark cave scene here.",
    "is_start": false, "is_ending": false, "actions": [],
    "position_x": 500, "position_y": 320
  }]
}

Documentation

What is DYSTEN?

Text Adventure

Graphic Novel

Interactive Movie

Creating a project

Editor layout

Overlay panels

Nodes

Adding & editing nodes

Connecting nodes

Mechanic templates

Item Gate

Stat Check

Combat

Shop

Loot Drop

Dialogue Branch

Writing scenes

Content types

Placeholder nodes

Naming tips

Player state

stat

flag

counter

inventory

Visibility & defaults

Gear & items

Key fields

Genre presets

Actions & rules

Conditions & effects

Conditions

Effects

Common pattern: item gate

Shop & loot nodes

Shop nodes

Loot drop nodes

Testing & validation

Test Mode

Validation panel

Timeline continuity checker

Import & export

Exporting

Importing

Sharing with collaborators

Overview

Import & Export

Story Object

Nodes

Node Types

Actions & Outcomes

Action

Outcome

Transition

Rule Types

Conditions

Example

Effects

Example

State Definitions

Gear Definitions

Defaults

Full Example