feat: add normal map support for 2D lit sprites (#4)

* feat: add normal map support for 2D lit sprites

Add per-pixel normal mapping to the 2D lighting pipeline using a
two-shader approach: one shader for standard lit sprites and one with
the normal map always sampled. The renderer switches between them via
BeginShaderMode, the correct raylib pattern for shader state changes.

Key changes:
- SpriteState gains a NormalMap field (Texture2D voption)
- LightContext2D manages two shader programs with independent location
  caches and uploads uniforms to both
- LitShader exports a normal-map fragment variant using Half-Lambert
  lighting (NdotL = max(1.0 + dot(normal.xy, L), 0)) for correct 2D
  behavior
- Renderer2D selects the shader variant per-sprite based on NormalMap
- New LightDraw.litAnimatedSprite helper for animated sprites
- SpriteState moved to top-level type for ergonomic use

* fix: address PR #4 review feedback

- Remove dead normal map code from standard shader (unused uniforms, getNormal)
- Mark LitSprite signature change as breaking in CHANGELOG
- Add FlipY handling to litAnimatedSprite

Author: AngelMunoz

CHANGELOG.md

@@ -1,8 +1,19 @@
 # Changelog
 
-[Unreleased]
+## [Unreleased]
 
-## [1.0.0] - 2026-05-30
+### Added
+
+- 2D normal map support: `SpriteState.NormalMap` field for per-pixel lighting on lit sprites. `LightContext2D` manages two shader variants (standard and normal-mapped) and switches between them via `BeginShaderMode`. The normal-map shader uses a 2D-compatible Half-Lambert lighting model (`NdotL = max(1.0 + dot(normal.xy, L), 0)`) for correct visual results with 2D light directions.
+- `LightDraw.litAnimatedSprite` helper for animated sprites with automatic flip handling.
+- `SpriteState` promoted to top-level type with builder DSL (`create`, `withNormalMap`, `withLayer`, etc.).
+
+### Changed
+
+- **Breaking:** `LitSprite` command signature changed — now carries `LightContext2D * SpriteState` instead of 8 individual fields. Consumers must update pattern matches and `LightDraw.litSprite` call sites to use the new `SpriteState` type.
+- `SpriteState` moved from `Command2D` module to top-level `Mibo.Elmish.Graphics2D` namespace.
+
+## [1.0.0] - 2026.05.30
 
 ### Added
 

samples/PlatformerSample/MinimapView.fs

@@ -147,15 +147,14 @@ let private viewInner
 
   if minimap.TexReady then
     buffer
-    |> Draw.sprite {
-      Texture = minimap.Texture
-      Dest = Rectangle(minimapX, minimapY, minimapSize, minimapSize)
-      Source = Rectangle(0.0f, 0.0f, float32 texSize, float32 texSize)
-      Origin = Vector2.Zero
-      Rotation = 0.0f
-      Color = Color.White
-      Layer = 1010<RenderLayer>
-    }
+    |> Draw.sprite(
+      SpriteState.create(
+        minimap.Texture,
+        Rectangle(minimapX, minimapY, minimapSize, minimapSize),
+        Rectangle(0.0f, 0.0f, float32 texSize, float32 texSize)
+      )
+      |> SpriteState.withLayer 1010<RenderLayer>
+    )
     |> Draw.drop
 
   let centerX = minimapX + halfMinimap

samples/PlatformerSample/Program.fs

@@ -8,6 +8,7 @@ open Mibo.Elmish.Graphics2D
 open Mibo.Elmish.Graphics2D.Lighting
 open Mibo.Input
 open Mibo.Animation
+open Mibo.Layout
 open PlatformerSample.Constants
 open PlatformerSample.Types
 open PlatformerSample.WorldGen
@@ -34,6 +35,7 @@ let loadAssets(ctx: GameContext) : SpriteAssets =
 
   let font = assets.Font("assets/Fonts/monogram.ttf")
   let jumpSound = assets.Sound("assets/sfx_jump.ogg")
+  let coinNormalMap = assets.Texture("assets/NormalMap.png")
 
   // White 1x1 texture for particles (black would multiply to zero)
   let particleImg =
@@ -43,7 +45,7 @@ let loadAssets(ctx: GameContext) : SpriteAssets =
   Raylib.UnloadImage(particleImg)
 
   let playerSheet =
-    SpriteSheet.fromFrames playerTex (Vector2(64.0f, 64.0f)) [|
+    SpriteSheet.fromFrames playerTex Vector2.Zero [|
       struct ("idle",
               {
                 Frames = [| r 645 0 128 128 |]
@@ -86,6 +88,7 @@ let loadAssets(ctx: GameContext) : SpriteAssets =
     TileTexture = tileTex
     TorchSheet = torchSheet
     ParticleTexture = particleTex
+    CoinNormalMap = coinNormalMap
     Font = font
     JumpSound = jumpSound
   }

samples/PlatformerSample/Types.fs

@@ -71,6 +71,7 @@ type SpriteAssets = {
   TileTexture: Texture2D
   TorchSheet: SpriteSheet
   ParticleTexture: Texture2D
+  CoinNormalMap: Texture2D
   Font: Font
   JumpSound: Sound
 }

samples/PlatformerSample/View.fs

@@ -163,15 +163,10 @@ let view (ctx: GameContext) (model: Model) (buffer: RenderBuffer2D) =
       r (int torch.Position.X - 16) (int torch.Position.Y - 32) 32 32
 
     buffer
-    |> LightDraw.litSprite model.Lighting {
-      Texture = model.Assets.TorchSheet.Texture
-      Dest = torchDest
-      Source = torchSrc
-      Origin = Vector2.Zero
-      Rotation = 0.0f
-      Color = Color.White
-      Layer = 7<RenderLayer>
-    }
+    |> LightDraw.litSprite
+      model.Lighting
+      (SpriteState.create(model.Assets.TorchSheet.Texture, torchDest, torchSrc)
+       |> SpriteState.withLayer 7<RenderLayer>)
     |> Draw.drop
 
   // Add occluders
@@ -218,45 +213,34 @@ let view (ctx: GameContext) (model: Model) (buffer: RenderBuffer2D) =
               let wy = chunk.Grid.Origin.Y + float32 y * tileSize
               let dest = Rectangle(wx, wy, tileSize, tileSize)
 
-              buffer
-              |> LightDraw.litSprite model.Lighting {
-                Texture = model.Assets.TileTexture
-                Dest = dest
-                Source = tileSpriteSrc chunkBiome tile
-                Origin = Vector2.Zero
-                Rotation = 0.0f
-                Color = Color.White
-                Layer = 10<RenderLayer>
-              }
-              |> Draw.drop)
+              let sprite =
+                let sprite =
+                  SpriteState.create(
+                    model.Assets.TileTexture,
+                    dest,
+                    tileSpriteSrc chunkBiome tile
+                  )
+                  |> SpriteState.withLayer 10<RenderLayer>
+
+                if tile = TileType.Coin then
+                  sprite
+                  |> SpriteState.withNormalMap model.Assets.CoinNormalMap
+                else
+                  sprite
+
+              buffer |> LightDraw.litSprite model.Lighting sprite |> Draw.drop)
           chunk.Grid
 
-  // Lit player sprite
-  let playerSrc = AnimatedSprite.currentSource model.PlayerSprite
-  let mutable playerSrcMut = playerSrc
-
-  if model.PlayerSprite.FlipX then
-    playerSrcMut <-
-      Rectangle(
-        playerSrcMut.X,
-        playerSrcMut.Y,
-        -playerSrcMut.Width,
-        playerSrcMut.Height
-      )
-
+  // Lit player sprite (uses litAnimatedSprite for automatic flip/normal map handling)
   let playerDrawY = int(model.PlayerPosition.Y + playerHeight - 64.0f)
   let playerDest = r (int model.PlayerPosition.X) playerDrawY 64 64
 
   buffer
-  |> LightDraw.litSprite model.Lighting {
-    Texture = model.Assets.PlayerSheet.Texture
-    Dest = playerDest
-    Source = playerSrcMut
-    Origin = Vector2.Zero
-    Rotation = 0.0f
-    Color = Color.White
-    Layer = 20<RenderLayer>
-  }
+  |> LightDraw.litAnimatedSprite
+    model.Lighting
+    20<RenderLayer>
+    playerDest
+    model.PlayerSprite
   |> Draw.drop
 
   // Particles
@@ -272,26 +256,28 @@ let view (ctx: GameContext) (model: Model) (buffer: RenderBuffer2D) =
   // End camera
   |> Draw.endCamera 1000<RenderLayer>
   // UI
-  |> Draw.text {
-    Font = model.Assets.Font
-    Text =
-      $"Day/Night Cycle | Time: {model.DayNightTimeOfDay:F1}h | Chunks: {model.Chunks.Count} | Score: {model.Score} | Pos: %.1f{model.PlayerPosition.X},%.1f{model.PlayerPosition.Y} | WASD/Arrows: Move | Space: Jump | R: Respawn"
-    Position = Vector2(10.0f, 10.0f)
-    FontSize = 20.0f
-    Spacing = 1.0f
-    Color = Color.White
-    Layer = 1001<RenderLayer>
-  }
-  |> Draw.text {
-    Font = model.Assets.Font
-    Text =
-      $"FPS: {model.Diagnostics.Fps} | Frame Time: {model.Diagnostics.FrameTime * 1000.0f:F1}ms"
-    Position = Vector2(10.0f, 32.0f)
-    FontSize = 20.0f
-    Spacing = 1.0f
-    Color = Color.White
-    Layer = 1001<RenderLayer>
-  }
+  |> Draw.text(
+    TextState.create(
+      model.Assets.Font,
+      $"Day/Night Cycle | Time: {model.DayNightTimeOfDay:F1}h | Chunks: {model.Chunks.Count} | Score: {model.Score} | Pos: %.1f{model.PlayerPosition.X},%.1f{model.PlayerPosition.Y} | WASD/Arrows: Move | Space: Jump | R: Respawn",
+      Vector2(10.0f, 10.0f)
+    )
+    |> TextState.withFontSize 20.0f
+    |> TextState.withSpacing 1.0f
+    |> TextState.withColor Color.White
+    |> TextState.withLayer 1001<RenderLayer>
+  )
+  |> Draw.text(
+    TextState.create(
+      model.Assets.Font,
+      $"FPS: {model.Diagnostics.Fps} | Frame Time: {model.Diagnostics.FrameTime * 1000.0f:F1}ms",
+      Vector2(10.0f, 32.0f)
+    )
+    |> TextState.withFontSize 20.0f
+    |> TextState.withSpacing 1.0f
+    |> TextState.withColor Color.White
+    |> TextState.withLayer 1001<RenderLayer>
+  )
   // Minimap
   |> Minimap.view ctx model
   |> Draw.drop

samples/PlatformerSample/assets/NormalMap.png

@@ -195,15 +195,14 @@ let private viewInner
 
   if minimap.TexReady then
     buffer
-    |> Draw.sprite {
-      Texture = minimap.Texture
-      Dest = Rectangle(minimapX, minimapY, minimapSize, minimapSize)
-      Source = Rectangle(0.0f, 0.0f, float32 texSize, float32 texSize)
-      Origin = Vector2.Zero
-      Rotation = 0.0f
-      Color = Color.White
-      Layer = 100<RenderLayer>
-    }
+    |> Draw.sprite(
+      SpriteState.create(
+        minimap.Texture,
+        Rectangle(minimapX, minimapY, minimapSize, minimapSize),
+        Rectangle(0.0f, 0.0f, float32 texSize, float32 texSize)
+      )
+      |> SpriteState.withLayer 100<RenderLayer>
+    )
     |> Draw.drop
 
   let centerX = minimapX + halfMinimap