Load once, create several NPCs
Load and verify a prepared bundle during startup.content.getModels() is an immutable lookup;
you can reuse a selected NpcModel for several NpcSpawnRequest objects.
Each request chooses its own instance, position, sound callback and configuration.
FirstNpc.java loads files on each call to keep the first example self-contained. In your
application, move those two file operations into your content-loading service and pass the
selected model to the request builder. Keep blocking file work off the instance tick.
Keep an owner until removal finishes
Your application owns both the NPC and any repeating tasks it creates:- Keep the
NpcStartreturned byNpcRenderer.prepare(...)immediately. - Wait asynchronously for preparation. A ready handle is still hidden.
- Publish the handle, then allow application code to use it.
- Cancel your animation tasks and await
start.cancel()before stopping the instance.
FirstNpc wraps this sequence. Keep one such owner per NPC, including NPCs
that are still starting.
If a creation step fails, cancel and await that start before considering cleanup complete.
If cleanup also fails, retain both errors. Do not shut down the scheduler while cleanup still
needs to finish.
Avoid blocking the instance thread
NPC commands returnCompletionStage values. Compose them from event callbacks:
destination is the NpcRenderTransform from the movement guide.
Waiting with join() or get() inside an instance tick can block the same scheduler that
must complete the command. Bounded waits are appropriate on a separate bootstrap/shutdown
thread, as shown in the quickstart.
A completed server command does not acknowledge a rendered Minecraft frame or an accepted
resourcepack. Use your application’s pack-status handling when gameplay requires that boundary.
Handle changing worlds and reconnects
Invalidate pending installations when a world closes or a newer installation replaces them. For that advanced lifecycle, configureNpcPublicationGuard on the spawn request. Its callback
must check the current generation and run the supplied publication operation synchronously
and atomically. The default guard runs it immediately.
Player objects and private presentation handles belong to one current backend connection.
When a player transfers between servers or proxies, cancel old local state and create new state
at the destination. Use network-wide presence/routing when resolving remote players.
Add Scene when you need interactions
The NPC library renders models. If you also want authored placements, click/proximity triggers and logical colliders, add the optional Scene adapter:build.gradle.kts
groundsgg/library-scene GitHub Packages repository as well.
Scene owns the logical element, interactions and activation; NPC owns its rendered parts.
Your application still loads models and supplies the exact scene catalogs.
See the Scene runtime reference for that separate integration.
Next: troubleshooting or
advanced build and verification workflows.