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

# Migrate the NPC API

> Move an existing application to NPC 2.0.0 and select a compatible Scene adapter.

## From NPC 1.1 to 2.0

Use `2.0.0` for every selected NPC module. This release adds shared clip admission,
reservations and optional sound-duration metadata. The four-argument Java `NpcClipSound`
constructor remains available; Kotlin data-class copy signatures changed. Recompile consumers
rather than replacing a JAR beneath already compiled Kotlin code.

If you use Scene, select `scene-npc-minestom:1.0.1`. Ordinary hosts do not need to build Scene,
Lobby or Dialogue to use the standalone NPC library.

## From NPC 0.2

NPC `1.0.0` intentionally breaks source and JVM signatures from `0.2.0`.
Schema-1 model JSON, resource IDs and authored units remain compatible. Recompile Java and Kotlin
consumers against one matching released dependency set.

## Update packages and construction

| Previous API | Redesigned API |
| - | - |
| Model types at `gg.grounds.npc.core` | `gg.grounds.npc.core.model` |
| Vectors, matrices and transforms at the core root | `gg.grounds.npc.core.math` |
| Clips, keyframes and sampling at the core root | `gg.grounds.npc.core.animation` |
| JSON decoder, limits and decode results at the core root | `gg.grounds.npc.core.io` |
| `NpcProblem` at the core root | `gg.grounds.npc.core.validation.NpcProblem` |
| Minestom options, transforms, viewer state and callbacks at its root | `.config`, `.transform`, `.viewer` and `.spi` |
| Personal types at the Minestom root | `gg.grounds.npc.minestom.presentation` |
| Positional optional options constructors and `copy` | `builder(requiredValues).property(value).build()` and `toBuilder()` |
| Loop/interpolation strings in numeric definitions | `NpcLoopMode` and `NpcInterpolation` |
| Nested track string maps | Bone-ID map of `NpcBoneTrack(position, rotation, scale)` |
| Clip `.length` and keyframe `.time` | `.lengthSeconds` and `.timeSeconds` |

Options are immutable construction results. Preparation rejections defensively copy a nonempty
diagnostic list and no longer expose data-class `copy` or destructuring.

## Update lifecycle and animation calls

| Previous call | Redesigned call |
| - | - |
| `startAnimation(id, millis)` | `playClip(id, millis)`; `playClip(id)` starts at zero |
| `advanceAnimation(millis)` | `advanceClipTo(millis)` with absolute clip-local milliseconds |
| `stopAnimation(null)` | `stopClip()` |
| `stopAnimation(id)` | `stopClipIfPlaying(id)` |
| `NpcPresentations.prepare(parent, options)` | `parent.preparePresentation(options)` |

Retain preparation tokens before asynchronous readiness, publish hidden handles explicitly and
await cancellation on every failed installation path. `closed()` observes final cleanup without
closing. Custom or delegating `NpcHandle` implementations forward `preparePresentation` directly.

Keep numeric sampling in seconds, shared command time in milliseconds, and rotations in degrees.
Shared playback still needs a host clock; private playback uses the library's monotonic clock.

## Update an application

1. Select released NPC `2.0.0` modules in your build.
2. Update an optional Scene NPC adapter to `1.0.1` and recompile the host.
3. Run your normal application tests, then check model appearance, animation, sound,
   reconnects and cleanup with the matching client pack.

Scene `0.5.0` is the older adapter for NPC `0.2.0`; it cannot be mixed with the redesigned
NPC API. See [installation](https://docs.grounds.gg/reference/libraries/npc/installation.md) for package access and
[advanced workflows](https://docs.grounds.gg/reference/libraries/npc/advanced.md) if you maintain the libraries themselves.


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