LocatorBarAPI

High-performance Java library and server plugin for complete programmatic control over the vanilla Minecraft Locator Bar HUD.

---

Why LocatorBarAPI?

Minecraft's vanilla locator bar lacks an official public API and is difficult to control directly via NMS. Manual packet manipulation often results in ghost waypoints, HUD flickering, packet leakage, and threading race conditions.

LocatorBarAPI aims to provide a simple, clean, yet stable API to modify and control the locator bar—abstracting all low-level networking, Netty channel pipelines, and reflection into an intuitive developer experience:

• Simple 1-Line Calls: Hide, show, track, or pin waypoints with zero boilerplate.
• Rock-Solid Stability: Outbound Netty pipeline filtering prevents packet leakage and ghost dots.
• Built-in Stealth Rules: Automatic filters for sneaking, invisibility, carved pumpkins, mob heads, and gliding.
• Custom Conditions: Plug in custom predicates for combat tags, teams, or custom items.
• Static Waypoints & Colors: Place custom labeled, colored coordinates on the compass HUD.
• Multi-Platform Compatibility: Supports Spigot, Paper, Purpur, and Folia region-threading out of the box.
• Bukkit Events: Intercept waypoint updates with standard cancellable @EventHandler listeners.

---

Installation

Gradle (Kotlin DSL)

repositories {
    mavenCentral()
    maven("https://jitpack.io")
}

dependencies {
    compileOnly("com.github.mukulx:LocatorBarAPI:v1.0.0") // Standalone plugin mode
    // implementation("com.github.mukulx:LocatorBarAPI:v1.0.0") // Or shade directly
}

Maven

<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>com.github.mukulx</groupId>
        <artifactId>LocatorBarAPI</artifactId>
        <version>v1.0.0</version>
        <scope>provided</scope>
    </dependency>
</dependencies>

---

Quick Example

// Shaded mode: initialize in onEnable() (Standalone plugin initializes automatically)
LocatorBarAPI.init(this);

// 1. Target Tracking (see only teammates within 100 blocks)
LocatorBarAPI.track(player, teamMembersList, 100.0);

// 2. Built-in Stealth (hide sneaking / invisible players)
LocatorBarAPI.enableDefaultStealthConditions(player);

// 3. Custom Predicate (hide players in combat)
LocatorBarAPI.addCondition(player, "combat", (viewer, target) -> CombatManager.isTagged(target));

// 4. Colored Static Waypoint (bases, death markers, flags)
LocatorBarAPI.setWaypoint(player, "base", baseLocation, Color.GREEN, WaypointStyle.DEFAULT);

// 5. Automatic Death Waypoint Tracking (SMP / Survival)
LocatorBarAPI.setDeathWaypointsEnabled(true);
LocatorBarAPI.setDeathWaypointAutoClearRadius(5.0);

// 6. Global & Per-World Controls
LocatorBarAPI.enableWorld(world);
LocatorBarAPI.hideAll();

---

Documentation Guides

• Getting Started Guide - Complete setup guide for standalone and shaded configurations.
• API Reference - Detailed specifications for every method, class, enum, and event.
• Usage Examples & Recipes - Practical patterns for team radars, minigames, stealth, and custom waypoints.
• Architecture & Internals - Deep dive into Netty pipeline interception and protocol mechanics.

---

License

This project is open-source and released under the MIT License.