stickman/docs/archive/plans/PHASE_9a_PROP_ATTACH.md

### 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.