initial

cutscene/README.md

@@ -0,0 +1,135 @@
+# 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.
+
+## Features
+- Sequential action execution
+- Parallel action execution
+- Extensible action system
+- Signal-based completion system
+- Error handling and recovery
+
+## 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
+```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
+```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)
+```
+
+### 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.