𦴠Skeletal Animation
Imported glTF skins become an ImportedSkin plus a
SkinnedPose component; the engine samples clips, blends them and skins
vertices on the CPU.
Overview#
There are two related layers:
- Runtime and editor path β
assets/MeshLoader.cppimports a glTF skin intoImportedSkin(skeleton, bones and clips). An entity with a skinned mesh gets aSkinnedPose, andtickSkinnedPosesresolves the pose each frame. This is the path used by Doppio's timeline, the Animator panel and the runtime. - Standalone primitives β
SkeletalAnimation.hppprovidesBone,Skeleton,SkeletalClip,SkeletalAnimatorandSkeletalAnimationSystemfor direct sampling and tests. It is compiled and tested, but the renderer does not consumeSkeletalAnimator; useSkinnedPosefor scene characters.
Both share the same Bone / Skeleton / SkeletalClip types.
API#
namespace Caffeine::Animation {
struct Bone {
FixedString<32> name;
i32 parentIndex = -1; // -1 = root
Mat4 bindPoseInverse;
Mat4 localTransform; // bind-pose local TRS
};
struct Skeleton {
std::vector<Bone> bones;
Mat4 skinSpace; // inverse of the skinned mesh node
u32 boneCount() const;
i32 findBone(const char* name) const;
};
struct SkeletalKeyframe {
f32 time = 0.0f;
Vec3 position {0.0f, 0.0f, 0.0f};
Quat rotation {Quat::identity()};
Vec3 scale {1.0f, 1.0f, 1.0f};
};
struct SkeletalClip {
FixedString<32> name;
f32 duration = 0.0f;
f32 fps = 30.0f;
bool loop = true;
HashMap<u32, std::vector<SkeletalKeyframe>> channels; // bone -> keys
void sampleAt(f32 time, const Skeleton& skeleton,
std::vector<Mat4>& boneTransforms,
std::vector<Vec3>* jointPositions = nullptr) const;
};
struct BlendNode {
enum class Type : u8 { Clip, Blend1D, Blend2D };
Type type = Type::Clip;
const SkeletalClip* clip = nullptr;
std::vector<std::pair<f32, BlendNode*>> children;
f32 parameter = 0.0f;
};
struct SkeletalAnimationState {
FixedString<32> name;
const SkeletalClip* clip = nullptr;
f32 speed = 1.0f;
std::vector<AnimationTransition> transitions;
};
struct SkeletalAnimator {
const Skeleton* skeleton = nullptr;
std::vector<Mat4> boneMatrices;
HashMap<FixedString<32>, SkeletalAnimationState> states;
FixedString<32> currentState;
f32 timeInState = 0.0f;
f32 blendWeight = 1.0f;
bool paused = false;
BlendNode* blendTree = nullptr;
};
class SkeletalAnimationSystem : public ECS::ISystem {
public:
void onUpdate(ECS::World& world, f32 dt) override;
void play(ECS::World& world, ECS::Entity e, const char* stateName);
void pause(ECS::World& world, ECS::Entity e);
void resume(ECS::World& world, ECS::Entity e);
void setSpeed(ECS::World& world, ECS::Entity e, f32 speed);
bool isPlaying(ECS::World& world, ECS::Entity e, const char* stateName) const;
};
} // namespace Caffeine::Animation
Import and pose path#
namespace Caffeine::Animation {
struct ImportedSkin {
Skeleton skeleton;
std::vector<std::string> boneNames;
std::vector<SkeletalClip> clips;
std::vector<std::string> clipNames;
const Assets::Mesh3D* mesh = nullptr;
bool synthesized = false;
};
void registerImportedSkin(const std::string& path, ImportedSkin skin);
const ImportedSkin* findImportedSkin(const std::string& path);
bool synthesizeHumanoidSkin(const std::string& path, Assets::Mesh3D& mesh,
bool replace = false);
struct SkinnedPose {
char meshPath[260] = {};
i32 clipIndex = 0;
f32 time = 0.0f;
f32 speed = 1.0f;
bool playing = false;
bool editorHeld = false; // clears on load; Play starts the clip
bool loop = true;
bool loaded = false;
bool sampleKeys = false; // timeline keys replace the sampled pose
HumanoidRig humanoid;
std::vector<BonePose> offsets;
std::vector<BoneKeyframe> keys;
std::vector<ObjectKeyframe> objectKeys;
std::vector<i32> removedBones;
std::vector<ClipStrip> strips;
std::vector<PoseLayerMix> overrideMix;
u64 overrideFrame = 0;
bool timelineHold = false;
};
SkinnedPose* ensurePoseForMesh(ECS::World& world, ECS::Entity entity,
const std::string& projectRoot);
void tickSkinnedPoses(ECS::World& world, f32 dt);
} // namespace Caffeine::Animation
Note. In the low-level SkeletalAnimationSystem,
setSpeed() currently writes SkeletalAnimator::blendWeight, not a
clip playback rate. Use SkeletalClip::sampleAt directly when you need a
specific time.
tickSkinnedPoses chooses the pose source in this order: the timeline's
overrideMix, then the entity's Animator layers, then the inspector's single
clipIndex. It then skins the bind mesh into the entity's posed vertices and writes
joint positions for the viewport overlay.
Vertex Skinning#
Skinning is CPU-side and runs in parallel chunks:
VertexSkin (per vertex, imported):
u16 joints[4]
f32 weights[4]
skinVertices(bindMesh, boneMatrices, outVertices):
for each vertex:
p = Ξ£ weights[i] * boneMatrices[joints[i]] * bindPosition
n = Ξ£ weights[i] * boneMatrices[joints[i]] * bindNormal
skinVertices copies the texture coordinates and tangent through and writes position
and normal. There is no GPU skinning shader in the current renderer; the posed vertex
buffer is uploaded like any other mesh.
SkeletalClip::sampleAt:
- Loops or clamps
timebased onloopandduration. - Interpolates position and scale linearly and rotation with
Quat::slerp. - Resolves bones even when a parent appears after its child in the joint list.
- Computes
skinSpace * world * bindPoseInversefor each bone.
Exemplos de Uso#
// ββ Inspect an imported clip ββββββββββββββββββββββββββββββββββ
const ImportedSkin* skin = Caffeine::Animation::findImportedSkin("characters/hero.gltf");
if (skin && !skin->clips.empty()) {
std::vector<Mat4> bones(skin->skeleton.boneCount());
skin->clips[0].sampleAt(0.5f, skin->skeleton, bones);
}
// ββ Attach a pose to an entity ββββββββββββββββββββββββββββββββ
SkinnedPose* pose = Caffeine::Animation::ensurePoseForMesh(world, hero,
projectRoot);
if (pose) {
pose->clipIndex = 1;
pose->loop = true;
pose->editorHeld = false; // allow playback
}
// ββ Drive the state graph through the Animator ββββββββββββββββ
Animator& animator = world.add<Animator>(hero);
animator.defaultState = "Idle";
// states, transitions and parameters are shared with the 2D path.
// ββ Tick poses once per frame before rendering ββββββββββββββββ
Caffeine::Animation::tickSkinnedPoses(world, dt);
matchHumanoid maps common Mixamo/Unity bone names into HumanoidBone slots and is
used automatically for imported skins unless HumanoidRig::manual is set.
Acceptance Criteria#
tests/test_skeletal_animation.cpp covers:
- [x] Default skeleton, keyframe and blend-node state
- [x]
findBonelookup - [x]
sampleAton an empty clip and between keyframes - [x] Looping wraps time and non-looping clamps at the end
- [x] Parent transforms propagate to children
- [x] Rotation interpolation uses slerp
- [x] Mixamo bone names map to humanoid slots
- [x] CPU skinning moves a weighted vertex
- [x] A static glTF does not get an automatic humanoid skin
- [x] Explicit
synthesizeHumanoidSkinstill works
No frame-rate target is asserted by the suite.
Dependencies#
- Upstream: Animation System, 3D Math, Mesh Loading
- Downstream: Doppio timeline, viewport joint overlay, runtime characters
Static meshes and fitted humanoid rigs#
A glTF without skins is a static mesh. Caffeine does not synthesize a humanoid rig
automatically when the Animator or Inspector binds it. synthesizeHumanoidSkin builds a
T-pose humanoid from the mesh bounds only when a tool calls it explicitly; models with
authored glTF skins import their bones and clips directly.
π Related Topics#
| Topic | Description |
|---|---|
| Animation System | Sprite clips and the shared Animator graph |
| Mesh Loading | glTF import and the mesh cache |
| ECS Core | Components and queries |
References#
src/caffeine/animation/SkeletalAnimation.hppβ bones, clips and the low-level systemsrc/caffeine/animation/SkinLibrary.hppβ imported skins, humanoid rigs andSkinnedPosesrc/caffeine/assets/MeshLoader.cppβ glTF skin importtests/test_skeletal_animation.cppβ behaviour suite