Alfheim Node Library

TAG Engine (Text Adventure Game Engine) Node Library — Node System Design Document

Overview

Alfheim's story system is built on a Node Graph. Each Episode (story chapter) is described by a node graph, with connections between nodes representing the story flow. Player choices, condition checks, and random events are implemented through different node types.

This document defines all 8 node types in the Node Library, their port rules, data structures, and the topology connection mechanism between Episodes.

---

Architecture: Port-Driven Model

Each node defines its output port layout through type-specific data. StoryBranch uniformly handles wiring between ports.

Plain TextNode-type specific data     →   Output Ports Layout   →   StoryBranch[] (wiring)
(choices, conditions, etc.)      (per-type rules)          (targetNodeId, sourceHandle)

Port rules per node type:

---

Node Types

1. Start Node

Category: Flow Control

Entry point of an Episode. Every Episode must have exactly one Start Node.

• Inputs: 0
• Outputs: 1 (default, always present)
• Constraints: Cannot be deleted. One per Episode.
• Visual: Green (#22c55e), Play icon

Behavior:

• Runtime begins execution at the Start Node
• Connected Episode's Start Node receives inherited global and character variables
• The single output connects to the first content or logic node

Data fields: None (uses base StoryNode fields only).

---

2. End Node

Category: Flow Control

Exit point of an Episode. Marks where the Episode's story flow terminates or transitions to another Episode.

• Inputs: N (any number of nodes can flow into End)
• Outputs: 0–N (one per Episode Link)
• Constraints: At least one per Episode recommended. Cannot be Start-type protected but can be freely created/deleted.
• Visual: Red (#ef4444), Square icon

Behavior:

• When episodeLinks is empty, the node is terminal — the story ends here.
• When episodeLinks has entries, each link generates an output port. These ports connect to other Episodes' Start Nodes.
• Each link can have an optional condition. At runtime, the first link whose condition evaluates to true is taken. If multiple links have no condition, the runtime presents them as choices.

Data fields:

Typescriptinterface EpisodeLink {
  id: string;
  targetEpisodeId: string;    // ID of the Episode to transition to
  label: string;              // Display label (e.g., "Continue to Chapter 2")
  condition: string | null;   // Optional condition expression
}

Variable inheritance on Episode transition:

---

3. Dialogue Node

Category: Content

The core content node. Contains dialogue lines (speaker text) and optional player choices.

• Inputs: 1
• Outputs: 1 (no choices) or N (one per choice)
• Visual: Blue (#3b82f6), MessageSquare icon

Behavior:

• Runtime plays each DialogueLine in order (speaker name, text, emotion, modifiers).
• If choices is empty, the node has a single default output and auto-continues.
• If choices has entries, each choice generates a labeled output port. The player selects a choice, and the flow follows the corresponding output.

Data fields:

Typescriptinterface NodeChoice {
  id: string;
  label: string;                    // Player-visible choice text
  condition: string | null;         // Only show this choice if condition is true
  variableChanges: VariableChange[]; // Execute these changes when selected
}

The DialogueLine[] structure is unchanged. The existing BrancherData modifier within dialogue lines is retained for lightweight inline options that do not affect the node-level flow (e.g., flavor responses, affinity micro-adjustments).

Distinction: NodeChoice vs BrancherData

Example:

Plain Text[Dialogue Node: "The Crossroads"]
  Lines:
    - Narrator: "You arrive at a fork in the road."
    - Narrator: "To the west, a dark forest. To the east, a mountain pass."
  Choices:
    - "Enter the forest"  → connects to ForestNode
    - "Climb the mountain" → connects to MountainNode
    - "Turn back" [condition: courage < 30] → connects to RetreatNode

---

4. Condition Node (If / Elif / Else)

Category: Logic

Evaluates variable conditions and routes flow to the first matching branch.

• Inputs: 1
• Outputs: N + 1 (one per condition arm, plus one Else)
• Visual: Amber (#f59e0b), GitBranch icon

Behavior:

• Condition arms are evaluated in order (top to bottom).
• The first arm whose expression evaluates to true is taken.
• If no arm matches, the Else output is taken.
• The Else port is always present and cannot be removed.

Data fields:

Typescriptinterface ConditionArm {
  id: string;
  label: string;      // Display label (e.g., "High Trust")
  expression: string;  // Condition expression (e.g., "trust >= 80")
}

Expression language:

Conditions use a simple expression syntax:

• Comparison: variable > value, variable == value, variable != value, variable >= value, variable <= value
• Boolean: flag == true, flag == false
• String: name == "Alice"
• Logical operators: &&, ||, !
• Grouping: (trust >= 50) && (visited_cave == true)

Example:

Plain Text[Condition Node: "Check Trust Level"]
  Arms:
    - "High trust"    [trust >= 80]  → connects to TrustPath
    - "Medium trust"  [trust >= 40]  → connects to NeutralPath
    - Else                           → connects to SuspicionPath

---

5. Random Node

Category: Logic

Randomly selects one output based on weighted probability.

• Inputs: 1
• Outputs: N (one per random output)
• Visual: Purple (#8b5cf6), Shuffle icon

Behavior:

• At runtime, one output is selected randomly.
• Weights are relative: a weight of 3 is three times as likely as a weight of 1.
• If all weights are equal, selection is uniform.

Data fields:

Typescriptinterface RandomOutput {
  id: string;
  label: string;   // Display label (e.g., "Find treasure")
  weight: number;  // Relative probability weight (positive number)
}

Example:

Plain Text[Random Node: "Forest Encounter"]
  Outputs:
    - "Meet a merchant"  [weight: 3]  → connects to MerchantNode
    - "Ambushed by wolves" [weight: 2] → connects to WolfNode
    - "Find hidden ruins"  [weight: 1] → connects to RuinsNode

Probabilities: Merchant 50%, Wolves 33.3%, Ruins 16.7%.

---

6. SetVariable Node

Category: Action

Sets or modifies one or more variables. Useful for tracking game state changes that happen outside of dialogue choices.

• Inputs: 1
• Outputs: 1 (default)
• Visual: Cyan (#06b6d4), Variable icon

Behavior:

• All assignments execute atomically when the node is entered.
• Flow immediately continues to the output.

Data fields:

Typescripttype AssignmentOperation = "set" | "add" | "subtract" | "multiply" | "toggle";

interface VariableAssignment {
  id: string;
  variableId: string;               // Target variable ID
  scope: VariableScope;             // "global" | "episode" | "character"
  characterId: string | null;       // Required when scope is "character"
  operation: AssignmentOperation;
  expression: string;               // Value or expression
}

Operations:

Example:

Plain Text[SetVariable Node: "Gain Reward"]
  Assignments:
    - gold [global]      set  += 100
    - trust [character: Alice]  add  += 20
    - visited_cave [episode]  set  = true

---

7. Event Node

Category: Action

Triggers game events such as playing music, showing images, or unlocking achievements.

• Inputs: 1
• Outputs: 1 (default)
• Visual: Pink (#ec4899), Zap icon

Behavior:

• All event actions execute when the node is entered.
• Events are fire-and-forget unless the runtime implements blocking behavior.
• Flow immediately continues to the output.

Data fields:

Typescriptinterface EventAction {
  id: string;
  eventType: string;                // Event identifier
  params: Record<string, string>;   // Key-value parameters
}

Built-in event types:

Example:

Plain Text[Event Node: "Enter the Cave"]
  Actions:
    - play_bgm { track: "audio/bgm/cave_theme.ogg" }
    - screen_effect { effect: "fade_black", duration: "0.5" }

---

8. Comment Node

Category: Utility

Developer-only annotation node. Does not participate in the story flow.

• Inputs: 0
• Outputs: 0
• Visual: Gray (#6b7280), MessageCircle icon

Behavior:

• Completely ignored at runtime.
• Can be placed anywhere on the canvas as a note for the development team.
• Uses the note field on StoryNode for content.

---

Episode Topology

Inter-Episode Connections

Episodes are connected through End Node episodeLinks. Each link references another Episode by ID and optionally specifies a condition.

Plain TextEpisode 1 (Prologue)                    Episode 2A (Forest Path)
┌─────────────────────────┐             ┌─────────────────────────┐
│ Start → ... → End       │──"Forest"──▷│ Start → ... → End       │
│                         │             └─────────────────────────┘
│                         │
│                         │             Episode 2B (Cave Path)
│                         │             ┌─────────────────────────┐
│                         │──"Cave"────▷│ Start → ... → End       │
└─────────────────────────┘             └─────────────────────────┘

Connection Rules

1. An End Node can have 0 to N episode links (terminal or branching).
2. Each link targets exactly one Episode.
3. Multiple End Nodes in one Episode can link to different Episodes.
4. Circular connections are allowed (e.g., Episode A → Episode B → Episode A) for looping story structures.
5. An Episode can be the target of links from multiple Episodes (convergence).

Variable Inheritance

When transitioning between Episodes:

• Global variables carry over with their current values.
• Character variables carry over with their current values.
• Episode variables reset to their defined default values.

The target Episode's Start Node begins execution with the inherited variable state.

Yggdrasil Tree View

The Yggdrasil panel provides two views for episode organization:

Timeline View (existing): Chronological timeline with calendar entries linking to Episodes.

Tree View (new): A node graph at the Episode level.

• Each Episode renders as a super-node showing name, description, and character thumbnails.
• Edges between Episodes are derived from End Node episodeLinks across all Episodes.
• The tree view is read-only visualization (editing happens within each Episode's Planner).
• Layout is auto-computed or manually adjustable.

---

StoryBranch Wiring

The StoryBranch array on each StoryNode stores the actual wiring — which output port connects to which target node.

Typescriptinterface StoryBranch {
  id: string;
  targetNodeId: string;
  label: string;
  condition: string | null;
}

How ports map to branches:

For nodes with dynamic outputs (dialogue with choices, condition, random), the branch sourceHandle in the ReactFlow edge encodes which output port the branch originates from:

---

Data Model Summary

TypeScript (editor/src/types/story.ts)

Typescriptexport type NodeType =
  | "start"
  | "end"
  | "dialogue"
  | "condition"
  | "random"
  | "setVariable"
  | "event"
  | "comment";

export interface NodeChoice {
  id: string;
  label: string;
  condition: string | null;
  variableChanges: VariableChange[];
}

export interface ConditionArm {
  id: string;
  label: string;
  expression: string;
}

export interface RandomOutput {
  id: string;
  label: string;
  weight: number;
}

export type AssignmentOperation = "set" | "add" | "subtract" | "multiply" | "toggle";

export interface VariableAssignment {
  id: string;
  variableId: string;
  scope: VariableScope;
  characterId: string | null;
  operation: AssignmentOperation;
  expression: string;
}

export interface EventAction {
  id: string;
  eventType: string;
  params: Record<string, string>;
}

export interface EpisodeLink {
  id: string;
  targetEpisodeId: string;
  label: string;
  condition: string | null;
}

export interface StoryNode {
  id: string;
  title: string;
  nodeType: NodeType;
  position: NodePosition;
  branches: StoryBranch[];

  // Content (Dialogue Node)
  dialogueLines: DialogueLine[];
  choices?: NodeChoice[];

  // Logic (Condition Node)
  conditionArms?: ConditionArm[];

  // Logic (Random Node)
  randomOutputs?: RandomOutput[];

  // Action (SetVariable Node)
  assignments?: VariableAssignment[];

  // Action (Event Node)
  eventActions?: EventAction[];

  // Flow (End Node)
  episodeLinks?: EpisodeLink[];

  // Common fields
  note: string;
  folderId: string | null;
  metadata: Record<string, string>;
  sceneTemplateId?: string | null;
  slotAssignments?: Record<string, string>;
  enterConditions?: NodeCondition[];
  variableActions?: VariableActionEntry[];
}

Visual Config