stickman/plans/PHASE_3c_EDITOR.md

# Phase 3c: Editor Tools — Action & Rule Editing

## 1. Overview

Phase 3c adds **full editing capabilities** for both the Director Tool's action queues and the Event System's rules. Currently, directors can only **append** actions and **create/delete** rules. They cannot fix mistakes, change order, or modify existing items. This phase makes the entire script **fully editable**.

The plan combines action editing and rule editing into a single, cohesive implementation with a logical progression from simpler to more complex features.

---

## 2. Core Principles

### 2.1. Extensibility First

The system is built to accommodate future growth:

| Future Addition        | How It's Supported                                        |
| ---------------------- | --------------------------------------------------------- |
| New action types       | Registry pattern — add action template, UI auto-generates |
| New rule trigger types | Registry pattern — add trigger type, UI auto-generates    |
| New action properties  | Action data model is a Dictionary — add new keys freely   |
| New rule properties    | Rule data model is a Dictionary — add new keys freely     |
| New visual styles      | Theme JSON already supports font/color overrides          |

### 2.2. Consistency

The UI patterns for action editing and rule editing are **identical**:

| Pattern      | Action Edition                      | Rule Edition                       |
| ------------ | ----------------------------------- | ---------------------------------- |
| Entry points | Popup menu + Right-click + Waypoint | Rule label + Stickman context menu |
| Panel UI     | Action Queue Panel                  | Rule Panel                         |
| Editor Popup | Action Editor                       | Rule Editor                        |
| Controls     | [✎] Edit, [✕] Delete, [≡] Reorder   | Same                               |
| Drag handles | Reorder actions                     | Reorder rules                      |

---

## 3. Implementation Order

The plan is organized into **5 phases**, each building on the previous:

| Phase          | Focus                     | Deliverables                                 |
| -------------- | ------------------------- | -------------------------------------------- |
| **Phase 3c.1** | **Foundation**            | Shared UI components, extensible data models |
| **Phase 3c.2** | **Action Queue Panel**    | View, edit, delete, reorder actions          |
| **Phase 3c.3** | **Action Visual Editing** | Waypoint context menu, visual walk editing   |
| **Phase 3c.4** | **Rule Panel**            | View, edit, delete, reorder rules            |
| **Phase 3c.5** | **Rule Visual Editing**   | Rule label click, waypoint trigger editing   |

---

## 4. Phase 3c.1: Foundation

### 4.1. Extensible Action Registry

The action system should be registry-driven to support future action types:

```gdscript

# action_registry.gd (NEW)
const ACTION_TEMPLATES = {
    "walk_to": {
        "label": "Walk To",
        "icon": "🚶",
        "params": [
            { "key": "target", "type": "position", "required": true }
        ]
    },
    "speak": {
        "label": "Speak",
        "icon": "💬",
        "params": [
            { "key": "text", "type": "text", "required": true },
            { "key": "duration", "type": "float", "default": 2.0 }
        ]
    },
    "wait": {
        "label": "Wait",
        "icon": "⏳",
        "params": [
            { "key": "duration", "type": "float", "required": true }
        ]
    },
    "ragdoll": {
        "label": "Ragdoll",
        "icon": "💥",
        "params": []
    },
    "recover": {
        "label": "Recover",
        "icon": "🔄",
        "params": []
    }
}
```

**Extensibility:** Adding a new action type = appending to `ACTION_TEMPLATES`. No other code changes required.

### 4.2. Extensible Trigger Registry

Similarly, trigger types are registry-driven:

```gdscript

# trigger_registry.gd (NEW)
const TRIGGER_TEMPLATES = {
    "arrived_at_waypoint": {
        "label": "Arrives at waypoint",
        "icon": "📍",
        "target_type": "waypoint"
    },
    "action_finished": {
        "label": "Completes any action",
        "icon": "✅",
        "target_type": "action_type"
    },
    "speech_finished": {
        "label": "Finishes speaking",
        "icon": "💬",
        "target_type": "none"
    },
    "entered_area": {
        "label": "Enters trigger area",
        "icon": "🎯",
        "target_type": "area"
    },
    "collided": {
        "label": "Collides with something",
        "icon": "💥",
        "target_type": "prop"
    }
}
```

### 4.3. Shared UI Components

| Component               | Purpose                       | Reused By                      |
| ----------------------- | ----------------------------- | ------------------------------ |
| **Panel Container**     | Scrollable list of items      | Action Queue Panel, Rule Panel |
| **Editor Popup**        | Edit single item's properties | Action Editor, Rule Editor     |
| **Drag Handle**         | Reorder items                 | Both panels                    |
| **Delete Confirmation** | Confirm before deletion       | Both panels                    |

### 4.4. Extensible Action Properties

Actions are stored as Dictionaries, so future properties can be added without breaking existing code:

```gdscript

# Current action
{ "type": "speak", "text": "Hello", "duration": 2.0 }
# Future action (with text color)
{ "type": "speak", "text": "Hello", "duration": 2.0, "text_color": "#ff0000" }
```

**Extensibility:** New properties are just new keys in the Dictionary. The editor should display editable fields for all known keys and gracefully ignore unknown ones.

---

## 5. Phase 3c.2: Action Queue Panel

### 5.1. Feature Breakdown

| Feature             | Description                                 |
| ------------------- | ------------------------------------------- |
| **Queue Panel**     | Popup showing all actions for a stickman    |
| **Edit Action**     | Re-open action popup with pre-filled values |
| **Delete Action**   | Remove action from queue (confirmation)     |
| **Reorder Actions** | Drag handle to reorder                      |
| **Add Action**      | Append new action from panel                |
| **Clear All**       | Remove all actions (confirmation)           |

### 5.2. Entry Points

| Entry Point     | When to Use                      | How it Works                                |
| --------------- | -------------------------------- | ------------------------------------------- |
| **Popup**       | Edit queue for selected stickman | Click stickman → "Edit Queue" → panel opens |
| **Right-click** | Quick access                     | Right-click stickman → "Edit Queue"         |

### 5.3. UI Layout

```

┌─────────────────────────────────────────────────────────────────────┐
│                     ACTION QUEUE PANEL                             │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  Stickman: Bob                         [×] Close                   │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │  ─────────────────────────────────────────────────────────  │   │
│  │  1  🚶 Walk to Crate                   [✎] [✕] [≡]       │   │
│  │  2  💬 Speak "Hello!"                  [✎] [✕] [≡]       │   │
│  │  3  ⏳ Wait 2.0s                       [✎] [✕] [≡]       │   │
│  │  4  💥 Ragdoll                         [✎] [✕] [≡]       │   │
│  │  5  🔄 Recover                         [✎] [✕] [≡]       │   │
│  │  ─────────────────────────────────────────────────────────  │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                                                                     │
│  [Add Action]  [Clear All]                                         │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘
```

### 5.4. Edit Action Flow

1. User clicks **[✎]** on an action.
2. The **same action popup** appears, with current values pre-filled.
3. User makes changes.
4. Click **OK** → action is updated in the queue.
5. Visuals update immediately.

| Action Type | Pre-filled Values                                  |
| ----------- | -------------------------------------------------- |
| **Walk To** | Current target position (waypoint dot highlighted) |
| **Speak**   | Current text and duration                          |
| **Wait**    | Current duration                                   |
| **Ragdoll** | (No parameters)                                    |
| **Recover** | (No parameters)                                    |

---

## 6. Phase 3c.3: Action Visual Editing

### 6.1. Feature Breakdown

| Feature                   | Description                               |
| ------------------------- | ----------------------------------------- |
| **Waypoint Context Menu** | Right-click waypoint → Edit/Delete/Insert |
| **Edit Walk (Visual)**    | Click a new position → waypoint moves     |
| **Insert Action**         | Insert before/after a specific waypoint   |

### 6.2. Waypoint Context Menu

In Edit mode, right-clicking a waypoint dot opens:

```

Right-click Waypoint 3:
┌─────────────────────────────────────────────┐
│  ✎ Edit this Walk                           │
│  ✕ Delete this Walk                         │
│  ⬆ Insert action before                    │
│  ⬇ Insert action after                     │
└─────────────────────────────────────────────┘
```

| Action                   | Behavior                                                       |
| ------------------------ | -------------------------------------------------------------- |
| **Edit this Walk**       | Enters target placement mode → click new spot → waypoint moves |
| **Delete this Walk**     | Removes the walk action from the queue                         |
| **Insert action before** | Opens action popup → inserts new action before this one        |
| **Insert action after**  | Opens action popup → inserts new action after this one         |

### 6.3. Visual Update Flow

```
User right-clicks waypoint
    ↓
Context menu appears
    ↓
User clicks "Edit this Walk"
    ↓
Stage enters target placement mode
    ↓
Current waypoint is highlighted (blinking)
    ↓
User clicks new position on stage
    ↓
Old waypoint removed, new waypoint appears
    ↓
walk_to action's target is updated
    ↓
Dotted lines reconnect
    ↓
Order numbers remain the same
```

---

## 7. Phase 3c.4: Rule Panel

### 7.1. Feature Breakdown

| Feature                          | Description                                   |
| -------------------------------- | --------------------------------------------- |
| **Rule Panel**                   | Popup showing all rules for a source stickman |
| **Edit Rule (Full)**             | Edit trigger type, trigger target, action(s)  |
| **Edit Rule (Consequence-Only)** | Quick edit of actions only                    |
| **Delete Rule**                  | Remove rule from registry (confirmation)      |
| **Reorder Rules**                | Drag handle to reorder evaluation order       |
| **Add Action to Rule**           | Add another action to an existing rule        |
| **Remove Action from Rule**      | Delete an action from a rule                  |
| **Clear All**                    | Remove all rules (confirmation)               |

### 7.2. Entry Points

| Entry Point          | When to Use                   | How it Works                                      |
| -------------------- | ----------------------------- | ------------------------------------------------- |
| **Rule Label**       | Edit a specific rule          | Click the rule label (dashed line) → editor opens |
| **Stickman Context** | View all rules for a stickman | Right-click stickman → "Edit Rules" → panel opens |

### 7.3. Rule Panel UI

```
┌─────────────────────────────────────────────────────────────────────┐
│                       RULE PANEL                                   │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  Source: Stickman A                         [×] Close              │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │  ─────────────────────────────────────────────────────────  │   │
│  │  1  📍 When A arrives at Waypoint 3                        │   │
│  │     → B speaks "Hello there!"                [✎] [✕] [≡]  │   │
│  │                                                             │   │
│  │  2  📍 When A arrives at Waypoint 5                        │   │
│  │     → C walks to crate                     [✎] [✕] [≡]  │   │
│  │                                                             │   │
│  │  3  🎯 When A enters Area                                  │   │
│  │     → All stickmen ragdoll                  [✎] [✕] [≡]  │   │
│  │  ─────────────────────────────────────────────────────────  │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                                                                     │
│  [Add Rule]  [Clear All]                                           │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘
```

### 7.4. Rule Editor (Full)

Opens when user clicks **[✎]** on a rule in the panel:

```

┌─────────────────────────────────────────────────────────────────────┐
│                     EDIT RULE                                      │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  Trigger:                                                          │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │  [📍 Arrives at waypoint ▼]  [Click target →]            │   │
│  │  Target: Waypoint 3 (on stage)                            │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                                                                     │
│  Actions:                                                          │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │  1  💬 B speaks "Hello there!"          [✎] [✕]         │   │
│  │  2  🚶 C walks to crate                 [✎] [✕]         │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                                                                     │
│  [Add Action]  [Cancel]  [OK]                                      │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘
```

### 7.5. Rule Editor (Consequence-Only)

Opens when user clicks a rule label on the stage:

```
┌─────────────────────────────────────────────────────────────────────┐
│                     EDIT RULE                                      │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  When:  📍 A arrives at Waypoint 3  (read-only)                   │
│  ──────────────────────────────────────────────────────────────  │
│  Then:                                                            │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │  1  💬 B speaks "Hello there!"          [✎] [✕]         │   │
│  │  2  🚶 C walks to crate                 [✎] [✕]         │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                                                                     │
│  [Add Action]  [Done]  [Cancel]                                    │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘
```

**Focus:** The trigger is displayed but **read-only**. For trigger editing, use the full rule editor.

---

## 8. Phase 3c.5: Rule Visual Editing

### 8.1. Feature Breakdown

| Feature                      | Description                                 |
| ---------------------------- | ------------------------------------------- |
| **Rule Label Click**         | Click rule label → consequence-only editor  |
| **Waypoint → Rules**         | Right-click waypoint → "Edit Trigger Rules" |
| **Rule Reordering (Visual)** | Evaluation order shown on stage (optional)  |

### 8.2. Waypoint → Rules

In Edit mode, right-clicking a waypoint dot that is used as a trigger target:

```
Right-click Waypoint 3:
┌─────────────────────────────────────────────┐
│  ✎ Edit this Walk (action)                  │
│  ─────────────────────────────────────────  │
│  ⚡ Edit Trigger Rules (2 rules)            │
└─────────────────────────────────────────────┘
```

Clicking "Edit Trigger Rules" opens the Rule Panel filtered to rules using that waypoint.

---

## 9. File Structure

| File                                | Purpose                                                |
| ----------------------------------- | ------------------------------------------------------ |
| `scripts/action_registry.gd`        | Registry of action templates (extensible)              |
| `scripts/trigger_registry.gd`       | Registry of trigger templates (extensible)             |
| `scripts/queue_panel.gd`            | Action Queue Panel controller                          |
| `scripts/queue_panel.tscn`          | Action Queue Panel scene                               |
| `scripts/rule_panel.gd`             | Rule Panel controller                                  |
| `scripts/rule_panel.tscn`           | Rule Panel scene                                       |
| `scripts/action_editor.gd`          | Action Editor popup controller                         |
| `scripts/action_editor.tscn`        | Action Editor popup scene                              |
| `scripts/rule_editor.gd`            | Rule Editor popup controller (full + consequence-only) |
| `scripts/rule_editor.tscn`          | Rule Editor popup scene                                |
| `scripts/waypoint_context.gd`       | Waypoint right-click menu                              |
| `scripts/sandbox_stage.gd`          | Add "Edit Queue", "Edit Rules", integrate editors      |
| `scripts/stage_director_visuals.gd` | Waypoint hit-testing, rule label click → editor        |

---

## 10. Extensibility Guide

### 10.1. Adding a New Action Type

```gdscript

# 1. Add to action_registry.gd
const ACTION_TEMPLATES = {
    # ... existing actions ...
    "jump": {
        "label": "Jump",
        "icon": "🦘",
        "params": [
            { "key": "height", "type": "float", "default": 100.0 },
            { "key": "duration", "type": "float", "default": 0.5 }
        ]
    }
}
```

# 2. Implement the action in StickmanRig.\_process_queue()

# 3. Add the action to the popup (automatically from registry)

### 10.2. Adding a New Rule Trigger Type

```gdscript

# 1. Add to trigger_registry.gd
const TRIGGER_TEMPLATES = {
    # ... existing triggers ...
    "variable_changed": {
        "label": "Variable changes",
        "icon": "📊",
        "target_type": "variable"
    }
}
```

# 2. Emit the trigger signal from SandboxStage

# 3. Add the trigger to the rule builder (automatically from registry)

### 10.3. Adding a New Action Property

```gdscript

# 1. The action is stored as a Dictionary
{ "type": "speak", "text": "Hello", "duration": 2.0, "text_color": "#ff0000" }
# 2. The Action Editor reads all keys from params
# 3. Unknown keys are displayed as read-only (or editable with generic control)
# 4. The action runner reads the new key when executing
```

---

## 11. Acceptance Criteria

### 11.1. Action Queue Panel

-"Edit Queue" opens panel from popup and right-click.

-Panel shows all actions in order.

-Each action shows type, parameters, and order number.

-[✕] deletes action (confirmation dialog).

-[✎] opens edit popup with pre-filled values.

-[≡] reorders actions.

-"Clear All" removes all actions (confirmation).

-"Add Action" appends a new action.

### 11.2. Edit Action

- Walk To: Edit opens target placement mode; clicking new spot updates waypoint.
- Speak: Edit opens text dialog with current text pre-filled.
- Wait: Edit opens duration dialog with current value pre-filled.
- Ragdoll/Recover: Edit opens confirmation dialog.

### 11.3. Waypoint Context Menu

- Right-click waypoint opens context menu.
- "Edit this Walk" enters target placement mode.
- "Delete this Walk" removes the action.
- "Insert action before/after" inserts new action.

### 11.4. Rule Panel

- "Edit Rules" opens panel from stickman context menu.
- Panel shows all rules where stickman is trigger source.
- Each rule shows trigger type, target, and action(s).
- `[✕] deletes rule (confirmation).
- `[✎] opens rule editor with pre-filled values.
- `[≡] reorders rules.
- "Add Rule" opens rule builder.
- "Clear All" removes all rules (confirmation).

### 11.5. Rule Editor

- Full editor: trigger type dropdown works, trigger target can be clicked.
- Full editor: action type dropdown works, target can be clicked.
- Full editor: parameters (text, duration) can be edited.
- Consequence-only editor: trigger is read-only.
- Consequence-only editor: actions can be edited.
- Multi-action rules: add/remove actions.
- Saving updates rule in event registry.
- Visual connectors update immediately.

### 11.6. Visual Updates

- Waypoint dots move when Walk actions are edited.
- Speech badge text updates when Speak actions are edited.
- Wait duration updates.
- Dotted lines reconnect to reflect new order.
- Order numbers update after insert/delete/reorder.
- Rule labels update with new summaries.
- Dashed lines reconnect to new targets.

### 11.7. Backward Compatibility

- Existing queues load and display correctly.
- Editing preserves action types and parameters.
- Existing rules load and display correctly.
- Editing a rule preserves the rule ID.
- Deleting an action/rule cleans up all references.

### 11.8. Extensibility

- New action types can be added via registry (no code changes required).
- New trigger types can be added via registry.
- New action properties are supported (dictionary keys).
- Editor gracefully handles unknown keys.

---

## 12. Implementation Order Summary

| Phase    | Focus                 | Key Deliverables                                        |
| -------- | --------------------- | ------------------------------------------------------- |
| **3c.1** | Foundation            | Action Registry, Trigger Registry, Shared UI Components |
| **3c.2** | Action Queue Panel    | Queue panel, edit/delete/reorder actions                |
| **3c.3** | Action Visual Editing | Waypoint context menu, visual walk editing              |
| **3c.4** | Rule Panel            | Rule panel, full/consequence-only edit, reorder         |
| **3c.5** | Rule Visual Editing   | Rule label click, waypoint trigger rules                |

---

## 13. Summary

| Before                               | After                                         |
| ------------------------------------ | --------------------------------------------- |
| Actions can only be appended         | Actions can be edited, deleted, and reordered |
| Rules can only be created or deleted | Rules can be edited, deleted, and reordered   |
| No way to fix mistakes               | Edit any parameter                            |
| No way to change order               | Drag to reorder                               |
| No visual editing                    | Waypoint context menu + visual walk editing   |
| No chain reaction editing            | Add/remove actions from rules                 |
| Fixed evaluation order               | Drag to reorder rules                         |
| Tightly coupled code                 | Registry-driven, extensible architecture      |

**This completes the Director Tool's full editing capabilities.** Directors can now create, edit, delete, and reorder both actions and rules with full control and extensibility for future development.