Skip to content

Creature Visuals And Animation

Choose the lightest visual hook that matches the job:

NeedUse
Swap a packaged visuals sceneCharacterAssetProfile.Scenes.VisualsPath or MonsterAssetProfile.VisualsScenePath
Use static frame cuesVisualCueSet on CharacterAssetProfile
Build the node tree in codeOverride TryCreateCreatureVisuals()
Drive combat animations yourselfOverride SetupCustomCombatAnimationStateMachine(...)
Drive merchant / rest-site visualsOverride SetupCustomMerchantAnimationStateMachine(...) or WorldProceduralVisuals

Start with paths and profiles. Move to factories only when static resources cannot express the behavior.

VisualCueSet is useful for non-Spine characters that can be described by named stills or frame sequences.

public override CharacterAssetProfile AssetProfile => new()
{
VisualCues = new VisualCueSet(
texturePathByCue: new Dictionary<string, string>
{
["idle"] = "res://MyMod/images/character/idle.png",
["hit"] = "res://MyMod/images/character/hit.png",
})
};

Keep cue names aligned with the animation states your model or state machine will request.

Use ModAnimStateMachines or ModAnimStateMachineBuilder when you need explicit animation state transitions.

protected override ModAnimStateMachine? SetupCustomCombatAnimationStateMachine(
Node visualsRoot,
CharacterModel character)
{
return ModAnimStateMachines.Standard(
CompositeBackendFactory.FromNode(visualsRoot));
}

Return null when the normal vanilla animation path should run.

  • Keep visual resources in the mod PCK and reference them with res://.
  • Register Godot scripts before any scene is instantiated.
  • Use one visible fallback pose for every non-Spine creature.
  • Test death, hit, attack, cast, idle, and relaxed states before release.
  • For merchant and rest-site visuals, verify both normal UI entry and reload-from-save paths.