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

# Use your own Blockbench model

> Turn a Blockbench model into server content and a matching resourcepack, then load it in your application.

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](https://docs.grounds.gg/reference/libraries/npc/getting-started.md) 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](https://github.com/groundsgg/library-npc/releases/tag/v2.0.0).
Run it with Java 25. It includes its dependencies and does not require a Minestom server.

```sh theme={null}
java -jar npc-cli-2.0.0-all.jar --help
```

**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:

```sh theme={null}
java -jar npc-cli-2.0.0-all.jar validate \
  --input models --namespace my_server --target 26.2

java -jar npc-cli-2.0.0-all.jar compile \
  --input models --namespace my_server --target 26.2 --output build/merchant
```

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

| File | How you use it |
| - | - |
| `server-content.zip` | Load the validated model definitions on the server. |
| `resourcepack.zip` | Make this downloadable and offer it to players. |
| `manifest.json` | Record the target, content identity and archive hashes. |
| `pack-fragment/` | Use the generated client files with an existing pack composer. |

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:

```java Startup import theme={null}
import gg.grounds.npc.core.io.content.NpcContentLoader;
import gg.grounds.npc.importer.NpcModelImporter;
import gg.grounds.npc.importer.config.NpcImportOptions;
import gg.grounds.npc.importer.config.NpcMinecraftTarget;
import java.nio.file.Files;
import java.nio.file.Path;

var work = Files.createTempDirectory("server-npcs-");
var options = NpcImportOptions.builder(
        Path.of("models"), "my_server", NpcMinecraftTarget.MINECRAFT_26_2).build();
var output = NpcModelImporter.compile(options, work.resolve("content"));
var content = NpcContentLoader.load(output.getServerContent());
content.verifyResourcePack(output.getResourcePack());
```

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:

```sh theme={null}
java -jar npc-cli-2.0.0-all.jar compile \
  --input models --namespace my_server --target 26.2 \
  --base-pack existing-pack.zip --output build/combined-npcs
```

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](https://docs.grounds.gg/reference/libraries/npc/api-reference.md#import-options).
Gradle task wiring belongs to [advanced workflows](https://docs.grounds.gg/reference/libraries/npc/advanced.md).


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