experiment-adventure-ai/plans/cutscene_resource_analysis.md

Cutscene Editor Architecture Analysis

Current System Overview

The current cutscene editor addon consists of several key components:

1. Editor Components (in addons/cutscene_editor/editor/):

   • CutsceneGraphEdit.gd: Main graph editor interface that manages nodes and connections
   • CutsceneResource.gd: Resource for storing cutscene data (nodes, connections)
   • CutsceneGenerator.gd: System for generating executable cutscene code from graph data
   • Node implementations (MoveActionNode, DialogueActionNode, etc.)

2. Runtime Components (in cutscene/):

   • CutsceneManager.gd: Manages execution of cutscene actions
   • Action.gd: Base class for all actions
   • Specific action implementations (MoveAction, DialogueAction, etc.)

Current Data Flow

1. User creates nodes in the graph editor
2. Node data is stored in CutsceneResource
3. CutsceneGenerator can convert the resource to:
   • GDScript code (current approach, not desired)
   • JSON (potential future approach)
   • Direct instantiation of runtime actions (desired approach)

Issues with Current Approach

1. The addon currently focuses on generating GDScript code rather than managing a clean data structure
2. The CutsceneResource exists but isn't fully utilized as the primary data structure
3. There's a disconnect between the editor representation and runtime execution

Requirements for New System

1. Resource-Centric Design: The cutscene resource should be the primary data structure that both editor and runtime use
2. Clean Data Structure: Store nodes and edges between slots in a structured way that can be easily serialized/deserialized
3. Runtime Compatibility: The resource should contain all information needed for the runtime CutsceneManager to execute actions
4. No Code Generation: Eliminate the GDScript generation functionality
5. Extensibility: Easy to add new node types and action types

Proposed Data Structure

The cutscene resource should store:

1. Nodes:

   • Unique ID
   • Type (entry, exit, move, dialogue, etc.)
   • Position (x, y)
   • Parameters specific to the node type

2. Connections:

   • Source node ID
   • Source port
   • Target node ID
   • Target port

3. Metadata:

   • Version info
   • Creation/modification timestamps

This structure should be directly usable by the runtime system to instantiate and execute actions.