ryan
0a7f97cec7
- Added specifications for Phase 10a, introducing permanent size changes to `.prop` documents and reversible uniform instance scaling in Sandbox EDIT mode. - Updated `PropCanvas`, `PropAnchorData`, `PropEditor`, `StageGizmos`, `SandboxStage`, and `StageSelection` classes to support new scaling features. - Implemented document transactions for scaling, including normalization to a 96 px maximum dimension. - Introduced a new **Transform Whole Prop** tool in the Prop Editor for moving, rotating, and resizing props. - Created unit tests for the new scaling functionality, validating shape scaling, anchor transformations, and whole-prop interactions. - Ensured compatibility with existing prop formats and maintained the integrity of the document structure during scaling operations.
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.
|