196 lines
4.3 KiB
Markdown
196 lines
4.3 KiB
Markdown
# 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 |