stickman/docs/archive/plans/PHASE_10_PROP_INTEGRATION.md

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.