2026.10.07-26.2 and a Minecraft 26.2 client.
1
Add the library
Follow installation, then return here.
Your application needs
npc-minestom:2.0.0; it does not need the importer or CLI.2
Download the example files
Download the quickstart ZIP and extract it into
an empty folder. Copy the The four Java files are application example code.
npc/ directory and the Java files below into your project,
checking for existing files before copying. The archive contains:FirstNpc loads the model and owns its
startup and removal. SampleNpcPack offers the matching pack to players who join.
NpcAnimations and NpcSounds are used in the next guide.
The model and its source are included under the MIT license.3
Make the resourcepack available
For a local test, open a second terminal in your project root and run the JDK’s web server:Open The localhost URL works when Minecraft runs on the same computer. For another computer,
use a pack URL that the player’s computer can reach. You can use your existing pack host;
keep the exact
http://127.0.0.1:8080/resourcepack.zip to check that the pack downloads.
Keep this terminal running while you test. If port 8080 is occupied, choose another
port with -p and update the URL below.Register the example’s pack handler after MinecraftServer.init() and before players join:resourcepack.zip supplied with this example.
The helper computes its request hash from that local file. Its file-loading call can throw IOException.4
Place the NPC
In your application’s startup code, after the Minestom server has started, use your existing
instance as Keep
instance. Choose a position near your player’s spawn; this example uses (0, 40, 0).
Run file loading on the startup thread, rather than inside an instance tick or player event.
The Java startup method must handle or declare IOException from file loading.firstNpc in your application’s state. The path is relative to your application’s
working directory. Its ready() stage completes once the NPC is prepared and published.
The helper cancels unfinished work if creation fails.Join the instance, accept the pack, and look near the chosen position. You should see the
bot’s body and head. It holds its initial pose; animation is the next guide.
5
Remove it when your application stops
Before stopping the instance or Minestom, wait for NPC removal on your shutdown thread:Do not wait inside an instance tick: queued NPC work needs that scheduler to run.
If cleanup fails or times out, report the failure in your shutdown handling.
What the helper does
FirstNpc.java uses three library operations: NpcRenderer.prepare(request) creates the
parts hidden, start.ready() returns the prepared handle, and handle.publish() makes it
available to viewers. It retains the start token so closeAsync() can cancel creation at
any point. Read src/main/java/example/npc/FirstNpc.java from the downloaded archive when adapting it to your server.
Continue with your own Blockbench model or
animate this bot.
If it is invisible, start with troubleshooting.