waypoint-guide

Waypoint Guide

A Minecraft 1.20.1 Forge mod that adds custom waypoints to the map and displays navigation guides on the player's screen (primarily designed for quest-driven modpacks).

Features

• Add colored waypoints via commands, with support for distance-based visibility limits
• Render diamond-shaped markers on-screen (name, distance, floating animation), scaling up as the player approaches
• Off-screen markers display edge arrows indicating direction
• Markers with distance limits fade in/out with a 1.4-second animation when entering/leaving visible range
• Right-click a marker when the crosshair is aimed at it to remove it, complete with dismissal animation and particle effects; right-click dismissal 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 via KubeJS server scripts

Commands

All subcommands operate on a target <player>: operating on yourself requires no permission, while operating on other players requires OP (level 2).

• /waypoint add <player> <id> <x> <y> <z> <color> <name> — Add a waypoint (no distance limit)
• /waypoint addnear <player> <id> <x> <y> <z> <color> <distance> <name> — Add a waypoint that becomes invisible when the player is more than distance blocks away
• /waypoint addlock <player> <id> <x> <y> <z> <color> <name> — Add a locked waypoint that cannot be removed by right-clicking
• /waypoint addlocknear <player> <id> <x> <y> <z> <color> <distance> <name> — 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 specified player
• /wp — Alias for /waypoint

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

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 => {
  // event.waypointId / event.player and other fields are available
})
// Recommended approach 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 (waypointId is a string)
WaypointRightClick('123', event => {
  console.log('Right-clicked waypoint 123')
})

License

This project is open-sourced under the GNU General Public License v3.0