feat: 3D skeletal animation system with GPU skinning and blending (#5)

* feat: add 3D skeletal animation system with GPU skinning and blending

* fix: address PR review — empty clips guards, bounds safety, material cache, bone upload clamp

* docs: update changelog with 3D animation system entries

Author: AngelMunoz

CHANGELOG.md

@@ -7,6 +7,14 @@
 - 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.).
+- `Animation3DClips` type for loading and querying 3D skeletal animation clips from `ModelAnimation[]`. Supports name-based and index-based lookup.
+- `Animation3DState` struct for per-entity 3D animation playback with `play`, `playByIndex`, `playIfNot`, `blendTo`, `blendToByIndex`, `update`, and `applyToModel`. Uses `UpdateModelAnimation` for single-clip playback and `UpdateModelAnimationEx` for crossfade blending.
+- `AnimatedMesh` type for shared GPU skinning data — extracts mesh and inverse bind pose from a `Model`. `computeBoneMatrices` performs pure keyframe interpolation (lerp/slerp) and inverse-bind-pose multiplication without mutating the model.
+- GPU skinning vertex shaders (`forwardVertexSkinned`, `depthShadowVertexSkinned`) using raylib's `vertexBoneIndices`/`vertexBoneWeights` attributes and `boneMatrices[128]` uniform.
+- `ForwardPbrPipeline.DrawSkinnedMesh` now uploads bone matrices and uses the GPU skinning shader (was a CPU skinning placeholder).
+- `IAssets.ModelAnimations: path: string -> ModelAnimation[]` for loading skeletal animations from glb/gltf/iqm files.
+- 42 unit tests for `Animation3DClips` and `Animation3DState` covering creation, playback, update, blending, and edge cases.
+- ThreeDSample: Player character (`character-oobi.glb`) now animates with idle/walk/jump animations and 0.15s crossfade transitions.
 
 ### Changed
 

samples/ThreeDSample/Program.fs

@@ -7,6 +7,7 @@ open Mibo.Elmish
 open Mibo.Elmish.Graphics2D
 open Mibo.Elmish.Graphics3D
 open Mibo.Elmish.Graphics3D.Pipelines
+open Mibo.Animation
 open Mibo.Input
 open ThreeDSample.Constants
 open ThreeDSample.Types
@@ -57,6 +58,14 @@ let init(ctx: GameContext) =
   let assets = GameContext.getService<IAssets> ctx
   model.JumpSound <- assets.Sound("assets/sfx_jump.ogg")
 
+  let playerModel = assets.Model(KenneyModels.characterOobi)
+  model.PlayerModel <- playerModel
+
+  let animClips = assets.ModelAnimations(KenneyModels.characterOobi)
+  let clips = Animation3DClips.fromModelAnimations animClips
+  model.PlayerAnimClips <- clips
+  model.PlayerAnim <- Animation3DState.create playerModel clips "idle" 60.0f
+
   let target = spawnPosition + Vector3(0.0f, playerHeight * 0.5f, 0.0f)
   model.CameraTarget <- target
 

samples/ThreeDSample/Systems.fs

@@ -6,6 +6,7 @@ open System.Numerics
 open Raylib_cs
 open Mibo.Elmish
 open Mibo.Elmish.Graphics3D
+open Mibo.Animation
 open Mibo.Input
 open Mibo.Layout3D
 open ThreeDSample.Constants
@@ -275,6 +276,32 @@ let inline diagnosticsSystem
   diag.ParticleCount <- model.Particles.Count
   struct (model, Cmd.none)
 
+let inline animationSystem
+  (dt: float32)
+  (model: GameModel)
+  : struct (GameModel * Cmd<Msg>) =
+  if model.PlayerAnim.Clips.Clips.Length = 0 then
+    struct (model, Cmd.none)
+  else
+    let isMoving =
+      model.Actions.Held.Contains(GameAction.MoveForward)
+      || model.Actions.Held.Contains(GameAction.MoveBackward)
+      || model.Actions.Held.Contains(GameAction.MoveLeft)
+      || model.Actions.Held.Contains(GameAction.MoveRight)
+
+    let targetAnim =
+      if not model.IsGrounded then "jump"
+      elif isMoving then "walk"
+      else "idle"
+
+    let anim =
+      model.PlayerAnim
+      |> Animation3DState.blendTo targetAnim 0.15f
+      |> Animation3DState.update dt
+
+    model.PlayerAnim <- anim
+    struct (model, Cmd.none)
+
 let inline lightingSystem
   (dt: float32)
   (model: GameModel)
@@ -370,6 +397,7 @@ let update (msg: Msg) (model: GameModel) : struct (GameModel * Cmd<Msg>) =
     System.start model
     |> System.pipeMutable(inputSystem dt)
     |> System.pipeMutable(physicsSystem dt)
+    |> System.pipeMutable(animationSystem dt)
     |> System.pipeMutable(chunkSystem dt)
     |> System.pipeMutable(particleSystem dt)
     |> System.pipeMutable(minimapSystem dt)

samples/ThreeDSample/Types.fs

@@ -7,6 +7,7 @@ open System.Numerics
 open Raylib_cs
 open Mibo.Elmish
 open Mibo.Elmish.Graphics3D
+open Mibo.Animation
 open Mibo.Input
 
 [<Struct>]
@@ -201,6 +202,11 @@ type GameModel() =
   member val Actions: ActionState<GameAction> = ActionState.empty with get, set
   member val InputMap: InputMap<GameAction> = InputMap.empty with get, set
   member val PlayerModel = Unchecked.defaultof<Model> with get, set
+
+  member val PlayerAnimClips =
+    Unchecked.defaultof<Animation3DClips> with get, set
+
+  member val PlayerAnim = Unchecked.defaultof<Animation3DState> with get, set
   member val ModelCache = Dictionary<string, Model>() with get, set
 
   member val Chunks =

samples/ThreeDSample/View.fs

@@ -9,6 +9,7 @@ open FSharp.NativeInterop
 open Raylib_cs
 open Mibo.Elmish
 open Mibo.Elmish.Graphics3D
+open Mibo.Animation
 open Mibo.Layout3D
 open ThreeDSample.Constants
 open ThreeDSample.Types
@@ -143,8 +144,7 @@ let view (ctx: GameContext) (model: GameModel) (buffer: RenderBuffer3D) =
         chunk.Grid
         buffer
 
-  let playerModel =
-    loadOrGetModel model.ModelCache KenneyModels.characterOobi ctx
+  let playerModel = model.PlayerAnim.Model
 
   let playerTransform =
     let rot = Raymath.MatrixRotateY(model.PlayerFacing)
@@ -158,6 +158,8 @@ let view (ctx: GameContext) (model: GameModel) (buffer: RenderBuffer3D) =
 
     Raymath.MatrixMultiply(rot, trans)
 
+  Animation3DState.applyToModel model.PlayerAnim
+
   let p = model.Particles
 
   for i = 0 to p.Count - 1 do