# 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:

```json
{
  "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