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

# Create your first NPC

> Place a finished example model in your existing Minestom server, without importing or building the library.

By the end of this guide, a small bot stands in your world. You use a finished model first;
[creating your own models](https://docs.grounds.gg/reference/libraries/npc/importing.md) 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](https://docs.grounds.gg/reference/libraries/npc/installation.md), 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](https://raw.githubusercontent.com/groundsgg/docs/a6980009d75718c8eafa3c19bef0fbccbb1916a6/files/npc/npc-quickstart-2.0.0-26.2.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:

```text theme={null}
npc/
  server-content.zip
  resourcepack.zip
  manifest.json
  models/bot.bbmodel
  models/import.json
  LICENSE
src/main/java/example/npc/
  FirstNpc.java
  SampleNpcPack.java
  NpcAnimations.java
  NpcSounds.java
```

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:

```sh theme={null}
cd npc
jwebserver -b 127.0.0.1 -p 8080
```

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:

```java Java theme={null}
import example.npc.SampleNpcPack;
import java.net.URI;
import java.nio.file.Path;

SampleNpcPack.install(URI.create("http://127.0.0.1:8080/resourcepack.zip"), Path.of("npc/resourcepack.zip"));
```

```kotlin Kotlin theme={null}
import example.npc.SampleNpcPack
import java.net.URI
import java.nio.file.Path

SampleNpcPack.install(URI.create("http://127.0.0.1:8080/resourcepack.zip"), Path.of("npc/resourcepack.zip"))
```

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.

```java Java theme={null}
import example.npc.FirstNpc;
import java.nio.file.Path;
import net.minestom.server.coordinate.Pos;

FirstNpc firstNpc = FirstNpc.spawn(instance, Path.of("npc"), new Pos(0, 40, 0));
firstNpc.ready().whenComplete((npc, error) -> {
    if (error != null) error.printStackTrace();
    else System.out.println("Bot created");
});
```

```kotlin Kotlin theme={null}
import example.npc.FirstNpc
import java.nio.file.Path
import net.minestom.server.coordinate.Pos

val firstNpc = FirstNpc.spawn(instance, Path.of("npc"), Pos(0.0, 40.0, 0.0))
firstNpc.ready().whenComplete { npc, error ->
    if (error != null) error.printStackTrace()
    else println("Bot created")
}
```

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.

> [!TIP]
>
> 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:

```java Java theme={null}
firstNpc.closeAsync().toCompletableFuture().get(5, java.util.concurrent.TimeUnit.SECONDS);
```

```kotlin Kotlin theme={null}
firstNpc.closeAsync().toCompletableFuture().get(5, java.util.concurrent.TimeUnit.SECONDS)
```

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](https://docs.grounds.gg/reference/libraries/npc/importing.md) or
[animate this bot](https://docs.grounds.gg/reference/libraries/npc/shared-npcs.md).
If it is invisible, start with [troubleshooting](https://docs.grounds.gg/reference/libraries/npc/troubleshooting.md).


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