render iteration

blender/scripts/README.md

@@ -0,0 +1,139 @@
+# Blender Export Scripts
+
+Python scripts for generating textures and heightmaps from Blender terrain meshes.
+
+## Prerequisites
+
+- Blender 5.0+
+- Terrain mesh object (default name: "TerrainPlane")
+
+## Scripts
+
+### generate_heightmap.py
+
+Bakes EXR heightmap from terrain mesh using Blender's render system.
+
+**Output:** `textures/terrain_heightmap.exr` (R32Float single-channel)
+
+**Usage:**
+```python
+# In Blender's Scripting workspace - just run the script!
+# It will automatically find TerrainPlane and bake to textures/terrain_heightmap.exr
+```
+
+**Or run from command line:**
+```bash
+blender terrain.blend --background --python scripts/generate_heightmap.py
+```
+
+**Custom parameters:**
+```python
+from generate_heightmap import bake_heightmap
+
+bake_heightmap(
+    terrain_obj=bpy.data.objects["TerrainPlane"],
+    resolution=1000,
+    output_path="path/to/output.exr"
+)
+```
+
+### generate_normal_map.py
+
+Generates normal map from terrain mesh for neighbor sampling in shaders.
+
+**Output:** `textures/terrain_normals.png` (RGB encoded normals)
+
+**Usage:**
+```python
+from generate_normal_map import save_normal_map
+
+save_normal_map(
+    output_path=project_root / "textures" / "terrain_normals.png",
+    resolution=1024,
+    blur_iterations=2,
+    terrain_name="TerrainPlane"
+)
+```
+
+### generate_flowmap.py
+
+Generates flowmap for water/snow flow effects.
+
+**Output:** `textures/terrain_flowmap.png`
+
+## Terrain Export Workflow
+
+1. **Model terrain in Blender 5.0**
+   - Create/sculpt terrain mesh
+   - Add modifiers (Subdivision, Displacement, etc.)
+   - Ensure terrain has UV mapping
+
+2. **Bake heightmap**
+   - Run `generate_heightmap.py` script
+   - Uses Blender's baking system (like baking a texture)
+   - Creates `textures/terrain_heightmap.exr`
+   - Automatically applies all modifiers
+
+3. **Export glTF with baked heights**
+   - Select terrain mesh
+   - File → Export → glTF 2.0
+   - Save as `meshes/terrain.gltf`
+   - Heights are baked in vertex positions
+
+4. **Both files in sync**
+   - glTF: rendering (vertices with baked heights)
+   - EXR: physics (rapier3d heightfield collider)
+   - Both from same source = guaranteed match
+
+## Resolution Guidelines
+
+- **Heightmap (EXR):** 512×512, 1000×1000, or 1024×1024
+  - Higher = more accurate collision
+  - Lower = faster loading
+  - Default: 1000×1000
+  - Uses Blender's render sampling (no gaps!)
+
+- **Normal Map:** 1024×1024 or 2048×2048
+  - For shader neighbor sampling
+  - Higher quality for detailed terrain
+
+## Customization
+
+Change parameters by editing the script or calling directly:
+
+```python
+from generate_heightmap import bake_heightmap
+
+bake_heightmap(
+    terrain_obj=bpy.data.objects["MyTerrain"],
+    resolution=1024,
+    output_path="custom/path.exr"
+)
+```
+
+## Output Files
+
+```
+project_root/
+├── meshes/
+│   └── terrain.gltf        # Mesh with baked heights (manual export)
+└── textures/
+    ├── terrain.exr         # Heightmap for physics (generated)
+    ├── terrain_normals.png # Normal map (generated)
+    └── terrain_flowmap.png # Flow map (generated)
+```
+
+## Troubleshooting
+
+**"Object not found":**
+- Ensure terrain object exists
+- Check object name matches parameter
+- Script will auto-detect objects with "terrain" or "plane" in name
+
+**"Mesh has no vertices":**
+- Apply all modifiers before running script
+- Check mesh is not empty
+
+**EXR export fails:**
+- Ensure Blender has EXR support enabled
+- Check output directory exists and is writable