experiment-adventure-ai/plans/cutscene_data_structure.md

Cutscene Data Structure Design

Overview

This document describes the data structure for storing cutscene nodes and connections in a way that can be used by both the editor and runtime systems.

Node Structure

Each node in the cutscene graph will have the following properties:

Common Properties

• id: Unique identifier for the node (string)
• type: Type of node (entry, exit, move, dialogue, etc.)
• position: Object with x and y coordinates
• parameters: Object containing type-specific parameters

Node Type Specifics

Entry Node

• Type: "entry"
• Parameters: None (or minimal configuration)

Exit Node

• Type: "exit"
• Parameters: None (or minimal configuration)

Move Action Node

• Type: "move"
• Parameters:
  • character: Character identifier/path
  • target_x: Target X position
  • target_y: Target Y position
  • speed: Movement speed

Dialogue Action Node

• Type: "dialogue"
• Parameters:
  • character: Character identifier/path
  • text: Dialogue text
  • duration: Display duration (0 for indefinite)

Animation Action Node

• Type: "animation"
• Parameters:
  • character: Character identifier/path
  • animation_name: Name of animation to play
  • loop: Whether to loop the animation

Turn Action Node

• Type: "turn"
• Parameters:
  • character: Character identifier/path
  • target: Target identifier/path
  • turn_speed: Speed of turning

Wait Action Node

• Type: "wait"
• Parameters:
  • duration: Wait duration in seconds

Parallel Group Node

• Type: "parallel"
• Parameters: None (connections define the group)

Connection Structure

Each connection between nodes will have:

• id: Unique identifier for the connection
• from_node: Source node ID
• from_port: Source port index
• to_node: Target node ID
• to_port: Target port index

Resource Structure

The CutsceneResource will contain:

{
  "version": "1.0",
  "metadata": {
    "created": "timestamp",
    "modified": "timestamp"
  },
  "nodes": [
    {
      "id": "node1",
      "type": "entry",
      "position": {"x": 100, "y": 100},
      "parameters": {}
    },
    {
      "id": "node2",
      "type": "move",
      "position": {"x": 200, "y": 150},
      "parameters": {
        "character": "player",
        "target_x": 300,
        "target_y": 200,
        "speed": 100
      }
    }
  ],
  "connections": [
    {
      "id": "conn1",
      "from_node": "node1",
      "from_port": 0,
      "to_node": "node2",
      "to_port": 0
    }
  ]
}

Implementation Considerations

1. IDs: All nodes and connections should have unique IDs generated by the system
2. Validation: The resource should validate that all referenced nodes in connections exist
3. Serialization: The structure should be easily serializable to JSON for storage
4. Runtime Mapping: The structure should map directly to runtime Action instances