🧭 PathGuide

Landmark Navigation for Vanilla+ SMP | Paper · Folia · 1.21–26.1.2

Your compass knows the way. You just have to walk.

PathGuide is a lightweight landmark navigation plugin for Paper, Spigot, and Folia servers. Players create named waypoints, share them with each other, and navigate using a compass and action bar — no teleports, no minimap, no shortcuts.

No client mods. No heavy dependencies. Just drop the jar and it works.

✨ Why PathGuide?

Most waypoint plugins hand players a teleport button and call it navigation. PathGuide doesn't. It's built for vanilla+ SMP servers where distance is part of the game and exploration means something.

The only landmark plugin built around the idea that getting there matters.

🧭 Core Features

Compass + action bar guidance The compass points to your target. The action bar shows direction and distance, updated every tick. No HUD mods, no client requirements — pure vanilla mechanics doing real work.

Landmark creation via signs Place a sign with [Landmark] on the first line and a name on the second. Done. The landmark is registered at that location. Break the sign — the landmark is removed. It feels like the world itself is the interface.

Public and private landmarks Public landmarks are visible and navigable by every player on the server. Private landmarks belong only to their creator. Both exist in the same system, with strict name uniqueness enforced per visibility tier.

Share a landmark with one command /path share <name> <player> sends the target player a clickable message in chat. One click starts navigation. No coordinates, no copy-pasting, no external tools.

Navigate to coordinates /path goto <x> <z> starts compass navigation to raw coordinates without creating a landmark. Useful for one-time destinations. Arrival is detected on the horizontal plane — Y coordinate is ignored.

Navigate to your last death /path death points you back to where you died. No grave plugins, no soul gems — just a compass and the memory of what happened there.

Paginated landmark list /path list shows all accessible landmarks with hover cards and one-click navigation. Every entry is interactive.

⚖️ Balance & Philosophy

PathGuide has four hard constraints that are not configurable:

No teleports The plugin never moves a player. Ever. Navigation ends when the player arrives on foot.

No economy Creating, sharing, and navigating to landmarks is free. No plugin currency, no cost system.

No minimap PathGuide does not render any map or overlay. Direction and distance in the action bar is the entire visual interface.

No GUIs Every interaction happens through commands, chat, and signs. No inventory screens, no chest menus.

These are product decisions, not missing features.

🔁 Navigation Lifecycle

Player runs /path find <name>  (or /path goto, /path death)
    │
    ├─ Permission check
    ├─ Landmark or target resolution
    ├─ Access check (public / own private)
    │
    ├─ Navigation session starts
    │       ├─ Compass target updated
    │       └─ Action bar: direction arrow + distance in blocks
    │
    ├─ Live updates every tick:
    │       ├─ World and target validation
    │       ├─ Distance + direction recalculation
    │       └─ Action bar re-render
    │
    └─ Session ends automatically on:
            ├─ Arrival within configured radius
            ├─ Manual /path stop
            ├─ Landmark deleted while navigating
            ├─ Player logout
            └─ World change (if configured)

⚙️ Configuration

general:
  locale: en                        # en · ru · ua
  chat-prefix-enabled: true
  update-notifications-enabled: true

storage:
  type: SQLITE                      # SQLITE only (MySQL not yet implemented)

landmarks:
  creation:
    sign-registration-enabled: true
    private-landmarks-enabled: true
    command-default-visibility: PRIVATE
    sign-default-visibility: PUBLIC
    max-landmarks-per-player: 100

  naming:
    min-length: 3
    max-length: 32
    max-words: 1                    # Single-word names only
    max-word-length: 16
    allowed-characters: "^[a-zA-Z0-9_\\-']+$"

  signs:
    header:
      - "[Landmark]"

  listing:
    page-size: 10
    clickable-list-enabled: true
    hover-details-enabled: true

  markers:
    unregister-on-marker-break: true

  worlds:
    blocked-for-creation: []
    blocked-for-navigation-target: []

navigation:
  compass-enabled: true
  action-bar-enabled: true
  update-interval-ticks: 20
  arrival-radius: 6.0
  stop-on-world-change: true

💬 Commands & Permissions

Aliases: /pg · /guide · /paths · /landmarks → all route to /path

🌍 Localization

Built-in translations: English, Russian, Ukrainian

Language files live in plugins/PathGuide/lang/ and can be freely edited. Switch language in config.yml under general.locale.

🚀 Perfect For

• Vanilla+ SMP servers — navigation that respects the survival experience
• Exploration-focused servers — distance stays real, discovery stays earned
• Roleplay servers — named landmarks build a living geography
• Folia servers — full regional thread compatibility out of the box
• Any server that wants QoL without breaking immersion

📋 Requirements

• Server: Paper, Spigot, or Folia
• Java: 21+ (Java 25+ for servers running 26.1.x)
• Minecraft: 1.21 – 26.1.2

Built for modern servers. 112 passing unit tests. Zero teleports.