Hexvane's Wayfinder

Hexvane's Wayfinder is an in-world navigation mod. You create routes as ordered waypoints; players start a route and see a particle trail leading to the next waypoint and a compass marker on the world map. When they reach a waypoint (within its arrival radius), the trail advances to the next one. You can add arrival messages, sounds, and optional commands that run when a waypoint is reached or when the full route is completed.

Overview

Wayfinder lets server staff or builders create named routes with multiple waypoints. Players use /wayfinder start <route> to begin following a route. A particle trail shows the path to the current waypoint, and the world map shows a marker for that waypoint. When the player gets within the waypoint's arrival radius (default 3 blocks), the next waypoint becomes active. Optionally, each waypoint can show a popup message, play a sound, and run a server command; the whole route can run a command when the player reaches the last waypoint.

All Wayfinder commands use /wayfinder or the shorthand /wf. Use underscores or dashes in route and waypoint names (e.g. My_First_Route, Starting_Area) so it is clear where the route name ends and other arguments begin.

Quick Start

Create a route: /wf create My_First_Route
Walk to the first location and add a waypoint: /wf addwaypoint My_First_Route Starting_Area
Walk to the next location and add another: /wf addwaypoint My_First_Route The_Old_Bridge
Optionally set an arrival message: /wf setmessage My_First_Route 2 Cross the bridge and look for the hidden cave entrance.
Start navigating: /wf start My_First_Route

A particle trail guides you to waypoint 1. When you get close enough, it advances to waypoint 2, shows the arrival message if set, and the trail updates.

Route Management

/wf create <name>
Create a new empty route.
/wf delete <name>
Delete a route permanently.
/wf list
List all routes and how many waypoints each has.
/wf info <name>
Show detailed route info: waypoints, positions, radii, and whether each has a message.

Waypoint Editing

Waypoint indices are 1-based (first waypoint is 1, second is 2, and so on).

/wf addwaypoint <route> [name]
Add a waypoint at your current position. If you omit the name, it defaults to "Waypoint N".
/wf removewaypoint <route> <index>
Remove the waypoint at that index. Later waypoints shift down.
/wf setwaypoint <route> <index>
Move the waypoint at that index to your current position.
/wf setmessage <route> <index> <message>
Set the popup message shown when a player reaches this waypoint.
/wf setradius <route> <index> <radius>
Set the arrival radius in blocks (default is 3.0). The player must be within this distance to trigger the waypoint.
/wf setarrivalcommand <route> <index> [command]
Run a command when a player reaches this waypoint. The command runs as the server console. Use {player} in the command for the player's display name (e.g. give {player} diamond 1). Omit the command to clear it.
/wf setsound <route> <index> [soundEventId]
Override the arrival sound for this waypoint. Use the game's sound event ID. Omit to clear and use the default again.
/wf setcompletioncommand <route> [command]
Run a command when a player reaches the last waypoint and completes the route. Runs as console; use {player} for the player's name. Omit the command to clear it.

Navigation

/wf start <route>
Begin navigating a route from waypoint 1. The particle trail and compass marker point to the current waypoint.
/wf stop
Stop your current navigation.
/wf skip
Skip to the next waypoint without walking there.
/wf preview <route>
Spawn particles at every waypoint to visually check the route layout.

How Navigation Works

A particle trail extends from the player toward the current waypoint (by default up to 20 blocks ahead).
A compass marker on the world map points to the active waypoint.
When the player enters the waypoint's arrival radius, the next waypoint becomes active. Any arrival sound or arrival command runs.
If the waypoint has a message, a popup appears with Continue and Stop Navigation options.
When the last waypoint is reached, the route completion command runs if set, and navigation ends.

Command Execution

Arrival and completion commands run as the server console, not as the player. The player does not need to be opped or have special permission; only the person who creates the route and sets the command needs to be able to use Wayfinder. In the stored command, use the placeholder {player}; it is replaced with the display name of the player who reached the waypoint or completed the route. Example: to give that player an item, use give {player} diamond 1. The leading slash in the command is optional.

Configuration

The config file is saved in the plugin data directory as wayfinder_config.json. Options include:

defaultParticle: Particle effect used for trails (default: Wayfinder_Trail).
trailSpacing: Distance between trail particles in blocks (default: 2.0).
trailMaxDistance: Maximum distance ahead of the player that the trail is drawn (default: 20.0).
defaultArrivalRadius: Default waypoint trigger radius in blocks (default: 3.0).
visualMode: FLOATING (trail at eye level) or GROUNDED (trail on terrain).
tickRate: How often trails update, in ticks (default: 10).
showArrivalPopup: Whether to show the popup UI when a waypoint is reached (default: true).
allowPlayerDisable: Whether the arrival popup shows a "Stop Navigation" button (default: true).

Data Storage

Routes are saved as JSON files in the plugin data directory under routes/. Each file is named after the route. Routes persist across server restarts.

Documentation

For a more in-depth tutorial on using the mod, including step-by-step route building, fixing mistakes, and command triggers, see the Usage Guide on GitHub.

Support

For issues, suggestions, or questions, join the Hexvane's Mods Discord for support.