docs: Document mesh shadow limitation (Task A.1 investigation)

1 files changed, 50 insertions, 0 deletions

diff --git a/doc/DEBUG_SHADOWS.md b/doc/DEBUG_SHADOWS.md
new file mode 100644
index 0000000..bcf6d3e
--- /dev/null
+++ b/doc/DEBUG_SHADOWS.md
@@ -0,0 +1,50 @@
+# Shadow Rendering Analysis
+
+## Issue
+In `test_mesh` (and the engine generally), shadows cast by `ObjectType::MESH` objects onto the floor (or other objects) appear as simple bounding boxes, not matching the mesh geometry.
+
+## Root Cause
+The engine uses **Hybrid Rendering**:
+1.  **Visibility**: Meshes are rasterized using the GPU graphics pipeline (`mesh_render.wgsl`).
+2.  **Shadows**: Shadows are calculated using **SDF Raymarching** in the fragment shader (`calc_shadow` in `shadows.wgsl`).
+
+To calculate shadows, the shader needs to query the distance to every object in the scene (`map_scene`).
+For SDF primitives (Sphere, Box, Torus), we have exact mathematical distance functions.
+For arbitrary Meshes, calculating the exact Signed Distance Field (SDF) in the shader is computationally expensive and complex (requires BVH in shader or 3D texture).
+
+Current implementation in `assets/final/shaders/render/scene_query.wgsl`:
+```wgsl
+fn get_dist(p: vec3<f32>, obj_params: vec4<f32>) -> f32 {
+    // ...
+    if (obj_type == 5.0) { return sdBox(p, obj_params.yzw); } // MESH AABB
+    return 100.0;
+}
+```
+`obj_params.yzw` contains the local extents (half-size) of the mesh's AABB.
+Thus, **all meshes are approximated as Boxes in the shadow/SDF pass.**
+
+## Implications
+- **Shadow Casting**: Meshes cast box-shaped shadows.
+- **Shadow Receiving**: Meshes receive shadows correctly (from other objects' SDFs).
+- **Self-Shadowing**: Disabled via `skip_idx` to prevent the mesh from being shadowed by its own proxy box.
+
+## Potential Solutions
+
+### 1. Shadow Mapping (Recommended for future)
+Render the scene depth from the light's perspective into a texture.
+- **Pros**: Exact shadows for rasterized geometry; handles self-shadowing naturally.
+- **Cons**: Requires additional render pass, potential bias artifacts, doesn't integrate perfectly with soft SDF shadows (though can be combined).
+- **Status**: Tracked as **Task #40**.
+
+### 2. Mesh SDF Baking
+Pre-calculate a 3D texture containing the SDF of the mesh and sample it in the shader.
+- **Pros**: Accurate soft shadows, integrates with existing SDF system.
+- **Cons**: High memory usage (3D textures), requires tooling to bake SDFs (e.g. `mesh_to_sdf` tool).
+
+### 3. Analytic Proxies
+Manually assign a better proxy shape (e.g. combination of spheres/boxes) for specific meshes.
+- **Pros**: Cheap, better than box.
+- **Cons**: Manual labor, limited fidelity.
+
+## Conclusion
+The current "bounding box shadow" behavior is a known limitation of using an AABB as the SDF proxy for meshes. It is not a bug in the code, but a simplified implementation choice for the 64k intro constraints. Accurate shadows require implementing Shadow Mapping (Task #40).