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.

5.4 KiB Raw Permalink Blame History