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:

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

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

# 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

# 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

# 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

# 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.