ryan/stickman
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Phase 14 - Organized directories.

Browse Source
This commit is contained in:
ryan
2026-10-03 19:13:39 -04:00
parent 6666173c4f
commit d950fd9d9a
307 changed files with 1452 additions and 1110 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/archive/plans/PHASE_3c_EDITOR.md
+593
View File
@@ -0,0 +1,593 @@
# 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.