b3dLoadAnimMesh

Loads skeletal animated mesh from file (.glb/.gltf, supports skinned meshes with skeleton and animations). Takes filename (mesh path, .glb/.gltf formats), textureSlots (BBR_ONE_SLOT to BBR_FOUR_SLOT, number of material slots), uvMode (BBR_NO_TEXTURE_UV or BBR_TEXTURE_UV, UV mapping mode), unique (0 = shared geometry for GPU instancing, 1 = unique copy independent geometry). Returns entity handle (ENTITY_ANIMATED_MESH type, 0 if failed). Loads geometry (vertices, normals, UVs, tangents, joint indices, joint weights), skeleton (joint hierarchy, bind pose, inverse bind matrices), animations (keyframes, channels, duration), creates GPU buffers (vertex/index buffers, joint matrices constant buffer). Use for character animation (player characters, NPCs, creatures), skeletal meshes (rigged models with bones), or any animated 3D models (exported from Blender, Maya, 3DS Max). Mesh caching: unique=0 enables cache (geometry shared across instances, GPU instancing, minimal memory per instance), unique=1 bypasses cache (independent geometry copy, higher memory but fully independent). Cache key includes filename, textureSlots, and uvMode (different configurations cached separately, ensures compatibility). CloneAnimatedMesh used for instances (shared geometry, independent animation state, each instance animates separately). Use cases: (1) Character loading (player = b3dLoadAnimMesh("player.glb", BBR_FOUR_SLOT, BBR_TEXTURE_UV, 0) load player character), (2) Multiple NPCs (npc1 = b3dLoadAnimMesh("npc.glb", ..., 0) instances share geometry, animate independently), (3) Unique prop (unique_mesh = b3dLoadAnimMesh("prop.glb", ..., 1) independent mesh for modification), (4) Skeletal creatures (monster = b3dLoadAnimMesh("monster.glb", ..., 0) with walk/attack animations).

Skeletal animation system: skeleton defines joint hierarchy (joints = bones, parent-child relationships, bind pose transforms), skinning binds vertices to joints (vertex weights 0-1, up to 4 joints per vertex, smooth deformation), animations keyframe joint transforms (translation/rotation/scale over time, interpolated per frame), GPU computes final vertex positions (vertex shader multiplies by joint matrices, skinning matrix = sum of weighted joint transforms). cgltf library parses GLTF/GLB (industry standard 3D format, supports PBR materials, animations, skins), loads buffers (binary data for geometry and animation), finds all skinned meshes sharing same skeleton (combines into single AnimatedMesh3D, unified animation). Texture slots: BBR_ONE_SLOT = 1 material (single texture set, base color only), BBR_FOUR_SLOT = 4 materials (PBR textures, base color + normal + metallic/roughness + emissive), more slots = more GPU memory but richer materials. UV mode: BBR_NO_TEXTURE_UV = no UV mapping (vertex colors only, no textures), BBR_TEXTURE_UV = UV coordinates (enables texture mapping, standard for textured models). GPU instancing: shared geometry enables instancing (one set of vertex/index buffers, many instances, DrawInstanced calls), each instance has independent position/rotation/scale/animation (per-instance data in constant buffers), significant memory savings (100 characters = 1x geometry memory instead of 100x).

Animation data loaded: animations[] array (multiple animations per mesh, e.g., walk/run/jump/attack), each animation has duration (total length in seconds), channels (keyframes for each joint, separate translation/rotation/scale tracks), samplers (interpolation type, LINEAR/STEP/CUBICSPLINE). Skeleton data: joints[] array (joint hierarchy, parent indices, bind pose transforms, inverse bind matrices), joint matrices (4x4 transform matrices, uploaded to GPU constant buffer), max joints supported (typical limit 128-256 joints, depends on GPU constant buffer size). AnimatedMesh3D structure: mesh (Mesh3D geometry, vertices/indices/materials), joints (skeleton hierarchy, joint transforms), animations (keyframe data, multiple clips), currentTime (playback position, updated per frame), playing/looping/pingPong (playback state), speed (playback multiplier, 1.0 = normal speed), sequences (user-defined animation clips, frame ranges).

Typical workflow: load animated mesh (this function, returns entity handle), define animation sequences (b3dSetAnimSeq splits long animations into clips like walk/run/idle), play animation (b3dAnimateSeq starts playback with loop/pingpong mode), update per-frame (engine calls UpdateAnimations automatically, advances currentTime, interpolates keyframes), render (engine renders with GPU skinning, joint matrices uploaded to shader). Mesh requirements: must have skin (cgltf_skin, defines joint bindings), must have animations (cgltf_animation, keyframe data, or animation can be added later), vertices must have JOINTS_0 and WEIGHTS_0 attributes (joint indices and weights, defines skinning). Supported mesh features: multiple meshes per skeleton (combines into single AnimatedMesh3D, unified rendering), material slots (1-4 texture sets, PBR materials), tangents (for normal mapping, generated if missing), blend shapes/morph targets NOT IMPLEMENTED (only skeletal animation supported).

Performance: GPU instancing efficient (shared geometry, minimal memory per instance, typical 100 bytes per instance), GPU skinning (vertex shader computes final positions, CPU only updates joint matrices, fast ~0.1ms per character), animation blending (transition parameter enables smooth transitions, lerps between previous and current pose, short duration ~0.2s typical). Memory usage: shared geometry (unique=0, one copy of vertices/indices, ~1-10MB per mesh depending on complexity), per-instance data (position/rotation/scale/animation state, ~1KB per instance), joint matrices (uploaded to GPU, ~16 bytes per joint x num joints, typical 128 joints = 2KB). Validation: returns 0 if filename invalid (null pointer, empty string, file not found), returns 0 if file parse fails (corrupted GLB, unsupported format), returns 0 if no skinned meshes found (mesh has no skin, not an animated mesh), returns 0 if textureSlots invalid (must be BBR_ONE_SLOT to BBR_FOUR_SLOT, range 1-4), check return value (If animMesh = 0 Then error, handle failure). Silent failures: prints error to stderr (error messages for debugging, no user-facing alerts), no error code returned (only 0 on failure, no detailed error info).

Related: b3dLoadMesh loads static mesh (non-animated, no skeleton, simpler but no animation support), b3dSetAnimFPS sets global FPS (frame-to-time conversion for sequences, default 24 FPS), b3dSetAnimSeq defines animation sequence (splits long animation into clips like walk/run/idle), b3dAnimateSeq plays sequence (starts animation playback with loop/pingpong mode), b3dAnimate plays frame range (alternative to sequences, direct frame-based playback), b3dPositionEntity positions animated mesh (place in world, entity system integration), b3dRotateEntity rotates animated mesh (orient in world), b3dScaleEntity scales animated mesh (adjust size).