improvement

plans/cutscene_data_structure.md

@@ -0,0 +1,122 @@
+# 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