ryan
00abacc7b2
- Implemented test_phase9a_prop_attach.gd to validate anchor schema, alignment math, and preview isolation. - Implemented test_phase9b_prop_centering.gd to check canonical origin presentation, bounds, centering, and save threshold. - Implemented test_phase9c_prop_editor_ux.gd to assess the user experience in the prop editor, including anchor renaming and UI responsiveness. - Added corresponding .uid files for each test. - Created sync_sources.py script to manage markdown file synchronization with the notebook. - Added .gitignore for virtual environment files.
131 lines
6.2 KiB
Markdown
131 lines
6.2 KiB
Markdown
# Architectural Plan: Dynamic `.prop` Loading & Sandbox Integration
|
|
|
|
This document outlines the architectural plan to transition `PropLibrary` from a static registry into a dynamic filesystem-backed library (matching `StickmanLibrary`) and integrate user-created `.prop` files into the Sandbox Stage.
|
|
|
|
---
|
|
|
|
## 1. System Architecture Overview
|
|
|
|
The system bridges custom prop files produced by the Prop Editor into the sandbox physics simulation through four primary layers:
|
|
|
|
1. **Library & File Scanning (`PropLibrary`):** Scans `res://props/` for `*.prop` files, deserializes them via `PropFile`, flattens multi-shape hierarchies into collision payloads, and merges them with built-in templates.
|
|
|
|
2. **Thumbnail Pipeline (`ThumbnailCache` & `PropThumbnail`):** Computes cache keys using file modification timestamps (`mtime`), renders visual previews offscreen, and streams textures to the selector grid.
|
|
|
|
3. **UI Integration (`AssetSelector` & `SandboxStage`):** Presents custom props alongside built-in presets in a unified grid, offering folder scanning, ad-hoc file browsing, and palette live-refresh.
|
|
|
|
4. **World Spawning & Physics Lifecycle (`StageSpawner` & `PropBlock`):** Instantiates `RigidBody2D` nodes configured with custom collision geometry and material physical properties (mass, friction, bounce), tracking authored positions across sandbox mode transitions.
|
|
|
|
---
|
|
|
|
## 2. Component Specifications
|
|
|
|
### A. Library Layer (`res://scripts/prop_library.gd`)
|
|
|
|
- **Dual-Source Registry:** Maintain built-in templates (Crate, Ball, Plank, Triangle) as default presets while scanning `res://props/*.prop` on demand.
|
|
|
|
- **Entry Model Schema:** Standardize entry dictionaries returned to the UI:
|
|
- **Identifier (`id`):** Resource path (`res://props/chair.prop`) for custom files, or string key (`crate`) for templates.
|
|
|
|
- **Display Name (`name`):** Extracted from `.prop` metadata, with fallback to capitalized file basename.
|
|
|
|
- **Material Preset & Label:** Physical properties index (Wood, Metal, Rubber, Cardboard) and human-readable label.
|
|
|
|
- **Payload (`payload`):** Flattened shape and collision dictionary generated via `PropFile.flatten_to_payload()`.
|
|
|
|
- **Provenance Flags:** Boolean flag indicating whether the entry is custom and string path reference for scene serialization.
|
|
|
|
- **Error Handling:** Skip invalid or corrupted `.prop` files gracefully while outputting descriptive warnings.
|
|
|
|
### B. Thumbnail Pipeline (`ThumbnailCache` & `PropThumbnail`)
|
|
|
|
- **Dynamic Keying Strategy:**
|
|
- Built-in prop templates compute keys using internal version constants.
|
|
|
|
- Custom `.prop` files compute keys combining file basename and filesystem modification timestamp (`FileAccess.get_modified_time`).
|
|
|
|
- **Renderer Extension (`PropThumbnail`):** Extend offscreen rendering to support composite shapes and custom vector styling (fill color, outline width, polygons, circles) rather than single primitive shapes.
|
|
|
|
- **Stale Cache Cleanup:** Automatically purge superseded PNG thumbnails when custom `.prop` files are edited or deleted.
|
|
|
|
### C. World Spawning Pipeline (`StageSpawner`)
|
|
|
|
- **Payload Forwarding:** Pass the entry payload directly to `PropUtils.spawn_prop()`, which generates the corresponding `PropBlock` node with `CollisionPolygon2D` or `CollisionShape2D` nodes.
|
|
|
|
- **Provenance Tagging:** Store `spawn_id` and source path metadata on spawned instances to support scene serialization and reloading.
|
|
|
|
- **Authored Pose Capture:** Save placement positions to instance metadata (`_authored_position`, `_authored_rotation`) during **Edit** mode.
|
|
|
|
### D. UI & Sandbox Integration (`AssetSelector` & `SandboxStage`)
|
|
|
|
- **Grid Population:** Trigger `PropLibrary.scan()` when opening the prop selector, populating grid cells with thumbnails and display names.
|
|
|
|
- **Browse & Refresh Integration:** Connect the "Browse…" button to a file dialog for arbitrary `*.prop` selection, and the "Refresh" button to re-scan `res://props/`.
|
|
|
|
- **Lazy Thumbnail Processing:** Process offscreen thumbnail generation non-blockingly during stage frame processing to keep UI interactions responsive.
|
|
|
|
---
|
|
|
|
## 3. Physics & Sandbox Lifecycle Integration
|
|
|
|
Custom `.prop` instances must follow the existing 3-mode sandbox state machine:
|
|
|
|
| Stage Mode | Prop Physics State | Interaction Capabilities | Reset Behavior |
|
|
| ---------- | -------------------------------------------------- | ------------------------ | -------------- |
|
|
| **Edit** | RigidBody frozen (`freeze = true`, kinematic mode) |
|
|
|
|
| Move, rotate, scale, or delete via selection gizmos
|
|
|
|
| N/A (Authored state recorded on movement)
|
|
|
|
|
|
|
| **Direct** | RigidBody frozen (`freeze = true`, kinematic mode)
|
|
|
|
| Gizmos active for rule/trigger assignment; spawner palette hidden
|
|
|
|
| N/A
|
|
|
|
|
|
|
| **Play** | RigidBody unfrozen (`freeze = false`)
|
|
|
|
| Full physical simulation, collisions with terrain/stickmen/props
|
|
|
|
| Mode exit restores initial authored position/rotation and zeroes linear/angular velocity
|
|
|
|
|
|
|
|
|
---
|
|
|
|
## 4. Implementation Roadmap
|
|
|
|
```
|
|
[ Phase 1: Library & Data Layer ]
|
|
└─ Extend PropLibrary (res://props/*.prop scanning + PropFile parsing)
|
|
└─ Define unified Prop Entry Dictionary schema
|
|
|
|
[ Phase 2: Thumbnail Pipeline ]
|
|
└─ Update PropThumbnail to render multi-shape custom payloads
|
|
└─ Implement modification timestamp cache invalidation in ThumbnailCache
|
|
|
|
[ Phase 3: Spawning & UI Integration ]
|
|
└─ Update StageSpawner to tag custom prop provenance
|
|
└─ Wire AssetSelector grid refresh and file dialog browsing
|
|
|
|
[ Phase 4: Stage Lifecycle & Verification ]
|
|
└─ Verify Edit -> Play -> Edit position resets for custom props
|
|
└─ Validate scene saving/loading persistence
|
|
|
|
```
|
|
|
|
### Milestone Checklist for Architect Agent
|
|
|
|
1. **Directory Scanning:** `PropLibrary` reads `res://props/` and extracts payloads via `PropFile`.
|
|
|
|
2. **Visual Previews:** `PropThumbnail` renders multi-polygon custom vector props to textures.
|
|
|
|
3. **Palette Display:** `AssetSelector` displays merged built-in templates and `.prop` files.
|
|
|
|
4. **Physics Interaction:** Custom props unfreeze during **Play** mode, participating in physics simulation and collision events.
|
|
|
|
5. **State Reset:** Props return to their original authored transforms when switching from **Play** back to **Edit** mode.
|