refactor: Update architect and spec-pipeline documentation for clarity and detail; add new Prop Editor plan
This commit is contained in:
@@ -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.
|
||||
"""
|
||||
@@ -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."_
|
||||
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user