stickman/plans/PHASE_3a_CORE_DIRECTOR.md

Phase 3a: Core Director Functionality

1. Overview

Phase 3a enables directors to click a stickman, choose actions from a popup menu, and watch those actions execute in sequence when Play is pressed.

---

2. Milestone 1: Navigation Foundation

Goal: The stickman can walk to a target position on the stage.

Deliverables:

• NavigationAgent2D added as a child of StickmanRig
• walk_to(target: Vector2) method
• is_walking() method
• arrived signal
• walk_speed export variable (default 300)

Test:

1. Place a stickman on the stage.
2. Call stickman.walk_to(Vector2(200, -300)).
3. Stickman walks to the target.

---

3. Milestone 2: Action Queue Data Model

Goal: Store and manage a list of actions per stickman.

Deliverables:

• action_queue: Array[Dictionary] stored in StickmanRig
• queue_action(action: Dictionary)
• clear_queue()
• get_queue()
• remove_action(index: int)
• insert_action(index: int, action: Dictionary)
• queue_size()

Action Types:

{ "type": "walk_to", "target": Vector2, "speed": 300.0 }
{ "type": "speak", "text": "", "duration": 2.0 }
{ "type": "wait", "duration": 1.0 }
{ "type": "ragdoll" }
{ "type": "recover" }

Test:

Manually create a queue: Walk → Wait → Speak.

stickman.get_queue() returns the list.

4. Milestone 3: Director Tool UI

Goal: Click a stickman → popup menu → choose an action.

Deliverables:

• "Direct" tool button in the SandboxStage palette
• Click detection on stickmen in Edit mode
• Action popup menu (Walk To, Speak, Wait, Ragdoll, Recover)
• "Walk To" → click stage → waypoint appears
• "Speak" → text input dialog
• "Wait" → duration input dialog

Popup Options:

• 🚶 Walk To (enter target mode)
• 💬 Speak (open text dialog)
• ⏳ Wait (open duration dialog)
• 💥 Ragdoll (add immediately)
• 🔄 Recover (add immediately)

Test:

• Click "Direct" tool.
• Click a stickman → popup appears.
• Click "Walk To" → click stage → waypoint appears.
• Action is appended to the queue.

5. Milestone 4: Waypoint Visual System

Goal: Show the director's script visually on the stage in Edit mode.

Deliverables:

• Waypoint markers (colored dots at walk targets)
• Dotted lines connecting waypoints in order
• Action icons (speech bubble, clock, ragdoll)
• Order numbers (1, 2, 3…)
• Hide on Play, Show on Edit

Visual Design:

• Waypoint: Blue dot with white outline

• Dotted line: Dashed white line (alpha 0.6)

• Speech icon: Small speech bubble

• Wait icon: Small clock symbol

• Ragdoll icon: Small "X" symbol

Test:

• Direct: Walk → Wait → Speak → Walk.
• Switch to Edit mode.
• Waypoints, dotted lines, icons, and numbers appear in order.

6. Milestone 5: Action Runner

Goal: Execute the action queue in sequence when Play is pressed.

Deliverables:

• start_queue()
• stop_queue()
• is_queue_running()
• action_started signal
• action_finished signal
• queue_finished signal

State Machine:

IDLE → start_queue() → EXECUTING → action completes → next action
                                 → queue empty → emit queue_finished
                                 → stop_queue() → IDLE

Action Execution:

• walk_to → NavigationAgent2D → wait for arrived

• speak → Show speech bubble → wait for duration

• wait → Wait for duration

• ragdoll → set_ragdoll(true) → wait for rest

• recover → request_recovery() → wait for finish

Test:

• Create queue: Walk → Wait 2s → Speak "Hello!" → Walk.

• Press Play.

• Stickman walks → waits → speaks → walks.

• All signals emit at correct times.

7. Acceptance Criteria

• Stickman walks to a target when directed.
• Action queue stores and manages actions.
• Director Tool UI allows action selection via click popup.
• Waypoints and dotted lines visible in Edit mode.
• Action Runner executes queue in Play mode.
• No user input is accepted during Play.
• Multiple stickmen can act simultaneously.

8. File Changes

File Changes

• scripts/stickman_rig.gd Add NavigationAgent2D, action queue, action runner
• scripts/sandbox_stage.gd Add "Direct" tool, click detection, waypoint visualization
• scripts/stage_gizmos.gd Add waypoint markers and dotted line rendering
• scenes/sandbox_stage.tscn Add "Direct" tool button