stickman/plans/DYNAMIC_VECTOR_PROPS.md

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.