Waypoint Guide

A Minecraft 1.20.1 Forge mod to add custom waypoints and display navigation guides on the player's screen (primarily for quest-driven modpacks).

Features

• Add colored waypoints via commands, with distance-based visibility limits
• Render diamond-shaped markers on-screen (name, distance, floating animation), scaling up as the player approaches
• Off-screen markers show edge arrows to indicate direction
• Markers with distance limits fade in/out with a 1.4-second animation when entering or leaving visible range
• Right-click a marker while the crosshair is aimed at it to remove it, with dismissal animation and particle effects; right-click removal uses a dedicated data packet and is validated server-side
• Waypoint data is saved per player to waypoints.json in the world directory
• Provides WaypointDismissEvent (Forge event, triggered server-side), which can be listened to by KubeJS server scripts

Commands

All subcommands target a <player>: no permission required to operate on yourself; OP level 2 is required to operate on other players.

• /waypoint add <player> <id> <x> <y> <z> <color> <name> [dimension] — Add a waypoint (no distance limit)
• /waypoint addnear <player> <id> <x> <y> <z> <color> <distance> <name> [dimension] — Add a waypoint that becomes invisible when the player is more than distance blocks away
• /waypoint addlock <player> <id> <x> <y> <z> <color> <name> [dimension] — Add a locked waypoint that cannot be removed by right-clicking
• /waypoint addlocknear <player> <id> <x> <y> <z> <color> <distance> <name> [dimension] — Add a locked waypoint with distance-based visibility that cannot be removed by right-clicking
• /waypoint remove <player> <id> — Remove a waypoint
• /waypoint clear <player> — Clear all waypoints for the target player
• /wp — Alias for /waypoint

<color> supports red, green, blue, yellow, cyan, magenta, white, black, orange, pink, gray, purple, as well as hex formats such as 0xRRGGBB / #RRGGBB.

[dimension] is an optional parameter. When specified, the waypoint will be placed in the given dimension (e.g. minecraft:the_nether, shorthand the_nether is also supported; press Tab to autocomplete all loaded dimensions on the server). When omitted, it defaults to the target player's current dimension. The command will fail and list available dimensions if the specified dimension does not exist.

Note: <name> can be written directly if it is a single word; names containing spaces must be wrapped in quotation marks (e.g. "Cave Floor 2").

KubeJS

When a waypoint is dismissed by right-clicking, the server triggers WaypointDismissEvent, which can be listened to in server scripts:

const $WayPoint = Java.loadClass('com.dreamdawn.waypointguide.forge.WaypointDismissEvent')
ForgeEvents.onEvent($WayPoint, event => {
  // Fields such as event.waypointId / event.player are available
})
// Recommended implementation for easier reuse across scripts
const $WayPoint = Java.loadClass('com.dreamdawn.waypointguide.forge.WaypointDismissEvent')
global.WaypointRightClick = (waypointId, callback) => {
  ForgeEvents.onEvent($WayPoint, event => {
    if (event.waypointId === waypointId) {
      callback(event)
    }
  })
}
// Example usage (ID is a string)
global.WaypointRightClick('123', event => {
  console.log('Right-clicked waypoint 123')
})

License

This project is open-sourced under the MIT license.