# 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.