From e3689c86c866eab8fc3c50b493d7323f8264dae1 Mon Sep 17 00:00:00 2001 From: Ryan Kegel Date: Sun, 20 Sep 2026 00:26:11 -0400 Subject: [PATCH] refactor: Update architect and spec-pipeline documentation for clarity and detail; add new Prop Editor plan --- .codex/agents/architect.toml | 54 ++++++--- .codex/skills/spec-pipeline/SKILL.md | 21 ++-- plans/PHASE_9a_PROP_ATTACH.md | 167 +++++++++++++++++++++++++++ 3 files changed, 219 insertions(+), 23 deletions(-) create mode 100644 plans/PHASE_9a_PROP_ATTACH.md diff --git a/.codex/agents/architect.toml b/.codex/agents/architect.toml index bb27340..55fdc12 100644 --- a/.codex/agents/architect.toml +++ b/.codex/agents/architect.toml @@ -1,28 +1,52 @@ name = "architect" -description = "Defines system requirements, evaluates architectural choices, and suggests technical improvements for Godot features." +description = "Evaluates architectural choices, proposes Godot 4 best practices, asks interactive clarification questions, and writes implementation specs." model = "gpt-5.6-sol" model_reasoning_effort = "high" sandbox_mode = "read-only" developer_instructions = """ -You are the Lead Systems Architect. Refer to `AGENTS.md` for project directory standards and coding rules. +You are the Lead Systems Architect specializing in Godot 4 and idiomatic GDScript. Refer to `AGENTS.md` for project directory standards and coding rules. ## Responsibilities - -1. **Analyze:** Read existing code patterns before designing. -2. **Critique & Innovate:** Proactively identify edge cases, performance bottlenecks, or over-engineered designs. Offer superior alternative architectures or simpler GDScript patterns if you identify a better path. -3. **Design:** Define API payload shapes, GDScript type hints, and signal flows. +1. **Analyze:** Read existing code patterns and node structures before designing. +2. **Critique & Innovate:** Identify edge cases, performance bottlenecks, or over-engineered designs. Offer superior GDScript patterns (e.g., Custom Resources, Component-based Nodes, Signal Bus, State Machines) if a better path exists. +3. **Design:** Define API payload shapes, static GDScript type hints, node hierarchies, and signal flows. 4. **Log:** Append trade-offs to `docs/tech_debt_and_optimizations.md`. -## Workflow +--- -1. **Scope, Critique & Clarify:** Ask up to 3 high-impact questions if requirements are ambiguous. If you see a simpler, more performant, or more scalable way to implement the feature, pitch it briefly before finalizing the spec. -2. **Spec Creation:** Output a minimal specification containing: - - Target Nodes / Classes modified. - - Signal interfaces & static type contracts. +## TWO-PHASE WORKFLOW + +### PHASE 1: Scope, Critique & Pitch (DEFAULT FIRST TURN) +Unless explicitly instructed by the prompt to "Skip clarification and build spec immediately," DO NOT write to `specs/[feature-name].md` during your first response. + +Instead, analyze the requirement and output a **Clarification & Architecture Brief**: + +1. **Clarification Questions (Up to 3):** + - Identify structural ambiguities (e.g., node hierarchy, state handling, physics, static vs. dynamic loading). + - For every question, present 2–3 choices and explicitly mark your recommended choice with `[Recommended]`. + +2. **Godot 4 Architectural Ideas & Best Practices:** + - Pitch 1–3 engine-specific optimizations or architectural alternatives (e.g., leveraging `Resource` scripts for data separation, Composition over Inheritance, custom signals vs. direct calls). + - Briefly explain *why* each option improves scalability, memory, or developer ergonomics. + +3. **Stop & Await Input:** + - End with a request for the user to confirm the recommended defaults, choose alternatives, or approve suggested additions. + +--- + +### PHASE 2: Spec Creation & Handoff (AFTER USER FEEDBACK) +Once the user responds to Phase 1 (or approves the pitch), perform the following: + +1. **Generate Spec:** Output the complete specification into `specs/[feature-name].md` containing: + - Target Nodes / Classes modified (with full static typing `class_name` contracts). + - Signal interfaces & static payload shapes. - Layout/Theme updates required. - - **Visual Diagrams & Schematics:** Include ASCII diagrams or Mermaid charts illustrating node hierarchies, state transitions, or signal flow interactions. - - **Concrete Examples & Data Flows:** Provide code/data examples demonstrating practical usage, sample dictionary shapes, or step-by-step state transformations. - - **Architectural Suggestions & Alternatives:** (Optional/Required if applicable) Highlight alternative approaches, potential pitfalls, or future-proofing ideas that improve the feature. -3. **Handoff:** Save to `specs/[feature-name].md` and display a summary including key diagrams and practical examples, then stop for user approval. + - **Visual Diagrams & Schematics:** ASCII diagrams or Mermaid charts illustrating node hierarchies, state transitions, or signal interactions. + - **Concrete Examples & Data Flows:** Code snippets, sample dictionary/resource shapes, or step-by-step state transformations. + - **Architectural Trade-offs:** Document choices made based on user feedback. + +2. **Log Debt:** Append key architectural trade-offs to `docs/tech_debt_and_optimizations.md`. + +3. **Display Summary:** Summarize key diagrams and decisions in your final chat output and stop for user approval. """ \ No newline at end of file diff --git a/.codex/skills/spec-pipeline/SKILL.md b/.codex/skills/spec-pipeline/SKILL.md index 9561436..11a1c03 100644 --- a/.codex/skills/spec-pipeline/SKILL.md +++ b/.codex/skills/spec-pipeline/SKILL.md @@ -1,23 +1,28 @@ --- name: spec-pipeline -description: "Lean implementation loop: Architect -> Developer -> User Verification." +description: "Lean implementation loop: Architect (Clarify -> Spec) -> Developer -> User Verification." --- ## Execution Logic -1. **Phase 1: Architecture (Optional for small edits)** - - `@architect` defines signatures, node structures, or spec updates in `specs/[feature-name].md`. - - **STOP:** Wait for user approval on design choices before invoking developer. +1. **Phase 1a: Architecture Proposal & Clarification** + - `@architect` analyzes existing patterns, pitches 1–3 Godot best-practice ideas, and asks up to 3 clarification questions with `[Recommended]` options. + - `@architect` stops without writing the spec file yet. -2. **Phase 2: Implementation & Engine Validation** - - `@developer` updates code and scenes using targeted diffs/snippets. +2. **Phase 1b: User Feedback & Spec Generation** + - User approves, modifies, or selects choices from `@architect`'s proposal. + - `@architect` writes the finalized specification to `specs/[feature-name].md` and logs decisions in `docs/tech_debt_and_optimizations.md`. + - **STOP:** Wait for final user sign-off on the spec before invoking developer. + +3. **Phase 2: Implementation & Engine Validation** + - `@developer` updates code and scenes using targeted diffs/snippets based on `specs/[feature-name].md`. - `@developer` runs headless syntax verification: `& "C:\Godot4\Godot_v4.7.1-stable_win64_console.exe" --headless --check-only --script "res://path/to/script.gd" --path "C:\Godot4\project"` - If static check fails, `@developer` fixes the code immediately. -3. **Phase 3: User Hand-off (Stop)** +4. **Phase 3: User Hand-off (Stop)** - Present the changes to the user to test inside the Godot Editor. - Do NOT update READMEs or documentation yet. -4. **Phase 4: Documentation (Triggered manually by user)** +5. **Phase 4: Documentation (Triggered manually by user)** - Only call `@writer` after the user confirms: _"Feature verified and working."_ diff --git a/plans/PHASE_9a_PROP_ATTACH.md b/plans/PHASE_9a_PROP_ATTACH.md new file mode 100644 index 0000000..fe413a5 --- /dev/null +++ b/plans/PHASE_9a_PROP_ATTACH.md @@ -0,0 +1,167 @@ +### Objective Summary + +This revised plan details the addition of an **Attach** mode to the Prop Editor (`[ Arrange | Reshape | Attach ]`), introducing a flexible, **Role-Based Dynamic Anchor Architecture** for vector prop files (`.prop`). Instead of hardcoding weapon-centric anchors (like a fixed muzzle), anchors are defined as named dictionary entries assigned specific functional roles—such as `pivot`, `grip`, `emitter`, `impact`, or `mount`. Coupled with interactive canvas gizmos, a live semi-transparent Stickman Hand Preview silhouette, and `StickmanRig` IK attachment logic, this system allows any prop (from flashlights and magic staves to broadswords and rifles) to be held, flipped, and interacted with accurately across all facing profiles. + +--- + +### 1. Dynamic Role-Based Anchor Data Architecture (`.prop` Schema) + +The `.prop` JSON file stores anchors in a flexible dictionary where each key represents a unique anchor identifier and contains an explicit `"role"` attribute. + +#### JSON Data Layout + +```json +{ + "version": "1.0", + "prop_name": "Arcane Staff", + "anchors": { + "origin": { + "role": "pivot", + "x": 0.0, + "y": 0.0 + }, + "primary_grip": { + "role": "grip", + "x": 0.0, + "y": 18.0, + "rotation_deg": 0.0, + "z_index_offset": 1, + "allowed_hands": "both" + }, + "secondary_grip": { + "role": "grip", + "x": 0.0, + "y": -12.0, + "rotation_deg": 0.0, + "z_index_offset": 1, + "allowed_hands": "left_only" + }, + "crystal_head": { + "role": "emitter", + "x": 0.0, + "y": -48.0, + "rotation_deg": -90.0 + } + } +} +``` + +#### Key Parameter Schema + +- **`role`**: Enforced category enum (`pivot`, `grip`, `emitter`, `impact`, `mount`, `custom`) defining visual gizmo styling and runtime behavior. +- **`x`, `y**`: Pixel offset relative to the prop’s root origin point (0,0). +- **`rotation_deg`**: Angular rotation applied to the prop geometry when attached, aligning prop handles seamlessly with a stickman’s hand/wrist joint. +- **`z_index_offset`**: Integer sorting shift (e.g., -1 or +1) controlling whether prop elements render behind or in front of the holding hand. +- **`allowed_hands`**: Hand access permission (`both`, `left_only`, `right_only`) used during character interaction checks. + +#### Standard Anchor Role Registry + +- **`pivot`**: The mandatory root origin (0,0) used for spawning, ground collision, terrain placement, and linear/angular center-of-mass physics when thrown. +- **`grip`**: Hand attachment targets for primary or secondary holding locations. +- **`emitter`**: Action output coordinates for spell particles, flashlights/light cones, projectile spawns, spray nozzles, or laser beams. +- **`impact`**: Point-of-contact coordinates for melee striking edges, spear points, or hammer heads. +- **`mount`**: Auxiliary attachment locations for modular accessories, scopes, or vehicle mounts. + +--- + +### 2. UI Integration & 'Attach' Mode Setup + +#### Segmented Mode Switcher + +- Expand the canvas toolbar mode control to three tabs: **`[ Arrange | Reshape | Attach ]`**. +- Selecting **Attach** hides shape vertex handles and activates the anchor editing overlay. + +#### Attach Mode Toolbar + +- **Show Hand Overlay**: Toggle button to display/hide the semi-transparent stickman lower-arm and hand preview. +- **Snap to Grid**: Toggle button for snapping anchor translation coordinates. +- **Show Inactive Gizmos**: Toggle visibility for non-selected background anchors. + +#### Anchor Management Panel (Sidebar Inspector) + +- **Anchor List Control**: +- Scrollable list showing all defined anchors with **Add Anchor**, **Delete**, and **Rename** buttons. +- Ability to add dynamic custom anchors and assign them any standard role. + +- **Property Fields**: +- **Role Selector**: Dropdown menu (`Pivot`, `Grip`, `Emitter`, `Impact`, `Mount`, `Custom`). +- **Position Inputs**: Numeric fields for X and Y coordinates with arrow incrementors. +- **Rotation Slider**: Angle adjustment (-180° to +180°) with numeric spinbox. +- **Z-Index Offset**: Integer field (-5 to +5) for layer sorting relative to hands. +- **Allowed Hands**: Dropdown (`Both`, `Left Only`, `Right Only`). + +- **Quick Preset Generator**: Buttons to instantly apply standard layouts (e.g., _One-Handed Grip_, _Two-Handed Weapon_, _Tool / Extinguisher Nozzle_, _Melee Edge_). + +--- + +### 3. Canvas Visual Tools & Interactive Editing + +#### Role-Based Gizmo Markers + +Each anchor role renders with a distinct visual icon and color code on the canvas: + +- **`pivot`**: Yellow Crosshair (locked to or editable near origin). +- **`grip`**: Cyan / Orange Hand Icon (primary vs. secondary grips). +- **`emitter`**: Red Target Reticle (shows direction vector arrow for particle/beam orientation). +- **`impact`**: Bright Pink Diamond / Slash Marker (indicates tip or edge). +- **`mount`**: Purple Ring Anchor. + +#### Canvas Interaction Mechanics + +- **Translation Dragging**: Click and drag any anchor gizmo across the viewport with full grid-snap support. +- **Rotation Arc Ring**: Selecting a `grip` or `emitter` anchor displays a surrounding rotation ring handle. Dragging the ring dynamically dials in `rotation_deg` while updating the live inspector readout. + +#### Stickman Hand Preview Silhouette Overlay + +- **Visual Representation**: When enabled, draws a semi-transparent stickman lower-arm and hand silhouette attached directly to the currently selected `grip` anchor. +- **Real-Time Alignment**: +- The arm and hand rotate dynamically in response to `rotation_deg` adjustments. +- The preview respects `z_index_offset`, rendering the hand over or under prop geometry to give immediate visual feedback. +- Guarantees sword hilts, briefcase handles, and tool grips fit stickman hands before running gameplay tests. + +--- + +### 4. Rig Compatibility & Runtime Behavior (`StickmanRig`) + +- **IK Hand Attachment**: +- `StickmanRig` queries the prop's `grip` anchors during pick-up or equip actions, snapping the wrist joint of `LeftLowerArm` or `RightLowerArm` to the exact anchor location. + +- **Facing Profile Mirroring**: +- When a character flips (e.g., facing left with `scale.x = -1`), the prop mirrors along with the rig. +- Symmetrical anchor positioning ensures tools and weapons flip naturally without offset errors. + +- **Action & Effect Dispatching**: +- When firing, casting, or emitting light, runtime scripts search for anchors with the `emitter` role to instantiate particles, light nodes, or hitscan traces. +- Melee collision scripts query `impact` anchors to detect high-velocity hit points. + +- **Throwing Physics**: +- Dropping or throwing a prop applies linear/angular velocity calculations relative to the `pivot` anchor position. + +--- + +### 5. Implementation Roadmap + +1. **Anchor Data Model & JSON Updates**: + +- Refactor internal dictionary parsers to support role-based dynamic key schemas. +- Update `.prop` saving and loading procedures to serialize custom anchor entries and their `role` tags. + +2. **UI Switcher & Sidebar Panel**: + +- Add the `Attach` tab to the primary mode control `[ Arrange | Reshape | Attach ]`. +- Build the Anchor Management sidebar panel with role selectors, dynamic list controls, and property spinboxes. + +3. **Canvas Rendering & Gizmo Input**: + +- Implement canvas drawing routines for role-specific gizmos (`pivot`, `grip`, `emitter`, `impact`, `mount`). +- Add gizmo click-picking, drag translation, and rotation ring interaction handles. + +4. **Hand Preview Silhouette System**: + +- Create the semi-transparent lower-arm and hand preview overlay attached to `grip` anchors. +- Connect real-time rotation and Z-order sorting updates to the overlay renderer. + +5. **Autosave, Thumbnail & Runtime Verification**: + +- Hook anchor adjustments into editor dirty-state tracking, undo/redo stacks, and autosave routines. +- Verify exported `.prop` files in the asset selector preview and validate runtime IK snapping on the test stage.