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

# Change an NPC for one player

> Give one player a different appearance, animation or head pose while others keep seeing the shared NPC.

A quest giver can wave at the player talking to it while everyone else sees its normal idle
animation. A personal presentation creates that private visual copy for one player.
The shared NPC remains the parent; it still supplies the position and common state.

Use the `NpcHandle` from the earlier guides as `npc`, and the connected player in the same
instance as `player`.

## Change only scale or glow

You do not need a private animation for a simple appearance change:

```java theme={null}
import gg.grounds.npc.minestom.viewer.NpcViewerState;

npc.applyViewerState(player, new NpcViewerState(1.3, true));
```

Only that player sees the NPC scaled to 1.3 and highlighted. Call
`npc.clearViewerState(player)` to restore the shared appearance. Both calls return stages;
observe their failures using the error handling from the earlier guides.

## Give the player a private animation

First prepare a private copy. Keep its start token so you can cancel it if the player leaves
before preparation finishes:

```java theme={null}
import gg.grounds.npc.minestom.presentation.NpcPresentationOptions;
import gg.grounds.npc.minestom.presentation.NpcPresentationResult;
import java.util.concurrent.CompletableFuture;

var personal = npc.preparePresentation(NpcPresentationOptions.builder(player).build());
var ready = personal.ready().thenCompose(result -> {
    if (!(result instanceof NpcPresentationResult.Ready prepared)) {
        return CompletableFuture.<gg.grounds.npc.minestom.presentation.NpcPresentationHandle>
                failedFuture(new IllegalStateException("Personal NPC rejected: " + result));
    }
    var handle = prepared.getHandle();
    return handle.publish().thenApply(unused -> handle);
});
ready.whenComplete((handle, error) -> {
    if (error != null) {
        error.printStackTrace();
        personal.cancel().whenComplete((unused, cleanupError) -> {
            if (cleanupError != null) cleanupError.printStackTrace();
        });
    }
});
```

After publication, `ready.thenCompose(handle -> handle.playClip("wave"))` starts a wave
only for this player. Observe that returned stage too. Private clips advance through the
library's own clock; do not attach the shared `NpcAnimations` helper to them.

## Return to shared behavior

| Call on the private handle | What the player sees |
| - | - |
| `playClip("wave")` | A private wave. Other players keep their own view. |
| `applyHeadLook(35, -15)` | A private head direction. |
| `followSharedClip()` | The shared NPC's current animation and time again. |
| `followSharedHeadLook()` | The shared head direction again. |
| `stopClip()` | Private idle or rest; the private channel stays allocated. |
| `closeAsync()` | Private displays disappear and the shared NPC becomes visible again. |

Keep the start token until cleanup completes. `personal.cancel()` also handles a copy that
has not become ready. Await it during your application's disconnect/teardown handling.
The [runnable example](https://github.com/groundsgg/library-npc/tree/v2.0.0/examples/standalone-minestom)
shows a session owner that handles repeated commands, disconnects and cancellation.

## Keep private sounds private

Set `sounds(...)` on `NpcPresentationOptions.builder(player)` to send cues only to the supplied
recipient. Use `recipient.playSound(...)`, rather than your shared nearby-player callback.
The default private sound callback is silent. Closing a copy cannot stop audio already sent
to the Minecraft client.

## Reconnects and server transfers

A presentation belongs to a concrete `Player` connection, not an account UUID. Cancel and
remove the old session on disconnect. A reconnect or backend transfer needs a new local
presentation on the destination server.

In a network with multiple proxies, use your network's presence/routing data to find the
player's current backend. The NPC library does not perform that lookup or forward handles
between servers. Another proxy's player must not be treated as locally connected.


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