> ## Documentation Index
> Fetch the complete documentation index at: https://docs.grounds.gg/llms.txt
> Use this file to discover all available pages before exploring further.

# Animate, move and play sounds

> Make the example bot wave, turn its head, move and play a sound for nearby players.

Start with the bot from [your first NPC](https://docs.grounds.gg/reference/libraries/npc/getting-started.md).
Use the `NpcHandle` returned by `firstNpc.ready()` as `npc` in the examples below.
A shared change is visible to every player watching that NPC.

## Play an animation

A model contains named clips. The example bot has `idle` and `wave`.
Calling `npc.playClip("wave")` selects the clip, but your application must also advance its time.

The quickstart ZIP includes `src/main/java/example/npc/NpcAnimations.java`.
It installs one repeating task on the owning instance and measures elapsed time with a
monotonic clock. Keep it with your NPC so you can cancel the task later:

```java theme={null}
import example.npc.NpcAnimations;

NpcAnimations animations = new NpcAnimations(instance, npc);
animations.play("wave").whenComplete((unused, error) -> {
    if (error != null) error.printStackTrace();
});
```

The bot should make its wave gesture. `animations.play("idle")` switches to its idle clip.
The helper resets its clock only after an admitted start. If an NPC cannot start the clip,
the returned stage fails and the current clock continues.

The helper samples elapsed **real time** once per instance tick. A busy server can skip visual
samples; elapsed animation time still follows the monotonic clock. It waits for an old
frame to finish before switching clips and skips ticks while the new start is pending.

## Turn the head and move the NPC

Head angles are degrees. This changes the head pose without turning the whole body:

```java theme={null}
npc.applyHeadLook(20, -10).whenComplete((unused, error) -> {
    if (error != null) error.printStackTrace();
});
```

To move it, supply a new world transform:

```java theme={null}
import gg.grounds.npc.core.math.NpcTransform;
import gg.grounds.npc.core.math.NpcVector3;
import gg.grounds.npc.minestom.transform.NpcRenderTransform;

var destination = new NpcRenderTransform(new NpcTransform(new NpcVector3(2, 40, 0)), null);
npc.applyTransform(destination).whenComplete((unused, error) -> {
    if (error != null) error.printStackTrace();
});
```

The example bot moves two blocks along X. Adapt the coordinates to your world.

## Make a clip audible

Sound cues describe *what* to play. Your application decides *who* hears them; the default
sound callback is silent. The example bot binds `wave` to the Vanilla event
`minecraft:entity.villager.yes`.

Use `NpcSounds.java` from the quickstart ZIP, then create the NPC with that callback:

```java theme={null}
import example.npc.FirstNpc;
import example.npc.NpcSounds;
import java.nio.file.Path;
import net.minestom.server.coordinate.Pos;

FirstNpc firstNpc = FirstNpc.spawn(instance, Path.of("npc"), new Pos(0, 40, 0), NpcSounds::near);
```

Once it is ready, start `wave` through your animation helper. Players within the cue's radius
on this instance hear it. The callback uses the cue's volume and pitch. Custom sound files
must also be present in the resourcepack.

## Stop and remove

`npc.stopClip()` selects the rest pose. To return to an authored idle animation, call
`animations.play("idle")` instead.

Before removing the NPC, stop its animation driver:

```java theme={null}
animations.close();
firstNpc.closeAsync().toCompletableFuture().get(5, java.util.concurrent.TimeUnit.SECONDS);
```

Do this in your host shutdown path, outside the instance tick. See
[application integration](https://docs.grounds.gg/reference/libraries/npc/integration.md) for handling several NPCs,
cancellation and cleanup failures.

Continue with [changes for one player](https://docs.grounds.gg/reference/libraries/npc/personal-presentations.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.