🧭
JWaypoints
⌘K
v1.7 Latest GitHub ↓ Download
Docs › Overview

JWaypoints

Next-generation Minecraft waypoint navigation with 3D arrow guidance, smart switching, and full customization. Built for Minecraft 1.21+.

Advanced Waypoint Navigation

Beautiful floating 3D arrows, intelligent action-bar guidance, arrival effects, and a polished in-game GUI — all in one lightweight plugin.

Get Started → Commands Reference Download ↗
1.21+
Minecraft Version
5
Arrow Designs
4
Motion Patterns
Free
Open Source

Core Features

🎯
3D Arrow Navigation

Floating block-art arrows with spiral, zigzag, and static patterns pointing to your destination.

🧭
Smart Guidance

Auto-switches to action bar compass when arrows are blocked by terrain.

🎨
Customizable

Arrow designs, arrival sounds, particles, hex color support, and custom icons.

📊
XP Bar Distance

Real-time distance display using the experience bar as a progress indicator.

🔄
Waypoint Sharing

Share locations with teammates. Configurable by admins.

🖥️
Intuitive GUI

Full graphical interface — manage, edit, and navigate without typing commands.

Highlights

  • Multi-World Support — works across dimensions and custom worlds seamlessly
  • Permission-Based — granular nodes for different player ranks and roles
  • Performance Optimized — minimal server impact with configurable update ticks
  • Persistent Storage — waypoints saved to disk with automatic data protection
  • Tab Completion — all commands support tab-complete for fast usage
  • Bukkit / Spigot / Paper — compatible with all major server platforms
💡
JWaypoints works in both single-player (via LAN) and multiplayer environments, with server-wide config for administrators.

Created & maintained by J2D · Open source on GitHub

Docs›Installation

Installation & Setup

Get JWaypoints running on your server in under two minutes.

Requirements

  • Minecraft Server 1.21 or higher
  • Bukkit / Spigot / Paper server software
  • Java 17 or higher
  • ~50 MB free RAM
  • Write permissions to the plugins/ directory

Download

📦

GitHub Releases

Official source · all versions
⬇️

Modrinth

Plugin repository

Installation Steps

1

Download the JAR

Grab the latest JWaypoints.jar from GitHub or Modrinth above.

2

Place in plugins folder

Move the JAR into your server's plugins/ directory.

3

Start / restart the server

The plugin will generate its config on first run.

4

Configure (optional)

Edit plugins/JWaypoints/config.yml to customize the plugin.

5

Verify installation

Join the server and run /waypoint help — if the help menu appears, you're good to go!

✅
Installation complete! You'll see the JWaypoints help menu in-game if the plugin loaded successfully.

Quick Start

Create your first waypoint and start navigating:

minecraft 
# Create a waypoint at your current location
/waypoint set home

# Activate 3D arrow guidance toward it
/waypoint activate home

# Open the full GUI manager
/waypoint gui
💡
Use /wp as a shorthand alias for /waypoint. All commands support tab completion.

Next: Commands Reference →

Docs›Commands

Commands Reference

Full reference for all JWaypoints commands. Use /wp as an alias for /waypoint.

Waypoint Management

/waypoint set <name> [x y z] Create a waypoint at your location or at specified coordinates.
/waypoint remove <name> Delete a waypoint. Requires confirmation via /waypoint confirm.
/waypoint activate <name> Start 3D arrow guidance toward the named waypoint.
/waypoint deactivate Stop guidance and hide the arrow.
/waypoint confirm Confirm a pending deletion.
/waypoint cancel Cancel a pending operation.

Interface

/waypoint gui Open the graphical waypoint manager.
/waypoint list Display all your waypoints in chat (or opens GUI).
/waypoint current Show details about the currently active waypoint.
/waypoint help Display the in-game help menu.

Customization

/waypoint design <name> Change arrow design: standard, diamond, gold, emerald, redstone
/waypoint sound <name> Change arrival sound: levelup, bell, firework, portal
/waypoint particle <name> Change arrival particle: FIREWORK, FLAME, HEART, SOUL
/waypoint seticon Set a custom icon for a waypoint. Requires jwaypoints.icon.
/waypoint icons Browse icon suggestions by category.
/waypoint distance Toggle distance display in the XP bar.

Toggles & Sharing

/waypoint share <waypoint> <player> Share a waypoint with another online player.
/waypoint guidance Toggle guidance-switch notification messages.
/waypoint silent Toggle complete silent mode (no sounds or particles).
/waypoint nosound Toggle arrival sounds only.
/waypoint noparticles Toggle arrival particles only.
/waypoint updatecheck Check for plugin updates. (Admin)
⌨️
All commands support tab completion. Use /wp as a shorter alias for /waypoint.

Next: Permissions →

Docs›Features

Feature Showcase

Deep dive into everything JWaypoints can do.

3D Arrow Navigation

JWaypoints renders floating block-art arrows above you, pointing toward your destination in real time. Four motion patterns are available:

🔺
Standard

Classic arrow with pointed head and stabilizing fins. Lime concrete body with yellow/red accents.

🌀
Spiral

Rotating spiral pattern — eye-catching for important landmarks.

⚡
Zigzag

Dynamic back-and-forth motion for an energetic feel.

📌
Static

Non-animated arrow for distraction-free navigation.

Intelligent Guidance Switching

When the 3D arrow is blocked by terrain, JWaypoints automatically switches to an action-bar compass:

🧭
Action bar example: ➡ Right | ⬆ Up | 🎯 45.2m
  • Directional arrows ⬆ ⬇ ⬅ ➡ show horizontal direction
  • Vertical guidance shows "Up" or "Down" for elevation changes
  • Live distance in meters updated in real time
  • Automatic return to 3D arrows once the path clears

Arrow Designs

DesignMaterialsPatternExtra
Standard Lime, Yellow, Red concrete Pointed —
Diamond Diamond blocks, blue accents Static Glowing effect
Gold Gold blocks Spiral Flame particles
Emerald Emerald blocks Static Villager particles
Redstone Redstone blocks Zigzag Redstone particles

Arrival Effects

🔔
Arrival Sounds

Level up, bell, firework, portal, and more configurable sounds.

✨
Particle Effects

Fireworks, flames, hearts, souls, enchant effects, and dozens more.

🏷️
Custom Icons

Assign any Minecraft item as an icon displayed in the waypoint GUI.

🌈
Hex Colors

Full &#RRGGBB support for names, prefixes, and GUI titles.

⚠️
Waypoint sharing can be disabled by server admins via allow_sharing: false in config.

Next: GUI Guide →

Docs›GUI Guide

GUI User Guide

Master the in-game graphical interface for effortless waypoint management.

Main Waypoint Menu

Open with /waypoint gui or /waypoint list.

🖱️
Click Actions
Left-click Activate navigation toward that waypoint
Right-click Delete the waypoint (requires confirmation)
Shift-click Open the waypoint editor
⚙️
Settings Button

Comparator icon — opens the settings menu to customize your navigation.

❌
Close Button

Barrier block closes the interface from any screen.

Waypoint Editor

Open by Shift-clicking any waypoint in the main GUI.

  • 🏷️ Name Tag — Rename the waypoint with a custom title
  • 🧭 Compass — Manually edit coordinates with precision input
  • 🔮 Ender Pearl — Teleport the waypoint to your current location instantly
  • 💣 TNT — Delete waypoint with safety confirmation dialog
  • ⬅️ Arrow — Return to the main waypoint list
💡
All GUI actions have command equivalents — use whichever method suits your playstyle.

Next: Permissions →

Docs›Permissions

Permission System

Granular permission control for server administrators and different player ranks.

Permission Nodes

Permission Node Description Default
jwaypoints.useAccess all basic waypoint featurestrue
jwaypoints.setCreate new waypointstrue
jwaypoints.activateActivate waypoint navigationtrue
jwaypoints.guiAccess the waypoint GUItrue
jwaypoints.shareShare waypoints with other playerstrue
jwaypoints.designChange arrow designs and effectstrue
jwaypoints.iconSet custom waypoint iconstrue
jwaypoints.bypass.limitBypass waypoint count limitsop

Suggested Group Setup

🆕
New Players
  • jwaypoints.use
  • jwaypoints.set
  • jwaypoints.activate
  • jwaypoints.gui
👤
Regular Members
  • All basic permissions
  • jwaypoints.share
  • jwaypoints.design
  • jwaypoints.icon
👑
VIP / Donors
  • All member permissions
  • jwaypoints.bypass.limit
  • Unlimited waypoints
⚠️
Grant jwaypoints.bypass.limit carefully — unlimited waypoints can cause database bloat over time.

LuckPerms Example

shell 
/lp user <player> permission set jwaypoints.use true
/lp group member permission set jwaypoints.share true
/lp group vip permission set jwaypoints.bypass.limit true

Next: Configuration →

Docs›Configuration

Server Configuration

All config options live in plugins/JWaypoints/config.yml.

Arrow Appearance

yaml 
arrow:
  height: 3.0              # Height above player (blocks)
  spacing: 0.4             # Space between arrow parts
  forward_offset: 2.0      # Distance in front of player
  default_material: "LIME_CONCRETE"
  head_material: "YELLOW_CONCRETE"
  tail_material: "RED_CONCRETE"
  arrow_update_ticks: 2    # Performance: update frequency

Plugin Settings

yaml 
settings:
  allow_sharing: true           # Enable waypoint sharing between players
  waypoint_limit: 10            # Max waypoints per player (-1 for unlimited)
  distance_display_default: true  # Show distance in XP bar by default
  distance_update_ticks: 10     # Distance display update frequency

Custom Arrow Designs

Add your own designs in the designs: block:

yaml 
designs:
  custom_design:
    main_material: "NETHERITE_BLOCK"
    head_material: "DIAMOND_BLOCK"
    tail_material: "GOLD_BLOCK"
    glowing: true
    particle_effect: "ENCHANT"
    pattern_type: 1    # 0=standard, 1=spiral, 2=zigzag, 3=static

Hex Color Support

Use &#RRGGBB format anywhere color codes are accepted:

yaml 
messages:
  prefix: "&#FF5733[Waypoints]: "
  gui_title: "�FF00⭐ &#FFFFFFWaypoints �FF00⭐"
🔄
Use /waypoint reload or restart the server after editing config to apply changes.

Next: Troubleshooting →

Docs›Changelog

Changelog

All notable changes to JWaypoints, newest first.

Version 1.7 Icons Update Latest
New Features
  • Custom Waypoint Icons — use /waypoint seticon to assign any icon. Icons appear in the GUI.
  • /waypoint icons — browse icon suggestions by category (Home, Mining, Farming, Combat, and more).
  • Hex Color Support — &#RRGGBB format works in names, prefixes, and GUI titles. Mix with legacy codes freely.
Fixes & Improvements
  • /waypoint reload now correctly reloads all configuration values
  • Message prefix now reads properly from config.yml
  • Performance settings (arrow_update_ticks, distance_update_ticks) are now configurable
  • GUI title customization applies correctly on reload
  • Arrow appearance settings update properly after /waypoint reload
📡
Star the GitHub repository to get notified about new releases.
Docs›API Docs

API Documentation

Developer resources for integrating JWaypoints into your plugins.

🚧

Coming Soon

We're working hard on comprehensive API documentation — JavaDoc reference, integration guides, code examples, and an event system for listening to waypoint actions.

⏳ In Development

Stay Updated

⭐
Star on GitHub

Get release notifications automatically when new versions drop.

👀
Watch Repository

Receive development updates and API announcements.

💬
Discord

Join for real-time developer discussions and early access.

🔔
Follow Releases

Instant notifications when API docs are published.

📢
Interested in early API access? Reach out to J2D on GitHub. We're happy to work with developers wanting to integrate JWaypoints early.
Docs›Troubleshooting

Support & Troubleshooting

Solutions for common issues and guidance for getting help.

Common Issues

🚫
Permission Errors

Players see "You don't have permission" when using commands.

Solution: Ensure the player has jwaypoints.use and the relevant sub-permission. Use LuckPerms:

shell 
/lp user <player> permission set jwaypoints.use true
👻
Invisible Arrows

Solution: Arrows may be blocked by nearby terrain or structures. Move to an open area and reactivate, or increase arrow.height in config.yml. The plugin will auto-switch to action-bar guidance when blocked.

💾
Data Not Saving

Solution: Check that the server process has write permissions to the plugins/JWaypoints/ directory. Review the server console for IOException or disk-space errors.

Quick Checklist

  1. Verify player permissions are correctly configured
  2. Confirm the plugin is enabled and running the latest version
  3. Review the server console for error messages or exceptions
  4. Test with a minimal plugin setup to isolate conflicts
  5. Validate config.yml syntax (YAML is whitespace-sensitive)
  6. Ensure the server is running Minecraft 1.21+ with Paper/Spigot

Getting More Help

📖
Documentation

Check this wiki first — most questions are answered here.

🐛
Bug Reports

Open an issue on GitHub with steps to reproduce.

💡
Feature Requests

Suggest improvements via GitHub discussions or Discord.

✅
If you've worked through the checklist and still have issues, open a GitHub issue and include your server version, plugin version, and a copy of any console errors.

© 2025 J2D · GitHub · Modrinth