Skip to main content
Start with a model that you own or are allowed to use. You can compile it before deploying your server, or let your application import it during startup. Both produce the same kinds of files. A restart loads your changed model. The example from your first NPC contains 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. Add implementation("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
Use the selected model from 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:
A directory with 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.