---
name: ferret-transform
description: Use to swap what an entity looks like and how it animates in Ferret (mesh, skeleton, graph, movement values) while keeping position and AI state: Transformer, ZoneTransform and effects such as particleBurst, scalePulse and combine.
---

# Transformation of characters

## 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