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

{
  "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.