Bone Snapshots

BoneSnapshots are GeckoLib's method of storing bone transformations for animations.

Overview

In the past, GeckoLib has allowed developers to directly modify GeoBones when animating. This has long been a source of consistency and concurrency issues, and especially in recent times has resulted in a number of mostly unfixable bugs.

In GeckoLib5, BoneSnapshots were redesigned to act as the sole owner of all transformations a given bone has had applied for a render pass.

Ideology

The idea behind BoneSnapshots is that when the RenderPassInfo renders a model for the first time in a render pass, it computes all the modifications for each bone, and stores them in BoneSnapshots.

This means that the render pass can be re-run at any time, in any order, and as many times as needed, and animations only need to be computed once. Additionally, it means that the bone holds no record of its modifications; and can't possibly leak into other rendered animatables.

At the end of the render pass, all BoneSnapshots are discarded entirely, leaving a clean slate.

Usage

When the GeoRenderer begins a render pass, it calls #adjustModelBonesForRender.
Users wanting to animate bones manually for a render pass should override this.

@Override
public void adjustModelBonesForRender(RenderPassInfo<R> renderPassInfo, BoneSnapshots snapshots) {

}

The BoneSnapshots object is provided to provide users access to the bones for animating.
See below for an example of animating a bone manually using BoneSnapshots.

Example Usage

Below, we animate the bone named "MyBoneName" by rotating it 45 degrees.

@Override
public void adjustModelBonesForRender(RenderPassInfo<R> renderPassInfo, BoneSnapshots snapshots) {
    snapshots.ifPresent("MyBoneName", boneSnapshot -> {
        boneSnapshot.setRotX(45 * Mth.DEG_TO_RAD);
    });
}

info

It is generally recommended to avoid using manual bone manipulation via BoneSnapshots, and instead incorporate it into Molang variables and do it via JSON animations.