The model is invisible or appears as paper
Make sure the player is in the NPC’s instance and near its position. Accept the matching resourcepack, and check that the player’s computer can download its URL.127.0.0.1 means the player’s own computer, so use a reachable host when testing remotely.
The resourcepack request uses the SHA-1 of the exact ZIP served at its URL.
SampleNpcPack computes it from your local pack file, so the hosted and local files must match.
The manifest records SHA-256 for artifact verification; it is not the request’s SHA-1.
After changing the pack, update the hosted file and rebuild the request from the matching local file. A server bundle and an unrelated pack do not form a working model.
The quickstart files target Minecraft 26.2.
The NPC is prepared but invisible
Preparation creates hidden parts. Wait forstart.ready(), handle rejection, and then await
handle.publish(). The quickstart helper performs both steps.
A shared animation starts but stays still
Your application must drive shared clip time. Use the animation helper or calladvanceClipTo(...) with increasing absolute clip-local milliseconds.
Passing 50 repeatedly always selects the same sample; it does not add 50 ms.
Private presentations have their own clock and do not need this driver.
A clip has no sound
Both shared and private sound callbacks are silent by default. Add the callback from the sound guide. Check the cue’s event ID and, for custom sounds, the resourcepack’s sound definition and file. A private callback must send only to its recipient.Startup hangs while waiting for an NPC
Do not block an instance tick waiting for another command on that instance. Compose returned stages instead. Keep shutdown waits on a separate thread while the scheduler is still available.The content loader rejects a path
Check the reported path and diagnostic. A configured content file must exist and its final path component must not be a symlink. An existing content directory must contain the complete bundle, rather than an individual model JSON file. For a projected Kubernetes Secret, a top-level key is a symlink. Project the archive ascontent/server-content.zip and open that nested file, or use a read-only file subPath mount.
This keeps the archive itself a regular file.
Gradle cannot resolve the package
Check the GitHub Packages repository and theread:packages credentials from
installation. Use NPC 2.0.0 consistently across modules.
A local source build is optional; it is not a prerequisite for consuming the released package.