ryan
bf11a5fab5
- Introduced `PHASE_3a_CORE_DIRECTOR.md` detailing the core functionality for directors, including navigation, action queue, UI, waypoint visualization, and action execution. - Implemented `StageDirectorVisuals` for drawing stickman action queues in edit mode, including waypoints and action badges. - Created `SpeechBubble` class for displaying speech bubbles above stickmen, with customizable text and styling.
178 lines
4.3 KiB
Markdown
178 lines
4.3 KiB
Markdown
# 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
|