improvement

plans/cutscene_documentation_plan.md

@@ -0,0 +1,196 @@
+# Cutscene System Documentation Plan
+
+## Overview
+
+This document outlines the documentation needed for the updated cutscene editor system that focuses on resource management rather than code generation.
+
+## Documentation Components
+
+### 1. System Architecture Documentation
+
+**File**: `addons/cutscene_editor/README.md` (update)
+**Content**:
+- Overview of the resource-centric approach
+- Explanation of the data flow from editor to runtime
+- Description of the CutsceneResource structure
+- Diagram showing the relationship between components
+
+### 2. CutsceneResource Documentation
+
+**File**: `addons/cutscene_editor/docs/cutscene_resource.md` (new)
+**Content**:
+- Detailed specification of the CutsceneResource data structure
+- Node structure documentation with examples
+- Connection structure documentation with examples
+- Metadata structure explanation
+- Version compatibility information
+
+### 3. Editor Documentation
+
+**File**: `addons/cutscene_editor/docs/editor_usage.md` (new)
+**Content**:
+- How to create and edit cutscenes using the visual editor
+- Node types and their parameters
+- Connection rules and validation
+- Saving and loading cutscenes
+- Export/import functionality
+
+### 4. Runtime Documentation
+
+**File**: `cutscene/README.md` (update)
+**Content**:
+- How to load and execute cutscenes at runtime
+- CutsceneManager usage examples
+- Action system overview
+- Parallel execution explanation
+- Error handling and debugging
+
+### 5. API Reference
+
+**File**: `addons/cutscene_editor/docs/api_reference.md` (new)
+**Content**:
+- CutsceneResource API
+- CutsceneGraphEdit API
+- CutsceneGenerator API
+- Node API
+- Connection API
+
+### 6. Migration Guide
+
+**File**: `addons/cutscene_editor/docs/migration_guide.md` (new)
+**Content**:
+- How to migrate from old format to new format
+- Code changes needed for existing projects
+- Backward compatibility information
+- Troubleshooting common migration issues
+
+## Implementation Plan
+
+### 1. Update Existing Documentation
+
+- Update `addons/cutscene_editor/README.md` to reflect new focus
+- Update `cutscene/README.md` to explain runtime usage
+
+### 2. Create New Documentation Files
+
+- Create `addons/cutscene_editor/docs/cutscene_resource.md`
+- Create `addons/cutscene_editor/docs/editor_usage.md`
+- Create `addons/cutscene_editor/docs/api_reference.md`
+- Create `addons/cutscene_editor/docs/migration_guide.md`
+
+### 3. Add Code Comments
+
+- Ensure all GDScript files have proper documentation comments
+- Add examples in comments where appropriate
+- Document public methods and properties
+
+## Documentation Structure
+
+### Cutscene Resource Documentation
+
+```markdown
+# Cutscene Resource Format
+
+## Overview
+
+The CutsceneResource is a Godot Resource that stores all the data needed to represent and execute a cutscene.
+
+## Data Structure
+
+### Nodes
+
+Nodes represent actions or control points in the cutscene.
+
+[Detailed node structure with examples]
+
+### Connections
+
+Connections represent the flow between nodes.
+
+[Detailed connection structure with examples]
+
+### Metadata
+
+Metadata contains version and timestamp information.
+
+[Metadata structure details]
+```
+
+### Editor Usage Documentation
+
+```markdown
+# Cutscene Editor Usage
+
+## Getting Started
+
+[Installation and setup instructions]
+
+## Creating a New Cutscene
+
+[Step-by-step guide]
+
+## Node Types
+
+[Description of each node type with parameters]
+
+## Connections
+
+[How to create and manage connections]
+
+## Saving and Loading
+
+[How to save and load cutscenes]
+```
+
+### Runtime Documentation
+
+```markdown
+# Runtime Cutscene Execution
+
+## Loading Cutscenes
+
+[How to load a CutsceneResource]
+
+## Executing Cutscenes
+
+[How to use CutsceneManager]
+
+## Custom Actions
+
+[How to create custom action types]
+```
+
+## Visual Documentation
+
+### 1. System Architecture Diagram
+
+```mermaid
+graph TD
+    A[Cutscene Editor] --> B[CutsceneResource]
+    B --> C[CutsceneGenerator]
+    C --> D[CutsceneManager]
+    D --> E[Actions]
+    E --> F[Game Objects]
+```
+
+### 2. Data Flow Diagram
+
+```mermaid
+graph LR
+    A[Editor Nodes] --> B[Resource Nodes]
+    C[Editor Connections] --> D[Resource Connections]
+    B --> E[Runtime Actions]
+    D --> E
+    E --> F[Execution]
+```
+
+## Implementation Timeline
+
+1. Update existing README files
+2. Create cutscene_resource.md
+3. Create editor_usage.md
+4. Create api_reference.md
+5. Create migration_guide.md
+6. Add code comments
+7. Create visual diagrams
+8. Review and finalize documentation