npc/models/bot.bbmodel. You can use that file to follow these steps before replacing it.
Prepare the files before deployment
1
Download the compiler
Download
npc-cli-2.0.0-all.jar from the
NPC 2.0.0 release.
Run it with Java 25. It includes its dependencies and does not require a Minestom server.2
Export your model
Save a Blockbench Generic Model as a
.bbmodel file in models/. For example,
models/merchant.bbmodel becomes my_server:npc/merchant.
Embed PNG textures or place them inside the model’s input directory. Start with cube geometry
and numeric animation keyframes; unsupported features are reported with a file and field path.3
Validate, then compile
Use the Minecraft version of your server and its clients. These commands use the guide’s 26.2 profile:Choose an output directory that does not exist yet. The compiler writes the finished result
after validating the model and generated pack.
4
Use the result in your server
Copy
server-content.zip and resourcepack.zip from build/merchant into your deployment.
Load them as in the quickstart. In FirstNpc.java, replace the example model ID
npc_demo:npc/bot with my_server:npc/merchant.Host the new pack. SampleNpcPack.install(url, path) computes the request’s SHA-1 from the
local pack file; pass your new file and the URL serving those same bytes. manifest.json
records SHA-256 archive hashes for deployment verification.Understand the output
Keep server content and its pack together.
NpcContentLoader.load(...) validates the server
bundle; content.verifyResourcePack(path) checks that the pack contains the matching generated
assets. This checks files, not whether a player has accepted the pack.
Import when the application starts
Use this option when your deployment contains editable source models. Addimplementation("gg.grounds:npc-importer:2.0.0") alongside npc-minestom:2.0.0.
Run the synchronous import on your startup thread or worker before creating NPCs:
Startup import
content.getModels(). Your application hosts
output.getResourcePack() and keeps the temporary files until the pack host and NPCs have
closed. Remove the temporary directory on failed import and during final shutdown.
You need neither the CLI nor an external process for this path.
Add models to an existing pack
Pass your pack as an additional input:pack.mcmeta also works. Its compatibility must include the selected target.
The compiler preserves unrelated files. Different files at the same path are reported as a
conflict; choose another namespace or correct the input. Your original pack stays unchanged.
For explicit model IDs, sound bindings, supported source features and CLI options, use the
import reference.
Gradle task wiring belongs to advanced workflows.