# Specification: Dynamic Vector Props (`PropBlock`)

**Objective:** Create a reusable, dynamic physics prop framework (`PropBlock`) using `RigidBody2D` with resolution-independent vector visuals (`Polygon2D`, `Line2D`) and configurable physics material profiles (mass, friction, bounce) that interact with `TerrainBlock` instances.

---

## 1. Reusable `PropBlock` Component (`RigidBody2D`)

- **Node Hierarchy:** A root `RigidBody2D` with three direct children: `Polygon2D` for interior visual fill, `Line2D` for crisp vector borders, and a physics collision node (`CollisionPolygon2D` for custom polygons or `CollisionShape2D` with a `CircleShape2D` for spheres).
- **Script Architecture:** `class_name PropBlock`, `extends RigidBody2D` equipped with `@tool` mode for live editor previewing.
- **Exported Properties:**
  - **Shape Parameters:** Shape type selector (Polygon vs. Circle), `polygon_points` (`PackedVector2Array`), and `radius` (`float`).
  - **Visual Styling:** `fill_color`, `outline_color`, and `outline_width` matching the stroke aesthetic of `TerrainBlock`.
  - **Physics Presets:** A preset selector or exported `PhysicsMaterial` handle for quick material assignment (e.g., _Wood Crate_, _Bouncy Rubber_, _Light Cardboard_, _Heavy Metal_).
- **Live Update Setter:** A unified property setter that updates visual fill and border geometry dynamically:
  - **Polygons:** Assigns `polygon_points` to `Polygon2D` and `CollisionPolygon2D` (`BUILD_SOLIDS`), closing the `Line2D` outline by appending the first vertex to the end with rounded line joints and caps.
  - **Circles:** Generates a smooth radial point loop for `Polygon2D` and `Line2D` while updating the radius of a `CircleShape2D` to maintain fast, accurate spherical collision.

---

## 2. `PropUtils` Factory & Preset Helper

- **Class Setup:** `class_name PropUtils`, `extends RefCounted` providing static utility methods for spawning dynamic props.
- **Primitive Generators:** Helper functions to programmatically build common prop primitives (e.g., `create_box()`, `create_ball()`, `create_plank()`, `create_triangle()`) with default vector dimensions and color themes.
- **Physics Material Presets:** Internal factory definitions for pre-configured `PhysicsMaterial` resources:
  - _Wood:_ Moderate mass, medium friction, low bounce.
  - _Rubber:_ Low mass, high friction, high restitution/bounce ($0.8+$).
  - _Metal:_ High mass, high friction, zero bounce.
- **Point Sanitization:** Any custom polygonal points passed to `PropUtils` should run through `TerrainUtils.sanitize_points()` to guarantee clockwise vertex order and strip collinear points before creating the prop.
- **Spawner Factory (`spawn_prop`):** Static function taking a target parent container, position, shape payload, and material preset to instantiate a `PropBlock`, set its initial velocity, and add it to the scene.

---

## 3. `PhysicsTestHarness` Staging Integration

- **Controls & Spawning:** Update `scripts/physics_test_harness.gd` to bind key inputs (or mouse clicks) for spawning dynamic props directly into the test world (e.g., Press `1` for Wood Crate, `2` for Bouncy Ball, `3` for Heavy Plank).
- **Physics Verification Checklist:**
  - **Vector Scaling & Zoom:** Ensure stroke weights and line join quality on dynamic props remain crisp and visually coherent with static terrain across camera zoom levels (0.25x to 3.0x).
  - **Collision Accuracy:** Verify dynamic props roll smoothly down angled ramps, bounce predictably off step ledges, and stack stably on flat terrain without clipping or falling through `TerrainBlock` geometry.
  - **Rig Interaction:** Confirm dynamic props collide accurately with the standing `MasterRig` instance on the ground.