stickman/docs/archive/plans/PHASE_10a_PROP_SCALING.md

Here is the revised architectural specification incorporating your exact adjustments for your architect agent:

---

Architectural Spec: Dual-Layer Prop Scaling System (Revised)

Status: implemented and user verified (2026-09-22).

This specification outlines the architecture for supporting prop scaling across two layers: permanent template scaling in the Prop Editor and contextual instance scaling in the Sandbox Stage.

---

1. System Architecture & Division of Responsibilities

  ┌─────────────────────────────────────────────────────────┐
  │                   PROP EDITOR (Phase 9)                 │
  │  • Permanent template geometry mutation                 │
  │  • Vertex & radius coordinate transformations           │
  │  • Anchor offset auto-scaling                           │
  │  • Stickman guide silhouette (Default: OFF)             │
  └────────────────────────────┬────────────────────────────┘
                               │ Saves .prop file
                               ▼
  ┌─────────────────────────────────────────────────────────┐
  │                  SANDBOX STAGE (Phase 10)               │
  │  • Contextual instance scaling via corner gizmos only   │
  │  • Locked aspect ratio (uniform scaling)                │
  │  • Physics mass decoupled from visual scale             │
  └────────────────────────────┴────────────────────────────┘

Layer	Target Entity	Operation Type	Scaling Behavior	Data Persistence
Prop Editor	Template Asset (.prop)	Permanent geometry mutation	Bakes scale into raw vector vertices, radii, and anchor offsets.	Persists into .prop file.
Sandbox Stage	Object Instance (PropBlock)	Node transform scaling	Pure gizmo scaling with locked aspect ratio.	Persists into .scene file (scale: { x, y }).

---

2. Prop Editor Implementation (Template Sizing)

A. Document Geometry Scale Tool

• Scope: Modifies raw geometry arrays (points for polygons/lines, radius for circles) in the shape stack.

• Anchor Recalculation: All registered anchor offset positions (x, y) automatically multiply by the scale factor so grip, pivot, and emitter points maintain exact relative alignment.

• Normalize Size Action: Adds a canvas action (📏 Normalize Size) alongside 🎯 Center Prop that computes the bounding box union of all shapes and uniformly scales the document to fit within a standard 96 \times 96\text{ px} canvas box.

B. Stickman Visual Reference Silhouette

• Overlay Guide: Renders a semi-transparent 1:1 Stickman figure silhouette on the canvas background for scale context against full character rigs (\approx 336 \times 940\text{ px}).

• Default State: Toggleable via the UI / canvas controls and defaults to OFF.

• View Aid Only: Non-selectable, non-interactive visual guide that is excluded from .prop file serialization.

---

3. Sandbox Stage Implementation (Instance Sizing)

A. Gizmo-Driven Scaling (No UI SpinBoxes / No Presets)

• Corner Scale Handles: Extends StageGizmos in EDIT mode to render corner cross handles on selected prop bounding boxes.

• Aspect Ratio Locking: Dragging any corner handle scales the object while strictly locking the aspect ratio (uniform scaling).

• Streamlined UI: No numeric scale SpinBoxes or preset buttons (S/M/L) are added to the stage UI; all scaling is performed intuitively directly on the canvas via gizmo manipulation.

B. Mode Lifecycle & Physics Rules

• Decoupled Mass Contract: Scaling a prop adjusts node visual geometry (Polygon2D, Line2D) and collision bounds (CollisionPolygon2D, CollisionShape2D). RigidBody mass remains independent, governed strictly by the assigned Material Preset (Wood, Metal, Rubber, Cardboard).

• Lifecycle State Handling (PLAY \rightarrow EDIT): Transitioning from PLAY back to EDIT mode restores the authored position and rotation and zeroes linear/angular velocity, but does not reset or alter the node scale. The authored scale set during editing is retained as-is.

---

4. Implementation Roadmap

1. Phase A (Prop Editor Tooling):

• Implement document-wide geometry and anchor scaling logic in PropEditor.

• Add the toggleable Stickman Reference Silhouette (default OFF) and "Normalize Size" canvas button.

2. Phase B (Sandbox Gizmo Scaling):

• Extend StageGizmos with corner scale handles that lock aspect ratio during drag operations.

• Ensure StageSelection AABB bounding boxes recalculate accurately to account for scaled instances.

3. Phase C (Persistence & Verification):

• Verify scene save/load serialization of scaled PropBlock instances.

• Confirm that EDIT \rightarrow PLAY \rightarrow EDIT mode switches restore authored position/rotation while keeping object scale intact.

5. Verified final Prop Editor controls

The Arrange mode top bar presents these controls in order:

1. Transform Whole Prop
2. Normalize Size
3. Center Prop
4. Show Stickman Guide

The numeric scale textbox and Apply Scale button were removed. Transform Whole Prop previews and commits whole-document move, rotation, and uniform resize gestures around the canonical origin. Grid Snap rounds move deltas, Ctrl snaps rotation to 15-degree increments, editable anchors follow the geometry, and Esc cancels an active preview. Normalize Size fits the shape-point bounds to a 96 px maximum dimension. Transform Whole Prop and Normalize Size are hidden in Reshape and Attach; Center Prop and Show Stickman Guide remain available in all modes.

Sandbox instance scaling remains a separate prop-only uniform corner-gizmo operation. It retains the authored scene scale, preset-governed mass, and PLAY-to-EDIT position/rotation restoration behavior.