initial

cutscene_system_design.md

@@ -0,0 +1,116 @@
+# Cutscene System Design for 2D Point-and-Click Adventure Game
+
+## Overview
+This document outlines the design for a flexible cutscene system in Godot 4.3. The system will manage actions that occur in sequence or in parallel, with support for time-based actions like character movement.
+
+## Core Architecture
+
+### 1. CutsceneManager
+The main orchestrator that manages the execution of cutscene actions.
+
+```gdscript
+# Core responsibilities:
+# - Managing the action queue
+# - Handling sequential and parallel execution
+# - Tracking action completion
+# - Providing an interface for starting/stopping cutscenes
+```
+
+### 2. Base Action Class
+An abstract base class that all actions will inherit from.
+
+```gdscript
+# Core responsibilities:
+# - Defining common interface for all actions
+# - Managing action state (pending, running, completed)
+# - Providing start/stop functionality
+# - Handling completion callbacks
+```
+
+### 3. Action Execution System
+Two main execution modes:
+- **Sequential**: Actions execute one after another
+- **Parallel**: Multiple actions execute simultaneously
+
+## Action Types
+
+### Core Action Types
+1. **MoveAction**: Moves a character to a specific position
+2. **DialogueAction**: Displays dialogue text
+3. **AnimationAction**: Plays a specific animation
+4. **TurnAction**: Makes a character turn to face a direction or another character
+5. **WaitAction**: Pauses execution for a specified time
+
+### Extensible Design
+The system will be designed to easily add new action types by inheriting from the base Action class.
+
+## Implementation Details
+
+### Action State Management
+Each action will have these states:
+- `PENDING`: Action is waiting to be executed
+- `RUNNING`: Action is currently executing
+- `COMPLETED`: Action has finished executing
+
+### Completion System
+Actions will use Godot's signal system to notify when they're completed:
+- Each action emits a `completed` signal when finished
+- The CutsceneManager listens for these signals to determine when to proceed
+
+### Parallel Execution
+For parallel actions:
+- Multiple actions start at the same time
+- The CutsceneManager waits for all actions to complete before proceeding
+- Uses a counter to track how many parallel actions are still running
+
+## Example Usage
+
+The system should support scripts like this:
+
+```gdscript
+# Create a cutscene
+var cutscene = CutsceneManager.new()
+
+# Add sequential actions
+cutscene.add_action(MoveAction.new(character1, Vector2(234, 591)))
+cutscene.add_action(DialogueAction.new(character1, "Hello there!"))
+
+# Add parallel actions
+var parallel_group = [
+    MoveAction.new(character1, Vector2(234, 591)),
+    MoveAction.new(character2, Vector2(912, 235))
+]
+cutscene.add_parallel_actions(parallel_group)
+
+# Add more sequential actions
+cutscene.add_action(TurnAction.new(character2, character1))
+cutscene.add_action(DialogueAction.new(character2, "Nice to meet you!"))
+cutscene.add_action(AnimationAction.new(character1, "shocked"))
+
+# Start the cutscene
+cutscene.start()
+```
+
+## File Structure
+```
+/cutscene/
+  ├── CutsceneManager.gd
+  ├── actions/
+  │   ├── Action.gd (base class)
+  │   ├── MoveAction.gd
+  │   ├── DialogueAction.gd
+  │   ├── AnimationAction.gd
+  │   ├── TurnAction.gd
+  │   └── WaitAction.gd
+  └── examples/
+      └── sample_cutscene.gd
+```
+
+## Extensibility
+To add new action types:
+1. Create a new class that inherits from `Action.gd`
+2. Implement the required methods (`start()`, `is_completed()`, etc.)
+3. Add any specific logic for the action type
+4. Use in cutscenes like any other action
+
+This design provides a solid foundation for a flexible cutscene system that can handle both sequential and parallel actions while being easily extensible for new action types.