b3dLoadPoseMesh

Loads mesh with multiple pose/shape key states for morphing animations. Takes filename (path to mesh file with pose/shape key data as String, typically GLB/GLTF with morph targets), textureSlots (number of texture slots to allocate, typical 1-4), uvMode (UV coordinate handling mode, implementation-specific), unique (1 = create unique mesh instance, 0 = share mesh data if already loaded). Returns entity handle as Int with pose data attached (standard entity handle with additional pose/morph target data, 0 or negative on failure).

Pose/shape keys: alternative to skeletal animation (vertex morphing instead of bone transforms, blend between multiple mesh shapes, useful for facial expressions, muscle flexing, cloth wrinkles), each pose = different vertex positions for same mesh topology (same vertex count, vertices move between poses). Mesh poses: file contains base mesh + multiple pose targets (pose 0 = neutral/base, pose 1 = smile, pose 2 = frown, etc, blend between poses for smooth transitions).

Pose data: stored in mesh file (GLB/GLTF morph targets, custom pose format), mesh vertex positions vary per pose (interpolated at runtime for smooth morphing), use b3dSetPose to activate specific pose. Parameters: textureSlots (number of texture channels, affects material setup, typical 1 for diffuse, 2-4 for diffuse+normal+etc), uvMode (UV handling, implementation-specific, check documentation), unique (0 = share mesh if file already loaded for memory savings, 1 = always create new unique instance for independent manipulation).

Use cases: (1) Character facial animation (smile, frown, blink, talk expressions), (2) Muscle simulation (flex, relax muscle deformation), (3) Cloth wrinkles (different fold states), (4) Morph effects (smooth transformation between shapes). Common patterns: load character with face poses (head = b3dLoadPoseMesh("character_head.glb", 1, 0, 0), contains neutral/smile/frown/blink poses), switch expressions (b3dSetPose(head, smilePose) to show smile).

Morph target animation: play through poses (interpolate poseIndex over time for smooth animation), blend multiple poses (weighted average of multiple pose states, requires custom implementation or animation system), scripted poses (set pose based on game state, character emotion, player proximity). Performance: pose morphing CPU cost (vertex positions interpolated per frame, more expensive than skeletal animation, suitable for facial detail), GPU skinning possible (some implementations offload morphing to GPU shaders).

File format: GLB/GLTF standard (supports morph targets natively, multiple mesh shapes in single file, widely supported by 3D tools), custom pose format (BambooBasic-specific, check exporter/documentation). Validation: returns 0 or negative if file not found or invalid format, returns entity handle if successful with pose data attached.

Related: b3dSetPose sets active pose/shape key for entity, b3dLoadMesh loads standard mesh without pose data (use for static meshes, b3dLoadPoseMesh for morphing meshes), b3dLoadAnimMesh loads skeletal animated mesh (alternative animation method).