refactor: Update architect and spec-pipeline documentation for clarity and detail; add new Prop Editor plan
This commit is contained in:
@@ -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