# 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:**

```gdscript
{ "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