stickman/plans/PHASE_12_LIVE_DIRECTOR.md

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 Tweens (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.