701 lines
38 KiB
Markdown
701 lines
38 KiB
Markdown
# Phase 3c — Editor Tools: Action & Rule Editing (Implementation Spec)
|
||
|
||
Status: IMPLEMENTED + TESTED (12 headless suites, 667 assertions; `tests/test_phase3c_editor.gd` alone: 253 assertions)
|
||
Related plan: `plans/PHASE_3c_EDITOR.md`
|
||
Target: Godot **4.7** (`project.godot:19` declares `config/features=PackedStringArray("4.7", ...)`; the Phase 3c test header names `Godot_v4.7.1-stable_win64_console.exe`).
|
||
|
||
---
|
||
|
||
## 1. Overview & Scope
|
||
|
||
Phase 3c adds **full editing** for the Sandbox Stage's two director-facing authoring
|
||
artifacts that previously had no in-place editing:
|
||
|
||
- **Action queues** (per-`StickmanRig`, Phase 3a): actions could only be *appended*. Phase 3c
|
||
adds a **Queue Panel** (view / edit / delete / drag-reorder / add / clear-all) and a
|
||
**waypoint context menu** with visual walk re-placement and insert-before/after.
|
||
- **Event rules** (`_event_rules` on `SandboxStage`, Phase 4): rules could only be
|
||
*created or deleted*. Phase 3c adds a **Rule Panel** (view / edit / delete / drag-reorder /
|
||
add / clear-all), a **full rule editor** (trigger + target + actions) and a
|
||
**consequence-only rule editor** (trigger read-only; actions editable).
|
||
|
||
Everything is **registry-driven**: two const registries (`ActionRegistry`,
|
||
`TriggerRegistry`) are the single source of truth for the action/trigger templates, and the
|
||
new editors + panels generate their UI from them. Adding a new action or trigger type is a
|
||
one-entry registry append (plan §4/§10) — no other code changes.
|
||
|
||
### In scope
|
||
|
||
- `scripts/action_registry.gd` / `trigger_registry.gd` — extensible template registries.
|
||
- `scripts/queue_panel.gd` + `scenes/queue_panel.tscn` — Action Queue panel.
|
||
- `scripts/rule_panel.gd` + `scenes/rule_panel.tscn` — Rule list panel.
|
||
- `scripts/action_editor.gd` + `scenes/action_editor.tscn` — single-action property editor.
|
||
- `scripts/rule_editor.gd` + `scenes/rule_editor.tscn` — full / consequence-only rule editor.
|
||
- `scripts/waypoint_context.gd` — waypoint right-click menu.
|
||
- `scripts/sandbox_stage.gd` — Phase 3c wiring: "Edit Queue…"/"Edit Rules…" entry points,
|
||
right-click context menus, the **unified target-capture system** (`CaptureKind`), the shared
|
||
confirmation dialog, and consequence-only rule editing on rule-label click.
|
||
- `scripts/stage_director_visuals.gd` — `hit_test_waypoint_action()`, `set/clear_edit_waypoint`
|
||
with the pulsing edit highlight, and rule-label → editor routing.
|
||
- `tests/test_phase3c_editor.gd` — 253-assertion headless suite.
|
||
|
||
### Out of scope / untouched (must not regress)
|
||
|
||
- **`.stk` format / the editor** — no changes.
|
||
- **Queue / rule disk persistence** — still in-memory across `EDIT ⇄ DIRECT ⇄ PLAY` toggles,
|
||
reset on scene reload (matches Phase 3a/4 scope).
|
||
- **The queue runner** (`StickmanRig._process_queue`, Phase 3a) and the **event engine**
|
||
(Phase 4) — read only; they already consume the same action/rule dict shapes.
|
||
- **Rule-builder flows** (Phase 4 `RuleStep` state machine) — unchanged; Phase 3c's editors are
|
||
additive alongside them. The panel "Add Rule" reuses `_begin_rule_build()`.
|
||
|
||
---
|
||
|
||
## 2. Recorded User / Implementation Decisions
|
||
|
||
1. **Registries are const dictionaries with static accessors.** Each action/trigger template is
|
||
one const dict entry. Because `Dictionary.keys()` is untyped at runtime, the registries expose
|
||
`static func types() -> Array[String]` (a genuinely typed array) rather than exposing `.keys()`
|
||
directly, so callers can store the type list in typed locals (`ActionEditor._current_type`,
|
||
`RuleEditor._select_action_type`).
|
||
2. **Panels/editors are `PopupPanel`s with `exclusive = true` + `popup_window = true`** built in
|
||
code. The four `.tscn` files are **minimal shells** (bare `PopupPanel` + root script); all UI
|
||
is constructed in `_ready()` (consistent with the Phase 3b `asset_selector.tscn` pattern).
|
||
Because they are exclusive, the stage must hide a host popup before entering a stage-click
|
||
capture or opening a nested editor, and re-show it on resolve/cancel (see Known Limitations,
|
||
§10 #19).
|
||
3. **Rule-action shape ↔ flat queue-action conversions live on the registry.** A rule action
|
||
nests params under `params` and adds `target` (the actor's instance id); a flat queue action
|
||
(Phase 3a) inlines them. `ActionRegistry.to_rule_action()` / `from_rule_action()` convert, and
|
||
`ActionRegistry.summarize()` / `TriggerRegistry.summarize()` produce the one-line labels used
|
||
by both the panels and the editors (they `get()` with fallbacks tolerant of either key layout).
|
||
4. **Waypoint "Edit this Walk" is a visual stage edit** (a `POSITION` capture), not a numeric
|
||
dialog. The target waypoint is highlighted with a **pulsing amber ring** drawn by
|
||
`StageDirectorVisuals` while the capture is pending.
|
||
5. **`ragdoll` / `recover` "Edit" = a paramless `ActionEditor` pre-fill.** Plan §11.2 originally
|
||
specified a separate *confirmation dialog* for editing these no-parameter actions; the
|
||
implementation instead reuses the generic `ActionEditor` (open, then OK) — fewer special
|
||
cases, and the type is unchanged unless the user changes it. This is a deliberate deviation
|
||
from the plan, not a defect (recorded in the tech-debt Change Log only; no debt row).
|
||
6. **Confirmations use one shared `ConfirmationDialog`** (`_ask_confirm(title, message, cb)`).
|
||
Queue delete / clear-all and Rule delete / clear-all confirm before mutating.
|
||
7. **Reordering is nearest-row-center drop semantics** (see Known Limitations, §10 #21): a drag
|
||
targets the row whose vertical center is nearest the pointer.
|
||
8. **"Edit Queue…" / "Edit Rules…" entry points are content-gated.** In the Direct action popup
|
||
and the stickman right-click menu, "📋 Edit Queue…" is hidden (or disabled) when the stickman's
|
||
queue is empty, and "⚡ Edit Rules…" is hidden (or disabled) when the stickman is the source of
|
||
no rule in `_event_rules`. The waypoint menu's "⚡ Edit Trigger Rules" entry already follows this
|
||
pattern — `WaypointContext.popup_for(rect, count)` enables it (and shows the count) only when
|
||
`count > 0`. Rationale: a menu item that opens an empty panel is noise; gating it signals that
|
||
there is nothing to edit.
|
||
|
||
---
|
||
|
||
## 3. New Files
|
||
|
||
| File | `class_name` / extends | Responsibility |
|
||
|---|---|---|
|
||
| `res://scripts/action_registry.gd` | `ActionRegistry` / `RefCounted` | `ACTION_TEMPLATES` (5 actions), static accessors + queue⇄rule conversions + summaries |
|
||
| `res://scripts/trigger_registry.gd` | `TriggerRegistry` / `RefCounted` | `TRIGGER_TEMPLATES` (5 triggers), static accessors + summaries |
|
||
| `res://scripts/queue_panel.gd` | `QueuePanel` / `PopupPanel` | Action Queue editor popup (root of `queue_panel.tscn`) |
|
||
| `res://scripts/rule_panel.gd` | `RulePanel` / `PopupPanel` | Rule list editor popup (root of `rule_panel.tscn`) |
|
||
| `res://scripts/action_editor.gd` | `ActionEditor` / `PopupPanel` | Single-action add/edit editor (root of `action_editor.tscn`) |
|
||
| `res://scripts/rule_editor.gd` | `RuleEditor` / `PopupPanel` | Full + consequence-only rule editor (root of `rule_editor.tscn`) |
|
||
| `res://scripts/waypoint_context.gd` | `WaypointContext` / `PopupMenu` | Waypoint right-click menu |
|
||
| `res://scenes/queue_panel.tscn` / `rule_panel.tscn` / `action_editor.tscn` / `rule_editor.tscn` | `PopupPanel` roots | Minimal shells; UI built in code |
|
||
|
||
---
|
||
|
||
## 4. Public API Signatures (GDScript)
|
||
|
||
### 4.1 `ActionRegistry` (`res://scripts/action_registry.gd`)
|
||
|
||
```gdscript
|
||
class_name ActionRegistry
|
||
extends RefCounted
|
||
|
||
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": [] },
|
||
}
|
||
|
||
static func types() -> Array[String] # genuinely typed (Dictionary.keys() is untyped)
|
||
static func has_type(type: String) -> bool
|
||
static func label(type: String) -> String # template label, else the type itself
|
||
static func icon(type: String) -> String # template icon, else ""
|
||
static func to_rule_action(action: Dictionary, target_id: int) -> Dictionary
|
||
# flat queue action -> rule-action shape: { "type", "target": target_id,
|
||
# "params": { target | text+duration | duration } } (walk_to/speak/wait only; others -> no params)
|
||
static func from_rule_action(rule_action: Dictionary) -> Dictionary
|
||
# rule-action shape -> flat queue action (drops target, inlines params)
|
||
static func summarize(action: Dictionary) -> String
|
||
# one-line label, e.g. 'Walk To (123, 456)', 'Speak "Hello" (2s)', 'Wait 1s'; tolerates
|
||
# both the flat and rule-action key layouts via get() fallbacks.
|
||
```
|
||
|
||
### 4.2 `TriggerRegistry` (`res://scripts/trigger_registry.gd`)
|
||
|
||
```gdscript
|
||
class_name TriggerRegistry
|
||
extends RefCounted
|
||
|
||
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" },
|
||
}
|
||
|
||
static func types() -> Array[String]
|
||
static func has_type(type: String) -> bool
|
||
static func label(type: String) -> String
|
||
static func icon(type: String) -> String
|
||
static func target_type(type: String) -> String # "waypoint" | "action_type" | "none" | "area" | "prop"
|
||
static func summarize(trigger: Dictionary) -> String # "<icon> <label>", e.g. "📍 Arrives at waypoint"
|
||
```
|
||
|
||
### 4.3 `QueuePanel` (`res://scripts/queue_panel.gd`, root of `queue_panel.tscn`)
|
||
|
||
```gdscript
|
||
class_name QueuePanel
|
||
extends PopupPanel
|
||
|
||
signal edit_requested(index: int) # ✎ on a row
|
||
signal delete_requested(index: int) # ✕ on a row
|
||
signal add_requested() # "➕ Add Action"
|
||
signal clear_requested() # "🗑 Clear All"
|
||
|
||
var rig: StickmanRig = null # attached via setup()
|
||
|
||
func setup(r: StickmanRig) -> void # attach a rig + refresh()
|
||
func refresh() -> void # rebuild rows from rig.get_queue()
|
||
```
|
||
|
||
Notes: built in `_ready()` (`exclusive = true`, `popup_window = true`, `min_size` 460×360).
|
||
Drag-reorder uses `_on_drag_handle_gui_input` (press = begin, motion = nearest-row-center
|
||
target, release = commit). On commit it moves the action via the rig's existing
|
||
`remove_action(from)` + `insert_action(to[, to>from ? to-1 : to], action)` API, so `queue_changed`
|
||
fires and the director overlay redraws. The panel stays decoupled — it never mutates directly
|
||
beyond the reorder helper, and add/edit/delete/clear are delegated to the stage via signals.
|
||
|
||
### 4.4 `RulePanel` (`res://scripts/rule_panel.gd`, root of `rule_panel.tscn`)
|
||
|
||
```gdscript
|
||
class_name RulePanel
|
||
extends PopupPanel
|
||
|
||
signal edit_requested(rule_id: int) # ✎ on a row
|
||
signal delete_requested(rule_id: int) # ✕ on a row
|
||
signal add_requested() # "➕ Add Rule"
|
||
signal clear_requested() # "🗑 Clear All"
|
||
signal reorder_requested(ordered_ids: Array[int]) # new order of the DISPLAYED rules' ids
|
||
|
||
func set_rules(rules: Array[Dictionary], title_hint: String) -> void
|
||
# update the list + title WITHOUT popping up (used by restore flows that re-pop afterwards)
|
||
func show_rules(rules: Array[Dictionary], title_hint: String) -> void
|
||
# set_rules() then popup_centered()
|
||
func refresh() -> void # rebuild rows from the stored _rules
|
||
```
|
||
|
||
The stage pre-filters `rules` (by source stickman **or** by waypoint) before calling
|
||
`show_rules`/`set_rules`. Rows show trigger summary (`<icon> <actor?> <label>`) plus one
|
||
indented `→ ...` line per action (`<icon> <actor?> <summary>`), an order number, and ✎ / ✕ /
|
||
drag-reorder ≡. Reorder emits the new order of the *displayed* rule ids (see
|
||
`SandboxStage._reorder_filtered_rules`, §6) so un-filtered rules keep their slots.
|
||
|
||
### 4.5 `ActionEditor` (`res://scripts/action_editor.gd`, root of `action_editor.tscn`)
|
||
|
||
```gdscript
|
||
class_name ActionEditor
|
||
extends PopupPanel
|
||
|
||
signal committed(action: Dictionary) # flat queue action (type + inline params)
|
||
signal cancelled()
|
||
signal target_requested() # walk_to needs a stage target -> stage captures it
|
||
|
||
func open_new() -> void # "add" mode; empty, default type walk_to
|
||
func open_edit(action: Dictionary) -> void # "edit" mode; pre-filled from a flat queue action
|
||
func set_walk_target(pos: Vector2) -> void # stage calls after a POSITION capture; re-pops
|
||
```
|
||
|
||
Type dropdown + param fields are generated from `ActionRegistry`. Param fields: `walk_to` →
|
||
a "🎯 Click target…" button + target label; `speak` → `LineEdit` (text) + duration `SpinBox`
|
||
(0.1–3600 s, step 0.1); `wait` → a duration `SpinBox`; `ragdoll`/`recover` (and any future
|
||
no-param action) → no fields. Pressing **OK** on a `walk_to` with no target set emits
|
||
`target_requested()` instead of committing; once a target is captured (via
|
||
`set_walk_target`) OK emits `committed(action)`. Esc emits `cancelled()`.
|
||
|
||
### 4.6 `RuleEditor` (`res://scripts/rule_editor.gd`, root of `rule_editor.tscn`)
|
||
|
||
```gdscript
|
||
class_name RuleEditor
|
||
extends PopupPanel
|
||
|
||
signal committed(rule: Dictionary) # { id, trigger, actions }
|
||
signal cancelled()
|
||
signal trigger_target_requested(trigger_type: String) # stage captures the target by trigger type
|
||
signal action_add_requested() # stage opens ActionEditor to collect a new action
|
||
signal action_edit_requested(index: int) # stage opens ActionEditor pre-filled for index
|
||
|
||
func open_full(rule: Dictionary) -> void # trigger type + target + actions editable
|
||
func open_consequence(rule: Dictionary) -> void # trigger READ-ONLY; actions editable
|
||
func set_trigger_target(target_id: int, params: Dictionary) -> void # after a stage capture; re-pops
|
||
func set_action(index: int, action: Dictionary) -> void # index < 0 appends; re-pops
|
||
func get_action(index: int) -> Dictionary # copy of a rule-action ({} out of range); used to
|
||
# pre-fill the ActionEditor when editing an action
|
||
```
|
||
|
||
Trigger controls are mode-sensitive: in `consequence` mode the trigger is shown via a read-only
|
||
label (`"When: <actor> <summary>"`) and the type dropdown / target row are hidden. In `full` mode
|
||
the target control shown depends on `TriggerRegistry.target_type(type)`: `waypoint` → a "🎯 Click
|
||
target…" button (target label reads `waypoint (x, y)` / `(not set)`); `action_type` → a dropdown
|
||
("Any action" or a specific action type, synced into `trigger.params.action_type` only for
|
||
`action_finished`); `area` / `prop` → a "🎯 Click target…" button + node name label; `none` /
|
||
`speech_finished` → no target control. The **Actions** section lists editable rows with ✎ / ✕ and
|
||
an "➕ Add Action" button; ✕ removes locally (`_remove_action`). **OK** emits `committed({id,
|
||
trigger, actions})` preserving `_rule_id`. Esc emits `cancelled()`.
|
||
|
||
### 4.7 `WaypointContext` (`res://scripts/waypoint_context.gd`)
|
||
|
||
```gdscript
|
||
class_name WaypointContext
|
||
extends PopupMenu
|
||
|
||
const EDIT_WALK := 0
|
||
const DELETE_WALK := 1
|
||
const INSERT_BEFORE := 2
|
||
const INSERT_AFTER := 3
|
||
const EDIT_TRIGGER_RULES := 4
|
||
|
||
func popup_for(rect: Rect2i, trigger_rule_count: int) -> void
|
||
# sets the "⚡ Edit Trigger Rules" entry's text to include the count and enables it when
|
||
# trigger_rule_count > 0 (else disables it), then popup(rect).
|
||
```
|
||
|
||
Item order is fixed in `_init()`: Edit this Walk / Delete this Walk / ⬆ Insert action before /
|
||
⬇ Insert action after / separator / ⚡ Edit Trigger Rules.
|
||
|
||
---
|
||
|
||
## 5. `SandboxStage` Phase 3c State & Entry Points (`scripts/sandbox_stage.gd`)
|
||
|
||
### 5.1 New state
|
||
|
||
```gdscript
|
||
enum CaptureKind { NONE, WAYPOINT, AREA, PROP, STICKMAN, POSITION }
|
||
|
||
# Editor popups/panels (instantiated from their scenes in _build_ui()).
|
||
var _queue_panel: QueuePanel
|
||
var _rule_panel: RulePanel
|
||
var _action_editor: ActionEditor
|
||
var _rule_editor: RuleEditor
|
||
var _waypoint_context: WaypointContext
|
||
var _confirm_dialog: ConfirmationDialog
|
||
var _confirm_callback: Callable = Callable()
|
||
|
||
# Context for the currently open panel.
|
||
var _panel_rig: StickmanRig = null # rig under the queue/rule panel
|
||
var _rule_panel_source_id: int = -1 # >= 0 => filtered by this source stickman's id
|
||
var _rule_panel_waypoint: Vector2 = Vector2.INF # finite => filtered by this waypoint
|
||
var _rule_panel_title: String = ""
|
||
var _rule_panel_filter_ids: Array[int] = [] # ids of the rules currently shown (for clear-all)
|
||
|
||
# Unified stage-click target capture.
|
||
var _capture_kind: CaptureKind = CaptureKind.NONE
|
||
var _capture_hint: String = ""
|
||
var _capture_callback: Callable = Callable()
|
||
var _capture_cancel: Callable = Callable()
|
||
|
||
# ActionEditor routing.
|
||
var _action_editor_kind: String = "" # "queue_add"|"queue_edit"|"queue_insert"|"rule_add"|"rule_edit"
|
||
var _action_editor_index: int = -1
|
||
var _action_editor_rig: StickmanRig = null
|
||
var _action_editor_actor_id: int = -1
|
||
var _action_editor_restore_queue: bool = false # re-pop the queue panel on resolve/cancel
|
||
|
||
# RuleEditor routing.
|
||
var _rule_editor_from_panel: bool = false # re-pop the rule panel on commit/cancel
|
||
|
||
# Visual walk edit.
|
||
var _walk_edit_rig: StickmanRig = null
|
||
var _walk_edit_index: int = -1
|
||
var _walk_edit_from_panel: bool = false
|
||
```
|
||
|
||
### 5.2 Entry-point ids
|
||
|
||
```gdscript
|
||
const ACT_EDIT_QUEUE := 7 # appended to the Direct action popup (after Phase 4's ACT_WHEN)
|
||
const ACT_EDIT_RULES := 8
|
||
const RIG_CTX_EDIT_QUEUE := 0 # stickman right-click context menu
|
||
const RIG_CTX_EDIT_RULES := 1
|
||
```
|
||
|
||
### 5.3 Entry-point routing (all EDIT/DIRECT, never PLAY)
|
||
|
||
| Handler | Trigger | Action |
|
||
|---|---|---|
|
||
| `_on_action_popup_id_pressed(ACT_EDIT_QUEUE)` / `_on_rig_context_id_pressed(RIG_CTX_EDIT_QUEUE)` | "📋 Edit Queue…" (hidden/disabled when `rig.get_queue().is_empty()`) | `_open_queue_panel(rig)` |
|
||
| `... ACT_EDIT_RULES` / `RIG_CTX_EDIT_RULES` | "⚡ Edit Rules…" (hidden/disabled when no rule has `trigger.source == rig.get_instance_id()`) | `_open_rules_panel_for_rig(rig)` |
|
||
| `_open_waypoint_context()` (RMB hit via `_director_visuals.hit_test_waypoint_action`) | waypoint menu | `_waypoint_context.popup_for(rect, _count_rules_for_waypoint(pos))` |
|
||
| `_on_waypoint_context_id_pressed(EDIT_WALK)` | "✎ Edit this Walk" | `_begin_walk_edit(rig, index, false)` |
|
||
| `... DELETE_WALK` | "✕ Delete this Walk" | `rig.remove_action(index)` |
|
||
| `... INSERT_BEFORE/AFTER` | "⬆/⬇ Insert …" | `_open_action_editor("queue_insert", {}, index(+1), rig, -1, false)` |
|
||
| `... EDIT_TRIGGER_RULES` | "⚡ Edit Trigger Rules" | `_open_trigger_rules_panel(pos)` |
|
||
| `_begin_edit_rule(id)` (rule-label click → consequence) | click a rule dashed label | `_open_rule_editor_consequence(rule)` |
|
||
| `_on_rule_panel_edit_requested(rule_id)` | rule ✎ in panel | `_open_rule_editor_full(rule, true)` |
|
||
|
||
**Entry-point gating:** both menus refresh their "📋 Edit Queue…" / "⚡ Edit Rules…" item
|
||
visibility on `about_to_popup` via `_refresh_action_popup_items()` (the Direct action popup) and
|
||
`_refresh_rig_context_items()` (the stickman right-click menu). "Edit Queue…" is hidden/disabled
|
||
when the rig's queue is empty; "Edit Rules…" is hidden/disabled when the rig is the source of no
|
||
rule in `_event_rules` (the same test as `_rule_matches_panel_filter`, §5.4). The waypoint menu's
|
||
"⚡ Edit Trigger Rules" entry is already count-gated by `WaypointContext.popup_for(rect, count)`.
|
||
|
||
`_handle_right_click()` precedence (EDIT/DIRECT): an active placement/drag RMB keeps its Phase 4b
|
||
"cancel build" role; otherwise a **waypoint** hit (nearest within `WAYPOINT_HIT_RADIUS_PX` /
|
||
zoom) opens the waypoint context menu; otherwise a **stickman** hit opens the rig context menu.
|
||
|
||
### 5.4 Rule-panel filtering
|
||
|
||
`_rule_matches_panel_filter(rule)`:
|
||
- `_rule_panel_source_id >= 0` → `trigger.source == _rule_panel_source_id`.
|
||
- else if `_rule_panel_waypoint` is finite → the rule's trigger is `arrived_at_waypoint` and its
|
||
`trigger.params.waypoint_pos` is within `WAYPOINT_MATCH_EPSILON` of the panel waypoint.
|
||
- else → all rules (unused fallback).
|
||
|
||
`_show_rule_panel()` / `_refresh_rule_panel()` compute the filtered list + `_rule_panel_filter_ids`
|
||
then call `RulePanel.show_rules`/`set_rules`. The **Add Rule** button only works from a
|
||
source-stickman panel (`_rule_panel_source_id >= 0`); from a waypoint-filtered panel it toasts
|
||
"Select a stickman first" (see Known Limitations §10 #20). "Add Rule" hides the panel and reuses
|
||
the Phase 4 `_begin_rule_build(source_id, from_panel=true)`; on finish `_restore_rule_build_panel()`
|
||
re-pops it.
|
||
|
||
---
|
||
|
||
## 6. Data Flow (representative paths)
|
||
|
||
**Edit a non-walk queue action** (`queue_edit`):
|
||
1. Queue panel row ✎ → `_on_queue_panel_edit_requested(index)`.
|
||
2. `_open_action_editor("queue_edit", action.duplicate(true), index, _panel_rig, -1, hide_queue=true)`
|
||
→ stores routing state, hides the queue panel, `ActionEditor.open_edit(action)`.
|
||
3. OK → `_on_action_editor_committed(flat)`: `remove_action(idx)` + `insert_action(idx, flat)`
|
||
(`queue_changed` → visuals redraw), then `_restore_queue_panel()` re-pops the refreshed panel.
|
||
Cancel → `_restore_queue_panel()` with no mutation.
|
||
|
||
**Edit a `walk_to` (visual)**: `_on_queue_panel_edit_requested` detects `walk_to` and routes to
|
||
`_begin_walk_edit(rig, index, from_panel=true)` instead of the generic editor.
|
||
`_begin_walk_edit` highlights the waypoint (`_director_visuals.set_edit_waypoint(pos)`) and begins
|
||
a `POSITION` capture. On capture, `_on_walk_edit_captured` rewrites the walk action's `target`
|
||
via `remove_action`+`insert_action`, clears the highlight, and (from a panel) re-pops it; cancel
|
||
(`_cb_walk_edit_cancel`) just clears the highlight + re-pops.
|
||
|
||
**Consequence-only rule edit** (rule label click): `_begin_edit_rule(id)` → `_open_rule_editor_
|
||
consequence(rule)` → `RuleEditor.open_consequence(rule)`. OK → `_on_rule_editor_committed(rule)`
|
||
writes the rule back into `_event_rules` by `id` (or, for a missing id, appends as new),
|
||
`_director_visuals.set_rules(...)`, and calls `_restore_rule_panel()` (a no-op here since
|
||
`_rule_editor_from_panel == false`).
|
||
|
||
**Reordering rules in a filtered panel**: `RulePanel.reorder_requested(ordered_ids)` →
|
||
`_on_rule_panel_reorder_requested` → `_reorder_filtered_rules(ordered_ids)`. This walks the full
|
||
`_event_rules`, rewrites only the slots whose ids are in `ordered_ids` into the new order, and
|
||
leaves every un-filtered rule's slot untouched; then `_director_visuals.set_rules(_event_rules)`.
|
||
|
||
---
|
||
|
||
## 7. Unified Target-Capture System (`CaptureKind`)
|
||
|
||
Phase 3a/4 scattered several "pending target" flows (walk target, rule trigger target, rule
|
||
action actor). Phase 3c consolidates them:
|
||
|
||
```gdscript
|
||
func _begin_capture(kind: CaptureKind, hint: String,
|
||
on_resolve: Callable, on_cancel: Callable = Callable()) -> void:
|
||
# sets _capture_kind/_capture_hint/_capture_callback/_capture_cancel; applies the flag cursor
|
||
# and refreshes the status bar.
|
||
|
||
func _resolve_capture(world_pos: Vector2) -> void:
|
||
# match kind:
|
||
# WAYPOINT -> _director_visuals.hit_test_waypoint(world_pos) (Vector2 or INF-miss)
|
||
# AREA -> _selection.hit_test(world_pos) is TriggerArea
|
||
# PROP -> ... is PropBlock
|
||
# STICKMAN -> ... is StickmanRig
|
||
# POSITION -> _snap_to_grid(world_pos) when snap is on, else world_pos
|
||
# On a valid hit: _end_capture() then on_resolve.call(value). On a miss: keep capturing.
|
||
|
||
func _cancel_capture() -> void: # _end_capture() then on_cancel.call() (Esc path)
|
||
func _end_capture() -> void: # clears kind/hint/callbacks; restores cursor + status
|
||
```
|
||
|
||
Stage-click and Esc handling check `_capture_kind != CaptureKind.NONE` first, giving capture
|
||
priority over placement/selection (matching the existing Esc chain). Each editor's capture
|
||
cancel callback re-pops the editor that requested the capture (`_cb_rule_trigger_cancel`,
|
||
`_cb_rule_actor_cancel`, `_cb_editor_walk_target_cancel`).
|
||
|
||
---
|
||
|
||
## 8. `StageDirectorVisuals` Extensions (`scripts/stage_director_visuals.gd`)
|
||
|
||
```gdscript
|
||
# Phase 3c: the walk_to waypoint currently being visually edited (blinking highlight).
|
||
var _edit_waypoint: Vector2 = Vector2.INF
|
||
|
||
func set_edit_waypoint(pos: Vector2) -> void # highlight on + mark_dirty()
|
||
func clear_edit_waypoint() -> void # highlight off + mark_dirty()
|
||
|
||
func hit_test_waypoint(world_pos: Vector2) -> Vector2
|
||
# nearest waypoint dot within WAYPOINT_HIT_RADIUS_PX / zoom; Vector2.INF on miss
|
||
# (thin wrapper over hit_test_waypoint_action)
|
||
func hit_test_waypoint_action(world_pos: Vector2) -> Dictionary
|
||
# {"rig": StickmanRig, "index": int, "pos": Vector2} for the nearest walk_to, or {}
|
||
# on miss. Reuses the same anchor math as _draw_rig_queue (rig feet as the current point).
|
||
```
|
||
|
||
- `_process()` redraws every frame while `_edit_waypoint.is_finite()` (the blink is
|
||
time-animated) and otherwise only on the dirty flag, so an active visual walk edit keeps
|
||
pulsing without a `mark_dirty` storm.
|
||
- `_draw_waypoint()` renders a **pulsing amber ring** (`radius + 6/zoom`,
|
||
`Color(1.0, 0.8, 0.0, 0.5 + 0.5·sin(ticks/150))`) around the waypoint when it is within 0.5 px
|
||
of `_edit_waypoint`.
|
||
- Rule-label click routing already existed via `hit_test_rule()` (Phase 4); Phase 3c connects the
|
||
label part to `SandboxStage._begin_edit_rule(id)` (consequence editor).
|
||
|
||
---
|
||
|
||
## 9. Extensibility Guide
|
||
|
||
### 9.1 Add a new action type
|
||
|
||
```gdscript
|
||
# 1. action_registry.gd — append an entry (params drive the ActionEditor + summaries).
|
||
const ACTION_TEMPLATES := {
|
||
# ... existing ...
|
||
"jump": { "label": "Jump", "icon": "🦘",
|
||
"params": [ { "key": "height", "type": "float", "default": 100.0 },
|
||
{ "key": "duration", "type": "float", "default": 0.5 } ] },
|
||
}
|
||
# 2. Implement execution in StickmanRig._process_queue() (the queue runner).
|
||
# 3. (For rule actions) extend ActionRegistry.to_rule_action()/from_rule_action()/summarize()
|
||
# with the new type's params. The ActionEditor dropdown + param fields + the panels' summaries
|
||
# appear automatically from the registry + summarize().
|
||
```
|
||
|
||
### 9.2 Add a new rule trigger type
|
||
|
||
```gdscript
|
||
# 1. trigger_registry.gd — append an entry with the correct target_type.
|
||
const TRIGGER_TEMPLATES := {
|
||
# ... existing ...
|
||
"variable_changed": { "label": "Variable changes", "icon": "📊", "target_type": "variable" },
|
||
}
|
||
# 2. Emit the trigger from SandboxStage's event engine when it fires.
|
||
# 3. Add the trigger to the rule builder (auto from the registry); if it needs a *new* target
|
||
# kind, add a CaptureKind + a _resolve_capture arm and a _refresh_trigger() target control.
|
||
```
|
||
|
||
### 9.3 Add a new action / rule property
|
||
|
||
Actions and rules remain `Dictionary`s. Add new keys freely; the `ActionEditor`/`RuleEditor`
|
||
display editable fields for the registry `params` and gracefully ignore unknown keys, and the
|
||
summaries use `get()` fallbacks so un-summarized keys do not crash.
|
||
|
||
---
|
||
|
||
## 10. Known Limitations
|
||
|
||
| # | Limitation | Severity |
|
||
|---|---|---|
|
||
| 1 | **Confirmation dialog over an exclusive panel.** Queue delete / clear-all (`_on_queue_panel_delete_requested`, `_on_queue_panel_clear_requested`) and Rule delete / clear-all (`_on_rule_panel_delete_requested`, `_on_rule_panel_clear_requested`) call `_ask_confirm(...)` **without hiding the exclusive `QueuePanel`/`RulePanel` first**. Popping the shared `ConfirmationDialog` while an `exclusive = true` panel is visible produces a **non-fatal engine warning** and the confirmation may render **non-modal** over the panel. It still works (the panel is re-shown after the callback); it is cosmetic. (Related to #19's host-visibility discipline — this is the confirmation-dialog facet of it.) |
|
||
| 2 | **`ragdoll`/`recover` "Edit" opens a paramless `ActionEditor`** instead of a dedicated confirmation dialog (plan §11.2). Deliberate design decision (§2 decision 5); the type is changeable via the editor. Not a defect — recorded here + Change Log only. |
|
||
| 3 | **Rule Panel "Add Rule" is unavailable in waypoint-filtered panels.** `_on_rule_panel_add_requested` toasts "Select a stickman first" when `_rule_panel_source_id < 0` (the waypoint-filtered "Edit Trigger Rules" state). A waypoint can be targeted by rules authored by several stickmen, so the source is ambiguous; a future pass could default the source to the waypoint's owning rig or open the builder in "any stickman" mode. (Tracked as tech-debt #20.) |
|
||
| 4 | **Drag-reorder uses nearest-row-center, not an insertion point.** Drop position can read off-by-one near row boundaries (it snaps to a whole row rather than an edge). (Tracked as tech-debt #21.) |
|
||
| 5 | **Panels/editors must hide their host before a capture or nested editor.** Host-visibility discipline is spread across `_open_action_editor`, `_on_action_editor_committed`/`_cancelled`, `_begin_walk_edit`, and `_on_rule_editor_trigger_target_requested`, with one-off `_restore_queue_panel`/`_restore_rule_panel`/`_restore_rule_build_panel` helpers. Works but fragile — a popup-stack abstraction would make it impossible to forget. (Tracked as tech-debt #19.) |
|
||
|
||
---
|
||
|
||
## 11. Acceptance Criteria
|
||
|
||
### 11.1 Action Queue Panel
|
||
- [x] "Edit Queue" opens the panel from the Direct action popup and the stickman right-click menu.
|
||
- [x] Panel shows all actions in order (number + icon + summary).
|
||
- [x] ✕ deletes an action behind a confirmation dialog.
|
||
- [x] ✎ opens the edit popup pre-filled (`walk_to` → visual edit, speak text/duration, wait duration).
|
||
- [x] ≡ drag-reorders actions (nearest-row-center).
|
||
- [x] "Clear All" confirms then clears; "Add Action" appends.
|
||
- [x] All mutations go through the rig queue API → visuals update.
|
||
- [ ] "Edit Queue…" is hidden (or disabled) when the stickman's queue is empty (entry-point gating).
|
||
|
||
### 11.2 Edit Action
|
||
- [x] Walk To: edit enters visual target placement (waypoint pulsing highlight); a click moves it.
|
||
- [x] Speak: text + duration pre-filled. Wait: duration pre-filled.
|
||
- [x] Ragdoll/Recover: paramless `ActionEditor` pre-fill (deviation from plan's confirmation dialog).
|
||
|
||
### 11.3 Waypoint Context Menu
|
||
- [x] Right-click a waypoint opens the menu.
|
||
- [x] "Edit this Walk" enters visual placement; "Delete this Walk" removes the action;
|
||
"Insert action before/after" opens the ActionEditor in `queue_insert` at the right index.
|
||
- [x] "Edit Trigger Rules" (enabled + count when rules target the waypoint) opens a filtered Rule Panel.
|
||
|
||
### 11.4 Rule Panel
|
||
- [x] "Edit Rules" opens the panel from the stickman context menu; "Edit Trigger Rules" opens it
|
||
from the waypoint menu, filtered to that waypoint's `arrived_at_waypoint` rules.
|
||
- [x] Panel lists each rule's trigger + action(s); ✎ full editor; ✕ confirm-delete;
|
||
≡ drag-reorder (reorder preserved through `_reorder_filtered_rules`).
|
||
- [x] "Add Rule" (source-stickman panels only) reuses the rule builder; "Clear All" confirms.
|
||
- [ ] "Edit Rules…" is hidden (or disabled) when the stickman is the source of no rule (entry-point gating).
|
||
|
||
### 11.5 Rule Editor
|
||
- [x] Full editor: trigger type dropdown + target capture per type (`waypoint`/`action_type`/`area`/`prop`).
|
||
- [x] Consequence-only editor: trigger read-only.
|
||
- [x] Multi-action rules: add / edit / remove actions; OK preserves the rule id; editing updates
|
||
`_event_rules` and the visuals.
|
||
|
||
### 11.6 Visual Updates
|
||
- [x] Waypoint dots move when walk actions are edited; speech/action text updates; order numbers
|
||
update after insert/delete/reorder; rule labels and dashed connectors update (`mark_dirty`).
|
||
|
||
### 11.7 Backward Compatibility
|
||
- [x] Existing queues and rules load + display through the new panels; editing preserves action
|
||
types/params and rule ids; delete cleans up references. No queue/rule persistence change.
|
||
|
||
### 11.8 Extensibility
|
||
- [x] New action/trigger types = registry append; new properties = new dict keys; unknown keys ignored.
|
||
|
||
---
|
||
|
||
## 12. Verification Plan
|
||
|
||
### 12.1 Runner command (from `tests/test_phase3c_editor.gd:28`)
|
||
|
||
```
|
||
& "C:\Godot4\Godot_v4.7.1-stable_win64_console.exe" --headless --script res://tests/test_phase3c_editor.gd --path .
|
||
```
|
||
|
||
### 12.2 New headless suite — `tests/test_phase3c_editor.gd` (`extends SceneTree`, 253 assertions)
|
||
|
||
Covers:
|
||
1. Registries (`ActionRegistry` / `TriggerRegistry`): `types()`, `label`, `icon`, `target_type`,
|
||
`summarize()` for all 5 actions + 5 triggers, and graceful unknown-type handling.
|
||
2. Scene shells instantiate and build their UI (`queue_panel`/`rule_panel`/`action_editor`/
|
||
`rule_editor`/`waypoint_context`).
|
||
3. `ActionEditor`: `open_new`/`open_edit` pre-fill (walk target, speak text/duration, wait
|
||
duration), `committed`/`cancelled`/`target_requested`, and OK-without-target requests a stage
|
||
target capture.
|
||
4. `RuleEditor`: full vs consequence modes; trigger read-only in consequence; action
|
||
add/edit/remove; `get_action()`; rule-id preservation on commit; `action_finished` dropdown sync.
|
||
5. `QueuePanel`: setup/refresh shows the queue in order; stage add/edit/delete/clear/reorder
|
||
flows mutate the rig queue via its API.
|
||
6. `RulePanel`: filtered list by source stickman and by waypoint; edit/delete/add/clear/reorder.
|
||
7. `WaypointContext`: item ids; trigger-rules entry enabled/disabled by rule count.
|
||
8. `StageDirectorVisuals.hit_test_waypoint_action()` returns `rig`/`index`/`pos`.
|
||
9. `SandboxStage` Phase 3c capture: `CaptureKind` begin/cancel/resolve + Esc priority;
|
||
right-click waypoint/rig context entry points.
|
||
10. Backward compatibility: pre-existing queues/rules display correctly; editing preserves action
|
||
types/params and rule ids.
|
||
|
||
### 12.3 Static verification
|
||
|
||
Headless `--editor --quit` rescan (to register the new `class_name`s), then per-script
|
||
`--check-only` on every new/modified script.
|
||
|
||
### 12.4 Manual (F6)
|
||
|
||
`res://scenes/sandbox_stage.tscn`: queue/rule panel edit-delete-reorder, waypoint context menu,
|
||
visual walk edit, full vs consequence-only rule editor, rule-label click → consequence editor.
|
||
|
||
---
|
||
|
||
## 13. Summary
|
||
|
||
| Before (Phase 3a/4) | After (Phase 3c) |
|
||
|---|---|
|
||
| Actions can only be appended | Actions can be edited, deleted, reordered, inserted before/after a waypoint |
|
||
| Rules can only be created/deleted | Rules can be edited (full + consequence-only), deleted, reordered |
|
||
| No way to fix mistakes | Edit any parameter (text, duration, walk target) |
|
||
| No visual editing | Waypoint context menu + visual walk re-placement (pulsing highlight) |
|
||
| Tightly coupled per-flow pending states | Unified `CaptureKind` stage-click capture system |
|
||
| Fixed evaluation order | Drag-reorder rules (preserving un-filtered slots) |
|
||
| Hard-coded type lists | Registry-driven, extensible (`ActionRegistry` / `TriggerRegistry`) |
|
||
|
||
---
|
||
|
||
## 14. Theme & Font Configuration (`sandbox_theme.json`)
|
||
|
||
Phase 4b introduced `res://sandbox_theme.json` and its loader (`SandboxStage._load_theme()`).
|
||
Phase 3c extends the `fonts` block so **font styles (bold/italic) and per-widget sizes** are
|
||
configurable — not just the handful of sizes + font paths shipped originally.
|
||
|
||
### 14.1 Extended `fonts` schema
|
||
|
||
```jsonc
|
||
"fonts": {
|
||
// Existing keys (unchanged, backward-compatible):
|
||
"ui_font": "", // base UI font resource path ("" = engine default)
|
||
"emoji_font": "", // emoji-capable font resource path
|
||
"action_popup_font_size": 24, // PopupMenu font size (action/trigger/rig/waypoint menus)
|
||
"tooltip_font_size": 18,
|
||
"status_pill_font_size": 16,
|
||
"assignment_badge_font_size": 20, // drawn by StageDirectorVisuals
|
||
"assignment_badge_radius": 9,
|
||
"rule_label_font_size": 16, // drawn by StageDirectorVisuals
|
||
|
||
// NEW — style variant resource paths (bold/italic realised as distinct Font
|
||
// resources, or via FontVariation when a separate file is unavailable):
|
||
"ui_font_bold": "", // fallback to ui_font when empty
|
||
"ui_font_italic": "", // fallback to ui_font when empty
|
||
|
||
// NEW — Phase 3c widget font sizes (fall back to action_popup_font_size):
|
||
"queue_panel_font_size": 18,
|
||
"rule_panel_font_size": 18,
|
||
"action_editor_font_size": 18,
|
||
"rule_editor_font_size": 18,
|
||
"panel_row_font_size": 16, // per-row summary/number labels
|
||
"panel_title_font_size": 18, // panel title labels
|
||
|
||
// NEW — style flags (bold via ui_font_bold / FontVariation.embolden):
|
||
"panel_title_bold": true,
|
||
"rule_label_bold": false,
|
||
"badge_bold": true,
|
||
|
||
// NEW — optional per-widget object form; overrides the flat size/style keys
|
||
// for that widget when present:
|
||
"action_popup": { "size": 24, "bold": false, "italic": false }
|
||
}
|
||
```
|
||
|
||
- A widget that has an object-form entry (e.g. `action_popup`) reads `{size, bold, italic}` from it,
|
||
falling back to the flat `*_font_size` / `*_bold` keys, then to the engine default.
|
||
- Bold/italic are realised via `FontVariation` (e.g. `variation_embolden`, or an OpenType slant)
|
||
applied to `ui_font`; a dedicated `ui_font_bold` / `ui_font_italic` path is honoured first.
|
||
- **`fonts.action_popup_emoji_size` is a currently-dead key** (shipped in `sandbox_theme.json` but
|
||
never read). **Decision: consume it** — apply it as the popup menu's emoji-glyph font size
|
||
alongside `_apply_popup_theme()` — rather than removing it: it is already shipped and removing it
|
||
would invalidate any user theme that sets it.
|
||
|
||
### 14.2 `apply_font` contract for the Phase 3c widgets
|
||
|
||
`QueuePanel`, `RulePanel`, `ActionEditor`, and `RuleEditor` are currently added to the UI canvas
|
||
with **no** font override (`SandboxStage._build_ui()`), so they render in the engine default font
|
||
and ignore the configured `ui_font` / `emoji_font`. Each gains an
|
||
`apply_font(ui_font: Font, emoji_font: Font, sizes: Dictionary)` method mirroring
|
||
`AssetSelector.apply_font()` (`asset_selector.gd`), which:
|
||
|
||
1. walks every `Control` it built in `_ready()` and applies the `ui_font` override (and `emoji_font`
|
||
for glyph/icon labels), and
|
||
2. applies the per-widget `*_font_size` / title / row size overrides and the `*_bold` style flags
|
||
(via the `FontVariation`-derived font).
|
||
|
||
`SandboxStage._build_ui()` calls each `apply_font(...)` **after** `add_child(...)` (the same
|
||
after-add ordering used for `_selector.apply_font(...)`, `sandbox_stage.gd:1462`), passing the
|
||
parsed `sizes` from `_load_theme()`. The `PopupMenu`s (`_rig_context_popup`, `_waypoint_context`)
|
||
keep using `_apply_popup_theme()`, extended to honour `action_popup_emoji_size` and the
|
||
`action_popup` object form.
|