experiment-adventure-ai/plans/cutscene_resource_implementation.md

CutsceneResource Implementation Plan

Overview

This document describes the changes needed to implement the new CutsceneResource data structure that will properly store nodes and connections for use by both the editor and runtime systems.

Current Issues

The current CutsceneResource.gd has several issues:

1. Uses "name" instead of "id" for node identification
2. Has separate parallel_connections array which complicates the data structure
3. Doesn't follow a consistent data structure for nodes and connections
4. Lacks proper unique ID generation for connections

Proposed Implementation

New Data Structure

The resource will store:

• nodes: Array of node objects with consistent structure
• connections: Array of connection objects with consistent structure
• metadata: Version and timestamp information

Node Structure

Each node will have:

{
  "id": "unique_string_identifier",
  "type": "node_type",
  "position": {
    "x": 100,
    "y": 150
  },
  "parameters": {
    // Type-specific parameters
  }
}

Connection Structure

Each connection will have:

{
  "id": "unique_string_identifier",
  "from_node": "source_node_id",
  "from_port": 0,
  "to_node": "target_node_id",
  "to_port": 0
}

Required Changes to CutsceneResource.gd

1. Update Properties

Replace the current properties with:

@export var nodes: Array = []
@export var connections: Array = []
@export var metadata: Dictionary = {}

2. Update Initialization

In _init():

• Remove parallel_connections initialization
• Update metadata to include version "2.0" to indicate the new structure

3. Update Node Methods

• add_node(): Should generate unique IDs for nodes if not provided
• remove_node(): Should only need to check for "id" field, not "name"
• get_node_by_name(): Should be renamed to get_node_by_id() and check for "id" field

4. Update Connection Methods

• add_connection(): Should generate unique IDs for connections if not provided
• remove_connection(): Should check for connection ID instead of node/port combination
• Remove add_parallel_connection() and remove_parallel_connection() methods
• Remove get_parallel_connections_for_node() method

5. Add Utility Methods

• generate_unique_id(): Helper to generate unique string identifiers
• validate(): Check that all referenced nodes in connections exist
• get_connections_for_node(): Get all connections where node is source or target

6. Update Load/Save Methods

• Ensure that when loading from existing resources, the data structure is converted properly
• When saving, maintain the clean structure

Implementation Steps

1. Create backup of current CutsceneResource.gd
2. Rewrite CutsceneResource.gd with new structure
3. Update references in CutsceneGraphEdit.gd to use new methods
4. Update CutsceneGenerator.gd to work with new structure
5. Test with existing example cutscenes
6. Update documentation

Compatibility Considerations

• Need to maintain backward compatibility with existing cutscene files
• Should provide migration path for existing resources
• Consider adding a version field to distinguish between old and new formats