experiment-adventure-ai/cutscene_system_design.md

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.

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

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

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