74 lines
5.4 KiB
Markdown
74 lines
5.4 KiB
Markdown
# Architecture Summary: Live Director System
|
|
|
|
The **Live Director System** transitions the sandbox from a static "plan-then-watch" tool into an interactive **Director Loop** ($\text{Play} \leftrightarrow \text{Pause/Direct} \leftrightarrow \text{Resume}$). Users can freeze the simulation mid-flight at any timestamp $t$, inspect current states, append or modify action paths relative to stickmen's live positions, and resume simulation seamlessly.
|
|
|
|
---
|
|
|
|
## 1. Core State & Control Model
|
|
|
|
```
|
|
┌──────────────────────────────────────┐
|
|
│ EDIT Mode (Authored t=0) │
|
|
└──────────────────┬───────────────────┘
|
|
│ Play (from t=0)
|
|
▼
|
|
┌──────────────────────────────────────┐
|
|
│ PLAY Mode (Simulating) │
|
|
└──────────┬────────────────▲──────────┘
|
|
Pause / Direct │ │ Resume Sim
|
|
(Freeze state at t) ▼ │
|
|
┌──────────────────────────────────────┐
|
|
│ DIRECT Mode (Mid-Sim State at t) │
|
|
└──────────────────┬───────────────────┘
|
|
│ Stop / Reset
|
|
▼
|
|
Restores Authored t=0
|
|
|
|
```
|
|
|
|
- **Unified Pause Alias**: Pressing **`Spacebar`**, clicking **`⏸️ Pause`**, or selecting **`🎬 Direct`** while in `PLAY` mode triggers the exact same transition: freezing simulation at timestamp $t$ and opening Direct Mode editing.
|
|
- **Resume**: Pressing **`Spacebar`** or clicking **`▶️ Play`** unfreezes physics and resumes simulation.
|
|
- **Reset**: Clicking **`↺ Reset`** or selecting **`✏️ Edit`** returns the stage and props to $t=0$ authored positions.
|
|
|
|
---
|
|
|
|
## 2. Physics, Timing, & State Freeze Mechanics
|
|
|
|
- **Multi-Part Ragdoll Velocity Caching**: Transitioning to Direct Mode iterates over all **10 individual bone `RigidBody2D` parts** in `StickmanRagdoll` as well as dynamic stage props. Linear and angular velocities are saved to node metadata (`set_meta`), and nodes are set to `freeze = true` (`FREEZE_MODE_KINEMATIC`). Momentum is restored per body upon unfreezing.
|
|
- **Collision Penetration Protection**: Body transforms are recorded on pause and synced via `PhysicsServer2D` prior to waking up physics bodies on resume to prevent force ejection glitches.
|
|
- **Tween & Process Clock Freezing**: Active procedural `Tween`s (`tween.pause()`), speech bubble timers, and runner process clocks freeze during pause.
|
|
|
|
---
|
|
|
|
## 3. UI Chrome & Visual Hierarchy
|
|
|
|
- **Live Timestamp Display (`TimestampBadge`)**:
|
|
- **Location**: Top-right corner of the viewport (`PRESET_TOP_RIGHT`).
|
|
- **Format**: Displays `⏱️ MM:SS.ms` (e.g. `00:04.25`).
|
|
- **Theming**: The display's size and font should be dictated by the **sandbox_theme.json** file.
|
|
- **Lifecycle**: Ticks continuously in `PLAY`, freezes on the exact paused frame in `DIRECT`, and resets to `00:00.00` in `EDIT`.
|
|
|
|
- **Viewport Path Visuals**:
|
|
- **Completed History ($0 \rightarrow t$)**: Displayed in a **faded ghost style (20% alpha / desaturated grey)** or hidden to eliminate clutter.
|
|
- **Pending Futures ($t \rightarrow \infty$)**: Displayed at **100% full opacity** with bright accent vectors originating at the stickman's live feet position ($P_{\text{live}}$) at time $t$.
|
|
|
|
- **Airborne & Ragdoll Spatial Anchoring**:
|
|
- For airborne or ragdolled stickmen, a vertical down-raycast locates the nearest ground point ($P_{\text{ground}}$).
|
|
- A vertical drop-line connects the character to $P_{\text{ground}}$, and new path vectors anchor directly to $P_{\text{ground}}$.
|
|
|
|
---
|
|
|
|
## 4. Action Execution & Edge Case Handling
|
|
|
|
- **Auto-Recovery**: Assigning a `walk_to` movement action to a ragdolled stickman automatically prepends a `recover` action so they stand up from their current location before navigating.
|
|
- **Landing Barrier Compliance**: Actions appended while paused during a landing crouch compression (`LANDING_IMPACT`) stay queued behind `_is_action_queue_blocked()` until landing animation compression completes upon resuming.
|
|
- **Active Action Cancellation**: Editing or deleting an action currently in progress at timestamp $t$ calls `_cancel_current_primary()` on `StickmanActionRunner` to clear active IK paths and speech overlays cleanly.
|
|
- **Ragdoll Hitbox Selection**: Selection clicks in Direct Mode evaluate all child bone collision shapes in `RagdollBodyContainer` to ensure reliable clicking regardless of pose.
|
|
- **Queue Persistence**: Actions added mid-sim ($t > 0$) append sequentially into the stickman's master queue. Resetting to $t=0$ restores stage layout but retains all newly authored queue actions for playback from the start.
|
|
|
|
---
|
|
|
|
## 5. Explicitly Out of Scope
|
|
|
|
- **Stage & Action Undo/Redo (`Ctrl+Z` / `Ctrl+Y`)**: Stage-wide and action queue undo/redo stacks remain explicitly **OUT OF SCOPE** for this implementation phase. Misplaced items or actions are modified or removed manually via viewport gizmos and selection menus.
|