CutsceneManager Design

Overview

The CutsceneManager is the central orchestrator for executing cutscenes. It manages both sequential and parallel actions, tracks their completion, and controls the flow of the cutscene.

Class Structure

class_name CutsceneManager
extends Node

# Action queues
var sequential_actions: Array  # Actions that run one after another
var current_action: Action     # The action currently being executed
var action_index: int = 0      # Index of the next sequential action

# Parallel actions
var parallel_actions: Array    # Groups of actions running simultaneously
var active_parallel_groups: Array  # Currently running parallel action groups

# State management
enum State {
    IDLE,       # Not running any cutscene
    RUNNING,    # Currently executing a cutscene
    PAUSED      # Cutscene is paused
}

var state: int = State.IDLE
var is_active: bool = false

# Signals
signal cutscene_started()
signal cutscene_completed()
signal cutscene_paused()
signal cutscene_resumed()
signal action_started(action)
signal action_completed(action)

# Public methods
func start() -> void:
    # Start executing the cutscene
    pass

func pause() -> void:
    # Pause the current cutscene
    pass

func resume() -> void:
    # Resume a paused cutscene
    pass

func stop() -> void:
    # Stop the current cutscene and reset
    pass

func add_action(action: Action) -> void:
    # Add a single action to the sequential queue
    pass

func add_parallel_actions(actions: Array) -> void:
    # Add a group of actions to run in parallel
    pass

# Internal methods
func _process(delta: float) -> void:
    # Main update loop
    pass

func _execute_next_action() -> void:
    # Start executing the next sequential action
    pass

func _check_parallel_groups() -> void:
    # Check if any parallel action groups have completed
    pass

func _on_action_completed(action: Action) -> void:
    # Handle action completion
    pass

func _reset() -> void:
    # Reset the manager to initial state
    pass

Sequential Execution System

The sequential execution system runs actions one after another:

Actions are added to the sequential_actions queue
When the cutscene starts, the first action is executed
When an action completes, the next one in the queue is started
The cutscene completes when all sequential actions are finished

# Example flow:
# 1. Add actions: [MoveAction, DialogueAction, AnimationAction]
# 2. Start cutscene
# 3. MoveAction starts and runs
# 4. When MoveAction completes, DialogueAction starts
# 5. When DialogueAction completes, AnimationAction starts
# 6. When AnimationAction completes, cutscene ends

Parallel Execution System

The parallel execution system runs multiple actions simultaneously:

Groups of actions are added as parallel groups
All actions in a group start at the same time
The manager waits for all actions in the group to complete
When all actions in a group complete, the next sequential action can proceed

# Example flow:
# 1. Add sequential action: MoveAction (character1)
# 2. Add parallel group: [MoveAction (character2), MoveAction (character3)]
# 3. Add sequential action: DialogueAction
# 
# Execution:
# 1. MoveAction (character1) runs and completes
# 2. Both MoveAction (character2) and MoveAction (character3) start simultaneously
# 3. When both complete, DialogueAction starts
# 4. When DialogueAction completes, cutscene ends

Action Group Management

Parallel actions are managed in groups:

# Structure for parallel action groups:
{
    "actions": [Action, Action, ...],  # The actions in this group
    "completed_count": 0,              # How many actions have completed
    "total_count": 0                   # Total number of actions in group
}

State Transitions

The CutsceneManager has these states:

IDLE: Not running any cutscene
RUNNING: Executing a cutscene
PAUSED: Cutscene is temporarily paused

State transitions:

IDLE → RUNNING: When start() is called
RUNNING → PAUSED: When pause() is called
PAUSED → RUNNING: When resume() is called
RUNNING → IDLE: When cutscene completes or stop() is called
PAUSED → IDLE: When stop() is called

Error Handling

The manager should handle these error cases:

Attempting to start a cutscene that's already running
Adding actions while a cutscene is running
Actions that fail during execution
Empty action queues

Integration with Godot Engine

The CutsceneManager should:

Inherit from Node to be added to the scene tree
Use _process() for frame-based updates
Connect to action signals for completion notifications
Be easily instantiated and configured in the editor or via code

This design provides a robust foundation for managing complex cutscene sequences with both sequential and parallel execution patterns.

4.8 KiB Raw Blame History