Fake players with click handlers, dialog, and movement paths

NPC

NPC spawns a mob (default: villager) with AI disabled and provides click handlers, dialog trees, and pathfinding movement.

---

Spawning

npc = await NPC.spawn(location, entity_type="VILLAGER", name="Guard")

• Parameters:
• location (Location) — Where to spawn the NPC.
• entity_type (EntityType | str) — Mob type. Default "VILLAGER".
• name (str | None) — Display name shown above the NPC.
• **kwargs — Extra spawn options passed to Entity.spawn.
• Returns: Awaitable[NPC]

guard = await NPC.spawn(Location(100, 64, 200, "world"), name="§6Town Guard")
shopkeeper = await NPC.spawn(player.location, entity_type="VILLAGER", name="§aShop")

---

Properties

entity

npc.entity  # → Entity

The underlying Entity instance.

uuid

npc.uuid  # → str | None

The entity's UUID string.

location

npc.location  # → Location

The NPC's current location.

---

Click Handlers

on_click

@npc.on_click
def handler(player, npc):
    ...

Register a handler called when a player left-clicks the NPC. Handler receives (Player, NPC).

on_right_click

@npc.on_right_click
def handler(player, npc):
    ...

Register a handler called when a player right-clicks the NPC. Handler receives (Player, NPC).

guard = await NPC.spawn(loc, name="Guard")

@guard.on_right_click
async def greet(player, npc):
    await player.send_message("§eHalt! State your business.")

---

Dialog Trees

dialog

npc.dialog(messages, loop=False)

Set a sequence of messages shown one per right-click. Each click advances to the next message.

• Parameters:
• messages (list[str]) — Messages to show in order.
• loop (bool) — If True, restart from the beginning after the last message. Default False (stays on last message).

npc.dialog([
    "§eWelcome, traveler!",
    "§eThe dungeon lies to the north.",
    "§eBeware of the dragon!",
    "§7(The guard nods silently.)"
], loop=False)

---

Movement

move_to

await npc.move_to(location, speed=1.0)

Move the NPC to a location using pathfinding. Temporarily enables AI.

• Parameters:
• location (Location) — Destination.
• speed (float) — Speed multiplier. Default 1.0.

follow_path

await npc.follow_path(waypoints, loop=False, speed=1.0, delay=0.5)

Make the NPC walk through a list of waypoints.

• Parameters:
• waypoints (list[Location]) — Locations to visit in order.
• loop (bool) — If True, repeat the path endlessly.
• speed (float) — Speed multiplier.
• delay (float) — Seconds between each waypoint. Default 0.5.

stop_path

npc.stop_path()

Stop the current movement and disable AI.

path = [Location(0, 64, 0, "world"), Location(10, 64, 0, "world"), Location(10, 64, 10, "world")]
await npc.follow_path(path, loop=True, speed=0.8)

# Later...
npc.stop_path()

---

Removing

remove

await npc.remove()

Remove the NPC entity from the world and unregister all handlers.