119 lines
6.6 KiB
Markdown
119 lines
6.6 KiB
Markdown
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.
|