Creature Visuals And Animation
Pick The Smallest Hook
Section titled “Pick The Smallest Hook”Choose the lightest visual hook that matches the job:
| Need | Use |
|---|---|
| Swap a packaged visuals scene | CharacterAssetProfile.Scenes.VisualsPath or MonsterAssetProfile.VisualsScenePath |
| Use static frame cues | VisualCueSet on CharacterAssetProfile |
| Build the node tree in code | Override TryCreateCreatureVisuals() |
| Drive combat animations yourself | Override SetupCustomCombatAnimationStateMachine(...) |
| Drive merchant / rest-site visuals | Override SetupCustomMerchantAnimationStateMachine(...) or WorldProceduralVisuals |
Start with paths and profiles. Move to factories only when static resources cannot express the behavior.
Visual Cues
Section titled “Visual Cues”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.
State Machines
Section titled “State Machines”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.
Practical Notes
Section titled “Practical Notes”- 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.