initial

action_class_design.md

@@ -0,0 +1,116 @@
+# Base Action Class Design
+
+## Overview
+The `Action` class is the abstract base class for all cutscene actions. It defines the common interface and functionality that all actions must implement.
+
+## Class Structure
+
+```gdscript
+class_name Action
+extends RefCounted
+
+# Action states
+enum State {
+    PENDING,    # Action is waiting to be executed
+    RUNNING,    # Action is currently executing
+    COMPLETED   # Action has finished executing
+}
+
+# Public properties
+var state: int = State.PENDING
+var name: String = "Action"
+
+# Signals
+signal started()        # Emitted when action starts
+signal completed()      # Emitted when action completes
+signal failed(error)    # Emitted if action fails
+
+# Virtual methods to be implemented by subclasses
+func start() -> void:
+    # Start executing the action
+    # This method should be overridden by subclasses
+    pass
+
+func update(delta: float) -> void:
+    # Update the action (called every frame while running)
+    # This method can be overridden by subclasses
+    pass
+
+func is_completed() -> bool:
+    # Check if the action has completed
+    # This method should be overridden by subclasses
+    return state == State.COMPLETED
+
+func stop() -> void:
+    # Stop the action (if it's running)
+    # This method can be overridden by subclasses
+    pass
+
+# Helper methods
+func _set_running() -> void:
+    # Set the action state to RUNNING and emit started signal
+    state = State.RUNNING
+    started.emit()
+
+func _set_completed() -> void:
+    # Set the action state to COMPLETED and emit completed signal
+    state = State.COMPLETED
+    completed.emit()
+
+func _set_failed(error_message: String) -> void:
+    # Set the action state to FAILED and emit failed signal
+    state = State.FAILED
+    failed.emit(error_message)
+```
+
+## Implementation Guidelines
+
+### Required Methods
+All action subclasses must implement these methods:
+
+1. `start()` - Initialize and begin the action
+2. `is_completed()` - Return true when the action is finished
+3. `update(delta)` - Optional, for frame-based updates
+
+### State Management
+Actions should properly manage their state:
+- Start in `PENDING` state
+- Move to `RUNNING` when `start()` is called
+- Move to `COMPLETED` when finished
+- Emit appropriate signals for state changes
+
+### Signal Usage
+Actions should emit these signals:
+- `started()` when the action begins
+- `completed()` when the action finishes successfully
+- `failed(error)` when the action encounters an error
+
+## Example Implementation
+
+```gdscript
+# Example of a simple WaitAction implementation
+class_name WaitAction
+extends Action
+
+var duration: float
+var elapsed_time: float = 0.0
+
+func _init(wait_duration: float):
+    duration = wait_duration
+    name = "WaitAction"
+
+func start() -> void:
+    ._set_running()
+    elapsed_time = 0.0
+
+func update(delta: float) -> void:
+    if state == State.RUNNING:
+        elapsed_time += delta
+        if elapsed_time >= duration:
+            ._set_completed()
+
+func is_completed() -> bool:
+    return state == State.COMPLETED
+```
+
+This design provides a solid foundation for all action types while maintaining flexibility for different implementation needs.