Merge pull request #1 from AngelMunoz/fix/single-directional-light

feat: shadow atlas with multi-light support and performance improvements

Author: AngelMunoz

AGENTS.md

@@ -23,6 +23,7 @@ The core abstractions of the library MUST NOT incur performance penalties for us
 - Prefer structs over classes unless struct size is too large.
 - Prefer object expressions to classes.
 - Avoid heap allocations in hot paths.
+- If implementing an interface, use a struct instead of a class or object expression if that object is going to be in a hot path
 - Favor arrays and spans over lists.
 - Favor ArrayPool over allocating new arrays where possible.
 - Favor functional programming patterns but allow mutable state when necessary for performance.
@@ -60,3 +61,47 @@ Each section may contain the following categories:
 - Security
 
 When adding entries to the changelog, make sure to follow format and categories.
+
+## raylib-cs / F# Quirks
+
+### DisableRuntimeMarshalling + void* Bug
+
+The project uses `[<DisableRuntimeMarshalling>]`. This affects how `SetShaderValue` and similar FFI calls work:
+
+- **DO NOT** pass raw `int`, `float32`, `Vector3` etc. directly as `void*` arguments. The runtime treats the value itself as a pointer address (e.g., passing `1` reads from address `0x1`, causing access violations).
+- **ALWAYS** use `fixed + NativePtr.toVoidPtr` for scalar/vec3/vec4 uniforms:
+
+```fsharp
+let setShaderInt (shader: Shader) (loc: int) (value: int) =
+    use p = fixed &value
+    Raylib.SetShaderValue(shader, loc, NativePtr.toVoidPtr p, ShaderUniformDataType.Int)
+```
+
+- **EXCEPTION**: `SetShaderValueMatrix` takes `Matrix4x4` directly (not `void*`) — this works correctly.
+- **EXCEPTION**: `Rlgl.SetUniform` (raw rlgl) also requires `fixed + NativePtr.toVoidPtr`.
+
+### Matrix Conventions
+
+#### System.Numerics vs raylib struct layout
+
+`Matrix4x4` in System.Numerics stores rows contiguously in memory: `m00 m01 m02 m03 m10 m11 m12 m13 ...`
+
+raylib's `rlMatrix` stores columns contiguously: `m0 m4 m8 m12 m1 m5 m9 m13 ...`
+
+`rlMatrixToFloatV` reorders from raylib's struct layout to GLSL column-major order (fields m0→m1→m2→...→m15). This means:
+- `SetShaderValueMatrix` and the batch's `glUniformMatrix4fv` both go through `rlMatrixToFloatV` — **they match**.
+- Do NOT manually blit a `Matrix4x4` to float arrays — use `rlMatrixToFloatV` for correct conversion.
+
+#### Vector4.Transform vs GLSL mat*vec
+
+- `Vector4.Transform(v, M)` computes `v * M^T` (transposed convention)
+- GLSL `M * v` computes `M * v` (standard convention)
+- These give **different results** on the same matrix. Do not mix them.
+- For uniform passing, `SetShaderValueMatrix` handles conversion via `rlMatrixToFloatV` — this is correct regardless.
+
+#### VP Matrix Capture
+
+When capturing the View-Projection matrix for shadow mapping:
+- **MUST** capture inside `BeginMode3D` using `Rlgl.GetMatrixModelview() * Rlgl.GetMatrixProjection()`
+- This matches what the batch computes for `mvp` (for identity model transforms)
+- Precomputing VP outside `BeginMode3D` or using `Matrix4x4.CreateLookAt * CreatePerspectiveFieldOfView` may produce different results due to raylib's internal matrix adjustments

CHANGELOG.md

@@ -15,7 +15,6 @@
 - Render context uses camera state (BeginCamera/EndCamera) instead of hardcoding.
 - Configurable `maxPointLights` and `ShadowConfig` for CSM cascades.
 - `RenderBuffer3D` with `IDisposable` for `ArrayPool` return.
-
 - Initial port of Mibo from MonoGame to raylib-cs.
 - Core: `RaylibGame` runtime loop integrating Elmish architecture with raylib lifecycle.
 - Core: `Program` module for configuring init, update, renderers, and services.
@@ -25,7 +24,7 @@
 - Rendering: `Batch3DRenderer` for 3D rendering with custom Phong shader and lighting.
 - Rendering: 2D lighting system (ambient, point, directional lights with CPU accumulation).
 - Rendering: 3D lighting system (ambient, directional, point lights with GPU Phong shader).
-- Rendering: Post-processing pipeline with `PostProcessConfig` and embedded GLSL shaders.
+- Rendering: Post-processing pipeline with multi-pass `PostProcessPass` and embedded GLSL shaders.
 - Rendering: Default shader library (`DefaultShaders.fs`) with Phong and tint shaders.
 - Rendering: `ModelHelper.setMaterialShader` for patching model material shaders (required by raylib).
 - Input: `InputMap` and `ActionState` types for semantic input mapping.
@@ -34,7 +33,20 @@
 - Time: `FixedStep` configuration for deterministic physics/simulation steps.
 - Animation: `Mibo.Animation` module for 2D sprite animation with `SpriteSheet.fromFrames`, `SpriteSheet.fromGrid`, `AnimatedSprite.update`, and layer-sorted rendering via `RenderCmd2D.DrawSprite`.
 - Code-first level design: `Mibo.Layout` and `Mibo.Layout3D` modules for 2D and 3D grid-based levels (planned).
-
 - Documentation: Official documentation site with guides for all modules.
 - Sample: 2D Platformer with procedural terrain, sprite animation, day/night cycle, and dynamic lighting.
 - Sample: 3D Platformer with procedural levels, custom Phong shader, camera-relative controls, and day/night GPU lighting.
+
+### Changed
+
+- ThreeDSample: Minimap rendering now bakes blocks into a CPU-side `Image` + GPU `Texture2D` instead of emitting ~1600 individual `FillRect` commands per frame. The texture is rebuilt every N frames and drawn as a single `Sprite`, reducing per-frame draw calls from ~1600 to 5 (1 sprite + player marker + direction line + border).
+- ThreeDSample: Refactored `MinimapView` into proper MVU module (`Minimap`) with `MinimapModel`, `system`, and `view`. Block collection and texture baking moved from the view function into the update pipeline.
+- ThreeDSample: Moved text overlay from `View.fs` `DrawImmediate` escape hatch to a proper `Diagnostics` 2D module with `Command2D.text`. Both minimap and diagnostics share a single 2D renderer.
+- ThreeDSample: Sun/moon cycle now uses model time instead of hardcoded noon. Arc distance scales with loaded world size via `arcRadius`.
+- ThreeDSample: Mushroom light collection moved from `View.fs` to `mushroomLightSystem`. Lights stored as `PointLight3D` on the model, `CastsShadows = false` for performance.
+- ThreeDSample: Pre-computed lighting state (`LightingModel`) stored on `GameModel`, populated by `lightingSystem`. View reads from model instead of computing DayNight values.
+
+### Removed
+
+- Dead code cleanup: removed unused `PostProcessConfig` type, `Renderer2D.createWithConfig`, `Renderer3D.createWithConfig`, and empty `RenderCommand.fs`/`RenderContext.fs` stub files.
+- ThreeDSample: Removed dead `DayNight.State`, `DayNight.initial`, `DayNight.update` (never used).

samples/MinimalEvsm/MinimalEvsm.fsproj

@@ -0,0 +1,16 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net10.0</TargetFramework>
+  </PropertyGroup>
+
+  <ItemGroup><Compile Include="Program.fs" />
+    
+  </ItemGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Raylib-cs" Version="8.0.0" />
+  </ItemGroup>
+
+</Project>