Skip to main content
By the end of this guide, a small bot stands in your world. You use a finished model first; creating your own models comes next. You need a running Java 25 Minestom project with an instance and a place for players to spawn. The example uses public Minestom 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 npc/ directory and the Java files below into your project, checking for existing files before copying. The archive contains:
The four Java files are application example code. 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 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:
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 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 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.
Keep 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.