# Animation

SimVX provides four animation systems, from simple to complex.

## Tweens

Animate any property over time with easing:

```python
from simvx.core import tween
from simvx.core.animation import ease_out_quad

# Basic tween (runs as a coroutine)
self.start_coroutine(
    tween(self, "position", Vec3(10, 0, 0), duration=1.0, easing=ease_out_quad)
)

# With callbacks and repeat
yield from tween(
    node, "rotation", Quat.from_euler(0, 360, 0),
    duration=2.0,
    delay=0.5,
    repeat=3,
    on_complete=lambda: print("Done!"),
)
```

### Tween Chains

Chain sequential animations fluently:

```python
from simvx.core.animation import TweenChain, ease_in_out_quad

TweenChain(obj, "position", Vec3(0, 0, 0)) \
    .to(Vec3(10, 0, 0), 1.0, ease_in_out_quad) \
    .wait(0.5) \
    .to(Vec3(0, 0, 0), 1.0) \
    .on_complete(lambda: print("Loop!")) \
    .build()
```

## Easing Functions

30 built-in easing curves:

| Family | In | Out | In-Out |
|--------|----|-----|--------|
| Linear | `ease_linear` | | |
| Quad | `ease_in_quad` | `ease_out_quad` | `ease_in_out_quad` |
| Cubic | `ease_in_cubic` | `ease_out_cubic` | `ease_in_out_cubic` |
| Quart | `ease_in_quart` | `ease_out_quart` | `ease_in_out_quart` |
| Quint | `ease_in_quint` | `ease_out_quint` | `ease_in_out_quint` |
| Sine | `ease_in_sine` | `ease_out_sine` | `ease_in_out_sine` |
| Expo | `ease_in_expo` | `ease_out_expo` | `ease_in_out_expo` |
| Back | `ease_in_back` | `ease_out_back` | `ease_in_out_back` |
| Elastic | `ease_in_elastic` | `ease_out_elastic` | `ease_in_out_elastic` |
| Bounce | `ease_in_bounce` | `ease_out_bounce` | `ease_in_out_bounce` |

## Sprite Sheet Animation

For 2D frame-based animations:

```python
from simvx.core import AnimatedSprite2D

sprite = AnimatedSprite2D(
    texture="player.png",
    frames_horizontal=4,
    frames_vertical=4,
)
sprite.add_animation("walk", frames=[0, 1, 2, 3], fps=10, loop=True)
sprite.add_animation("jump", frames=[4, 5, 6], fps=15, loop=False)
sprite.play("walk")
```

## Keyframe Clips

Timeline-based animation with multiple property tracks:

```python
from simvx.core import AnimationClip, AnimationPlayer

clip = AnimationClip("jump", duration=1.0)
clip.add_track("position", [
    (0.0, Vec3(0, 0, 0)),
    (0.5, Vec3(0, 5, 0)),
    (1.0, Vec3(0, 0, 0)),
])

player = AnimationPlayer(target=my_node)
player.add_clip(clip)
player.play("jump", loop=True)
```

## Animation State Machine

Transition between animations based on conditions:

```python
from simvx.core import AnimationTree

tree = AnimationTree(target=character)
tree.add_state("idle", idle_clip, loop=True)
tree.add_state("run", run_clip, loop=True)
tree.add_state("jump", jump_clip, loop=False)

tree.add_transition("idle", "run", lambda: tree.parameters["speed"] > 0.1)
tree.add_transition("run", "idle", lambda: tree.parameters["speed"] < 0.1)

tree.set_parameter("speed", 0.0)
tree.start("idle")
```

## API Reference

See {py:mod}`simvx.core.animation` for the complete animation API.