Citizens, Pathing and Waypoints

Why Moving NPCs Matter

Static NPCs feel lifeless. A guard that stands in one spot forever does not sell the illusion of a living world. Citizens npc pathing waypoints let you define routes that NPCs walk, patrol, or wander along, making your towns, dungeons, and spawn areas feel populated and dynamic. Players notice the difference immediately when NPCs move with purpose.

This guide builds on the Citizens NPC tutorial. Make sure Citizens is installed and you have at least one NPC created before setting up waypoints.

Waypoint Providers

Citizens supports multiple waypoint providers, each with different behavior:

• Linear: The NPC walks from point A to B to C and then reverses back. Best for patrol routes like guards walking a wall.
• Guided: The NPC walks from waypoint to waypoint in order, then teleports back to the start and repeats. Good for circular paths where the return trip would look unnatural.
• Wander: The NPC roams randomly within a set radius. Best for villagers, animals, or ambient town NPCs.

Set the provider with:

/npc wp provider linear
# or
/npc wp provider guided
# or
/npc wp provider wander

Adding Waypoints to a Path

Select your NPC first with /npc select, then add citizens npc pathing waypoints by walking to each location and running:

/npc wp add

Each command adds the waypoint at your current position. Walk to the next spot and run the command again. Repeat until your path is complete. The NPC starts walking the route immediately.

For precision, stand exactly where you want the NPC to walk. Citizens uses your coordinates including the Y level, so if your path includes stairs or elevation changes, position yourself carefully on each step.

Removing and Clearing Waypoints

/npc wp remove <index>    # Remove a specific waypoint
/npc wp clear              # Clear all waypoints

Waypoints are indexed starting at 0. If you misplace one in the middle of a long route, remove it by index rather than clearing the entire path.

Wander Provider Configuration

The wander provider is configured differently because there are no fixed points. Instead, you set a region within which the NPC roams:

/npc wp provider wander
/trait waypointprovider:wander

By default the NPC wanders within a 10-block radius of its spawn point. You can expand or limit this through the Citizens data file at plugins/Citizens/saves.yml, adjusting the wander distance for the specific NPC entry.

Controlling NPC Speed

Walking speed makes a big difference in how natural citizens npc pathing waypoints look. A guard should walk slowly and deliberately. A messenger NPC might jog. Set speed with:

/npc speed 0.8    # Slow walk
/npc speed 1.0    # Normal walk (default)
/npc speed 1.5    # Fast walk / jog
/npc speed 2.0    # Sprint

Avoid speeds above 2.0 because the NPC's walking animation breaks at high speeds and it looks like the entity is gliding rather than running.

Combining Paths with Actions

Waypoints become powerful when combined with Citizens' trait system. An NPC can stop at a waypoint, play an animation, say something in chat, or trigger a command:

/npc wp add --command "say Halt! Who goes there?"

This makes guard NPCs announce themselves at specific patrol points, or shopkeeper NPCs call out to nearby players when they reach the market square. For complex interactions, integrate with BetonQuest conversations to trigger full dialogue trees when a pathing NPC reaches a location.

Performance Considerations

Each pathing NPC uses server-side pathfinding calculations. On a server with 100+ NPCs all walking simultaneously, you may notice a slight TPS impact. To mitigate this:

• Use wander for ambient NPCs in low-traffic areas (cheaper pathfinding).
• Keep linear paths short, 10 to 15 waypoints maximum.
• Avoid placing pathing NPCs in areas with complex terrain or frequent block updates.
• Use the /citizens command to check NPC tick times if you suspect performance issues.

With citizens npc pathing waypoints configured properly, your server transforms from a static theme park into a world that moves and breathes. Pair walking NPCs with custom skins for the complete immersive package.

Need full config access? Astroworld Hosting, Pterodactyl panel, NVMe SSDs.