150 lines
4.3 KiB
Markdown
Executable File
150 lines
4.3 KiB
Markdown
Executable File
# Cutscene System for Godot 4.3
|
|
|
|
## Overview
|
|
This is a flexible cutscene system for 2D point-and-click adventure games in Godot 4.3. It supports both sequential and parallel action execution, with a focus on extensibility and dynamic behavior. The system can be used directly with code or with the visual Cutscene Editor plugin that manages cutscene resources.
|
|
|
|
## Features
|
|
- Sequential action execution
|
|
- Parallel action execution
|
|
- Extensible action system
|
|
- Signal-based completion system
|
|
- Error handling and recovery
|
|
- Resource-based cutscene management (with Cutscene Editor plugin)
|
|
|
|
## System Components
|
|
|
|
### Core Classes
|
|
- `Action`: Base class for all actions
|
|
- `CutsceneManager`: Orchestrates action execution
|
|
|
|
### Action Types
|
|
- `MoveAction`: Move characters to specific positions
|
|
- `TurnAction`: Rotate characters to face targets
|
|
- `DialogueAction`: Display dialogue text
|
|
- `AnimationAction`: Play character animations
|
|
- `WaitAction`: Time-based delays
|
|
|
|
## Usage
|
|
|
|
### Basic Setup (Code-based)
|
|
```gdscript
|
|
# Create a cutscene manager
|
|
var cutscene_manager = CutsceneManager.new()
|
|
add_child(cutscene_manager)
|
|
|
|
# Add sequential actions
|
|
cutscene_manager.add_action(MoveAction.new(character, Vector2(100, 100)))
|
|
cutscene_manager.add_action(DialogueAction.new(character, "Hello, world!"))
|
|
|
|
# Start the cutscene
|
|
cutscene_manager.start()
|
|
```
|
|
|
|
### Parallel Actions (Code-based)
|
|
```gdscript
|
|
# Create parallel actions
|
|
var parallel_actions = [
|
|
MoveAction.new(character1, Vector2(200, 200)),
|
|
MoveAction.new(character2, Vector2(300, 300))
|
|
]
|
|
cutscene_manager.add_parallel_actions(parallel_actions)
|
|
```
|
|
|
|
### Resource-based Setup (With Cutscene Editor)
|
|
```gdscript
|
|
# Load a cutscene resource created with the visual editor
|
|
var cutscene_resource = preload("res://path/to/your/cutscene.tscn")
|
|
|
|
# Generate actions from the resource
|
|
var generator = CutsceneGenerator.new()
|
|
var cutscene_manager = generator.generate_cutscene(cutscene_resource)
|
|
|
|
# Add to scene and start
|
|
add_child(cutscene_manager)
|
|
cutscene_manager.start()
|
|
```
|
|
|
|
### The Example Scenario
|
|
The system supports complex sequences like the one described in the requirements:
|
|
|
|
```gdscript
|
|
# 1. Character1 moves to 234, 591
|
|
# 2. At the same time Character2 moves to 912, 235
|
|
# 3. When both arrive, character2 turns to character1
|
|
# 4. Character2 says a dialogue line to character1
|
|
# 5. A special animation (shocked) is played for character1
|
|
|
|
var cutscene = CutsceneManager.new()
|
|
add_child(cutscene)
|
|
|
|
# Add parallel movements
|
|
var moves = [
|
|
MoveAction.new(character1, Vector2(234, 591)),
|
|
MoveAction.new(character2, Vector2(912, 235))
|
|
]
|
|
cutscene.add_parallel_actions(moves)
|
|
|
|
// Add sequential actions
|
|
cutscene.add_action(TurnAction.new(character2, character1))
|
|
cutscene.add_action(DialogueAction.new(character2, "Hello there!"))
|
|
cutscene.add_action(AnimationAction.new(character1, "shocked"))
|
|
|
|
cutscene.start()
|
|
```
|
|
|
|
## Extending the System
|
|
|
|
### Creating New Action Types
|
|
1. Create a new class that extends `Action`
|
|
2. Implement the required methods:
|
|
- `start()`: Initialize and begin the action
|
|
- `update(delta)`: Update the action each frame (optional)
|
|
- `is_completed()`: Return true when the action is finished
|
|
3. Use the action in cutscenes like any other
|
|
|
|
```gdscript
|
|
class_name CustomAction
|
|
extends "res://cutscene/Action.gd"
|
|
|
|
func _init(custom_parameter):
|
|
# Initialize custom properties
|
|
pass
|
|
|
|
func start() -> void:
|
|
# Start the action
|
|
._set_running()
|
|
|
|
func update(delta: float) -> void:
|
|
# Update the action each frame
|
|
pass
|
|
|
|
func is_completed() -> bool:
|
|
# Return true when the action is completed
|
|
return state == State.COMPLETED
|
|
```
|
|
|
|
## File Structure
|
|
```
|
|
/cutscene/
|
|
├── Action.gd
|
|
├── CutsceneManager.gd
|
|
├── actions/
|
|
│ ├── MoveAction.gd
|
|
│ ├── TurnAction.gd
|
|
│ ├── DialogueAction.gd
|
|
│ ├── AnimationAction.gd
|
|
│ └── WaitAction.gd
|
|
├── examples/
|
|
│ ├── sample_cutscene.tscn
|
|
│ ├── sample_cutscene.gd
|
|
│ ├── animated_character.tscn
|
|
│ └── animated_character.gd
|
|
└── tests/
|
|
└── test_cutscene_system.gd
|
|
```
|
|
|
|
## Testing
|
|
Run the test script at `cutscene/tests/test_cutscene_system.gd` to verify the system is working correctly.
|
|
|
|
## License
|
|
This cutscene system is provided as-is for educational and prototyping purposes. |