Transformation of characters

Skill ferret-transform · download all skills · SKILL.md

When to use#

A character becomes another (shape-shifting, disguises, power-ups), also on entering a zone.

The model#

Transformer swaps mesh, skeleton, animation graph and movement values from a TransformProfile, keeping position and AI state, with an Effect around the swap: particleBurst, scalePulse, instant, or combine of several. ZoneTransform does it on entering a zone.

Steps#

1. Describe each form as a TransformProfile (a Look, graph, movement values).
2. Add Transformer to the entity; call it with the profile and an effect.
3. For area-based swaps add ZoneTransform with the zone name (needs ZoneService).
4. Keep the animation graph compatible: same parameters or provide the new graph.

Check afterwards#

Position, health and AI state are unchanged after the swap; the new animation graph runs; swapping back restores the first form.

What usually goes wrong#

• A target skeleton without the clips the graph needs: retarget first (ferret-animation).
• Effects that outlive the swap: dispose with the effect context.
• Capsule size differences that put the character into a wall: choose movement values per form.

Files#

• reference/packages.md — Characters, animation graphs, NPC navigation, interactables, zones and transformations.
• reference/api-transform.md — every export of @ferret/transform with signature and doc comment