Skip to content

API_REFERENCE.md

Latest commit

 

History

History
654 lines (533 loc) · 28.6 KB

API_REFERENCE.md

File metadata and controls

654 lines (533 loc) · 28.6 KB
Raw

LocatorBarAPI Reference

This document provides a detailed specification for all public methods in the LocatorBarAPI class and the LocatorBarCondition enum.

Package: dev.mukulx.locatorbarapi

Class: LocatorBarAPI

The primary static facade for controlling locator bar waypoints.

Lifecycle Methods

init(JavaPlugin hostingPlugin)

  • Description: Bootstraps the LocatorBarAPI system. Registers event listeners, injects netty outbound channel handlers for all online players, and starts the background synchronization task.
  • Parameters:
    • hostingPlugin (JavaPlugin): The plugin instance managing the API lifecycle.
  • Throws: NullPointerException if hostingPlugin is null.

shutdown()

  • Description: Saves persistent state to disk, cancels the background update task, and clears internal references. Call this in onDisable() if shading the API.

save()

  • Description: Saves the current locator bar configuration, active waypoints, and sessions to locatorbar_state.json.

isAvailable()

  • Description: Checks whether packet reflection and netty pipeline hooks are available and working on the current server version.
  • Returns: boolean - true if fully functional, false otherwise.

setLoggingEnabled(boolean enabled)

  • Description: Enables or disables informational console logging from LocatorBarAPI. Pass false for a completely silent, clean server console. Important warnings and critical exceptions will still be reported.
  • Parameters:
    • enabled (boolean): true to enable console logs, false to silence them.

isLoggingEnabled()

  • Description: Checks whether informational console logging is currently enabled.
  • Returns: boolean - true if active.

getUpdateInterval()

  • Description: Retrieves the current background update interval in server ticks. Defaults to 2L ticks (10 Hz).
  • Returns: long - Interval in server ticks.

setUpdateInterval(long ticks)

  • Description: Configures the background synchronization frequency dynamically at runtime without requiring config files or server restarts.
  • Parameters:
    • ticks (long): The update interval in ticks (must be >= 1).
  • Throws: IllegalArgumentException if ticks < 1.

Global Visibility Controls

hideAll()

  • Description: Immediately untracks all waypoints from the screens of all online players and hides the locator bar for all future joiners.
  • Throws: IllegalStateException if the API has not been initialized.

showAll()

  • Description: Restores locator bar visibility for all online players using managed tracking.
  • Throws: IllegalStateException if the API has not been initialized.

isGlobalHidden()

  • Description: Checks whether the global hide state is currently active.
  • Returns: boolean - true if all players have their locator bars suppressed.
  • Throws: IllegalStateException if the API has not been initialized.

revertAll()

  • Description: Clears all custom tracking, conditions, and managed sessions across all online players, restoring pure vanilla Minecraft locator bar behavior.
  • Throws: IllegalStateException if the API has not been initialized.

Per-World Controls

isWorldEnabled(World world)

  • Description: Checks whether the locatorBar gamerule is enabled in the specified world.
  • Parameters:
    • world (World): The world to query.
  • Returns: boolean - true if enabled.
  • Throws: NullPointerException if world is null.

setWorldEnabled(World world, boolean enabled)

  • Description: Configures the locatorBar gamerule for a specific world. Fires WorldLocatorBarToggleEvent.
  • Parameters:
    • world (World): The target world.
    • enabled (boolean): true to enable, false to disable.
  • Returns: boolean - true if successfully applied, false if cancelled by event.
  • Throws: NullPointerException if world is null.

enableWorld(World world)

  • Description: Enables the locator bar gamerule for the given world.
  • Parameters:
    • world (World): The world to enable.
  • Returns: boolean - true if enabled.

disableWorld(World world)

  • Description: Disables the locator bar gamerule for the given world.
  • Parameters:
    • world (World): The world to disable.
  • Returns: boolean - true if disabled.

Per-Player Visibility Controls

hide(Player player)

  • Description: Hides the locator bar for a specific player immediately. Dispatches untrack packets to clear all active dots from the player's HUD.
  • Parameters:
    • player (Player): The player whose locator bar will be hidden.
  • Throws:
    • NullPointerException if player is null.
    • IllegalStateException if the API has not been initialized.

show(Player player)

  • Description: Shows the locator bar for a specific player using managed tracking.
  • Parameters:
    • player (Player): The player whose locator bar will be shown.
  • Throws:
    • NullPointerException if player is null.
    • IllegalStateException if the API has not been initialized.

isHidden(Player player)

  • Description: Checks whether the locator bar is currently hidden for the specified player.
  • Parameters:
    • player (Player): The player to check.
  • Returns: boolean - true if hidden.
  • Throws:
    • NullPointerException if player is null.
    • IllegalStateException if the API has not been initialized.

reset(Player player)

  • Description: Reverts the specified player to default vanilla behavior, clearing any custom target sets, ranges, or conditions.
  • Parameters:
    • player (Player): The player to reset.
  • Throws:
    • NullPointerException if player is null.
    • IllegalStateException if the API has not been initialized.

getMode(Player viewer)

  • Description: Returns the active operating mode name for a player (HIDDEN, MANAGED, or VANILLA).
  • Parameters:
    • viewer (Player): The player to query.
  • Returns: String - Mode name.
  • Throws:
    • NullPointerException if viewer is null.
    • IllegalStateException if the API has not been initialized.

Target Tracking Controls

track(Player holder, Player... targets)

  • Description: Configures holder to see only the specified targets on their locator bar.
  • Parameters:
    • holder (Player): The viewer receiving waypoint dots.
    • targets (Player...): One or more target players to display.
  • Throws:
    • NullPointerException if holder is null.
    • IllegalStateException if the API has not been initialized.

track(Player holder, Collection<Player> targets)

  • Description: Configures holder to see only the collection of targets on their locator bar.
  • Parameters:
    • holder (Player): The viewer receiving waypoint dots.
    • targets (Collection<Player>): Collection of target players.
  • Throws:
    • NullPointerException if holder is null.
    • IllegalStateException if the API has not been initialized.

track(Player holder, Collection<Player> targets, double range)

  • Description: Configures holder to see only the collection of targets within a maximum distance (in blocks).
  • Parameters:
    • holder (Player): The viewer.
    • targets (Collection<Player>): Target players to display.
    • range (double): Maximum block distance (use -1 for unlimited).
  • Throws:
    • NullPointerException if holder is null.
    • IllegalStateException if the API has not been initialized.

track(Player holder, double range, Player... targets)

  • Description: Configures holder to see only the array of targets within a maximum distance.
  • Parameters:
    • holder (Player): The viewer.
    • range (double): Maximum block distance.
    • targets (Player...): Target players.
  • Throws:
    • NullPointerException if holder is null.
    • IllegalStateException if the API has not been initialized.

clearTracking(Player holder)

  • Description: Clears any specific target restrictions for holder, returning to displaying all eligible players in managed mode.
  • Parameters:
    • holder (Player): The viewer.
  • Throws:
    • NullPointerException if holder is null.
    • IllegalStateException if the API has not been initialized.

isTracking(Player holder)

  • Description: Checks whether holder has an active custom target filter.
  • Parameters:
    • holder (Player): The viewer.
  • Returns: boolean - true if specific targets are being tracked.
  • Throws:
    • NullPointerException if holder is null.
    • IllegalStateException if the API has not been initialized.

getTracked(Player holder)

  • Description: Returns the set of players currently configured as targets for holder.
  • Parameters:
    • holder (Player): The viewer.
  • Returns: Set<Player> - Set of target players.
  • Throws:
    • NullPointerException if holder is null.
    • IllegalStateException if the API has not been initialized.

Proximity & Range Limits

setRange(Player holder, double range)

  • Description: Limits the maximum distance at which waypoints will appear for holder.
  • Parameters:
    • holder (Player): The viewer.
    • range (double): Distance in blocks (-1 for unlimited).
  • Throws:
    • NullPointerException if holder is null.
    • IllegalStateException if the API has not been initialized.

getRange(Player holder)

  • Description: Gets the current maximum distance limit for holder.
  • Parameters:
    • holder (Player): The viewer.
  • Returns: double - Range in blocks, or -1 if unlimited.
  • Throws:
    • NullPointerException if holder is null.
    • IllegalStateException if the API has not been initialized.

Contextual Conditions

setCondition(Player viewer, LocatorBarCondition condition, boolean enabled)

  • Description: Enables or disables a visibility condition for viewer. When enabled, any player meeting the condition is excluded from viewer's locator bar.
  • Parameters:
    • viewer (Player): The viewer.
    • condition (LocatorBarCondition): Condition to configure.
    • enabled (boolean): true to hide matching targets, false to show them.
  • Throws:
    • NullPointerException if viewer or condition is null.
    • IllegalStateException if the API has not been initialized.

setConditions(Player viewer, boolean enabled, LocatorBarCondition... conditions)

  • Description: Configures multiple conditions for viewer in a single call.
  • Parameters:
    • viewer (Player): The viewer.
    • enabled (boolean): true to hide matching targets, false to allow them.
    • conditions (LocatorBarCondition...): One or more conditions.
  • Throws:
    • NullPointerException if viewer or conditions is null.
    • IllegalStateException if the API has not been initialized.

enableDefaultStealthConditions(Player viewer)

  • Description: Convenience method enabling standard stealth conditions (SNEAKING, INVISIBLE, HEAD_WEARABLE) for viewer.
  • Parameters:
    • viewer (Player): The viewer.
  • Throws:
    • NullPointerException if viewer is null.
    • IllegalStateException if the API has not been initialized.

enableAllConditions(Player viewer)

  • Description: Enables the wildcard ALL condition for viewer, hiding players matching any supported stealth or state condition.
  • Parameters:
    • viewer (Player): The viewer.
  • Throws:
    • NullPointerException if viewer is null.
    • IllegalStateException if the API has not been initialized.

setAllConditions(Player viewer, boolean enabled)

  • Description: Configures the ALL wildcard condition on or off for viewer.
  • Parameters:
    • viewer (Player): The viewer.
    • enabled (boolean): true to enable, false to disable.
  • Throws:
    • NullPointerException if viewer is null.
    • IllegalStateException if the API has not been initialized.

clearConditions(Player viewer)

  • Description: Clears all active condition filters for viewer.
  • Parameters:
    • viewer (Player): The viewer.
  • Throws:
    • NullPointerException if viewer is null.
    • IllegalStateException if the API has not been initialized.

getConditions(Player viewer)

  • Description: Returns the set of all conditions currently enabled for viewer.
  • Parameters:
    • viewer (Player): The viewer.
  • Returns: Set<LocatorBarCondition> - Active conditions.
  • Throws:
    • NullPointerException if viewer is null.
    • IllegalStateException if the API has not been initialized.

isCondition(Player viewer, LocatorBarCondition condition)

  • Description: Checks whether a specific condition filter is currently active for viewer.
  • Parameters:
    • viewer (Player): The viewer.
    • condition (LocatorBarCondition): The condition to query.
  • Returns: boolean - true if the condition is active.
  • Throws:
    • NullPointerException if viewer or condition is null.
    • IllegalStateException if the API has not been initialized.

addCondition(Player viewer, String id, BiPredicate<Player, Player> predicate)

  • Description: Registers a dynamic custom condition predicate for viewer. The predicate is passed (viewer, target) and returning true hides the target.
  • Parameters:
    • viewer (Player): The viewer.
    • id (String): Unique identifier for this condition.
    • predicate (BiPredicate<Player, Player>): The evaluator function.
  • Throws:
    • NullPointerException if viewer, id, or predicate is null.
    • IllegalStateException if the API has not been initialized.

removeCondition(Player viewer, String id)

  • Description: Removes a custom condition predicate from viewer.
  • Parameters:
    • viewer (Player): The viewer.
    • id (String): Identifier of the condition to remove.
  • Throws:
    • NullPointerException if viewer or id is null.
    • IllegalStateException if the API has not been initialized.

clearCustomConditions(Player viewer)

  • Description: Clears all custom condition predicates registered for viewer.
  • Parameters:
    • viewer (Player): The viewer.
  • Throws:
    • NullPointerException if viewer is null.
    • IllegalStateException if the API has not been initialized.

hasCustomCondition(Player viewer, String id)

  • Description: Checks if viewer has a custom condition registered under id.
  • Parameters:
    • viewer (Player): The viewer.
    • id (String): The condition identifier.
  • Returns: boolean - true if registered.
  • Throws:
    • NullPointerException if viewer or id is null.
    • IllegalStateException if the API has not been initialized.

registerGlobalCondition(String id, BiPredicate<Player, Player> predicate)

  • Description: Registers a server-wide custom condition predicate evaluated for all viewers.
  • Parameters:
    • id (String): Unique identifier for this global condition.
    • predicate (BiPredicate<Player, Player>): The evaluator function.
  • Throws:
    • NullPointerException if id or predicate is null.
    • IllegalStateException if the API has not been initialized.

unregisterGlobalCondition(String id)

  • Description: Unregisters a server-wide custom condition predicate.
  • Parameters:
    • id (String): Identifier of the condition to remove.
  • Throws:
    • NullPointerException if id is null.
    • IllegalStateException if the API has not been initialized.

clearGlobalConditions()

  • Description: Clears all registered global custom condition predicates.
  • Throws:
    • IllegalStateException if the API has not been initialized.

hasGlobalCondition(String id)

  • Description: Checks if a global custom condition is registered under id.
  • Parameters:
    • id (String): The condition identifier.
  • Returns: boolean - true if registered.
  • Throws:
    • NullPointerException if id is null.
    • IllegalStateException if the API has not been initialized.

Static Points of Interest (POIs) / Location Waypoints

setWaypoint(Player viewer, String name, Location location, Color color, WaypointStyle style)

  • Description: Pins a static coordinate waypoint with custom color and style to a player's locator bar.
  • Parameters:
    • viewer (Player): The viewer player.
    • name (String): Unique identifier for this waypoint (e.g. "base", "spawn", "flag").
    • location (Location): The world coordinates to display.
    • color (Color, nullable): Optional Bukkit Color for the HUD icon. Pass null for default.
    • style (WaypointStyle, nullable): Optional WaypointStyle (DEFAULT dot or BOWTIE arrow). Pass null for default.
  • Throws:
    • NullPointerException if viewer, name, or location is null.
    • IllegalStateException if the API has not been initialized.

Additional setWaypoint Overloads:

  • setWaypoint(Player viewer, String name, Location location, Color color)
  • setWaypoint(Player viewer, String name, Location location, int rgbColor, WaypointStyle style)
  • setWaypoint(Player viewer, String name, Location location, int rgbColor)
  • setWaypoint(Player viewer, String name, Location location, WaypointStyle style)
  • setWaypoint(Player viewer, String name, Location location)
  • setWaypoint(Player viewer, Location location, Color color)
  • setWaypoint(Player viewer, Location location)

removeWaypoint(Player viewer, String name)

  • Description: Removes a static coordinate waypoint from a player's locator bar.
  • Parameters:
    • viewer (Player): The viewer player.
    • name (String): The identifier of the waypoint to remove.
  • Throws:
    • NullPointerException if viewer or name is null.
    • IllegalStateException if the API has not been initialized.

clearWaypoints(Player viewer)

  • Description: Clears all static coordinate waypoints for a specific player.
  • Parameters:
    • viewer (Player): The viewer player.
  • Throws:
    • NullPointerException if viewer is null.
    • IllegalStateException if the API has not been initialized.

hasWaypoint(Player viewer, String name)

  • Description: Checks whether a static waypoint is registered for a player.
  • Parameters:
    • viewer (Player): The viewer player.
    • name (String): The waypoint identifier.
  • Returns: boolean - true if present.
  • Throws:
    • NullPointerException if viewer or name is null.
    • IllegalStateException if the API has not been initialized.

getWaypoint(Player viewer, String name)

  • Description: Retrieves the location of a static waypoint for a player.
  • Parameters:
    • viewer (Player): The viewer player.
    • name (String): The waypoint identifier.
  • Returns: Location - Clone of the waypoint location, or null if not found.
  • Throws:
    • NullPointerException if viewer or name is null.
    • IllegalStateException if the API has not been initialized.

getWaypointColor(Player viewer, String name)

  • Description: Retrieves the Bukkit Color assigned to a player's static waypoint.
  • Returns: Color - The color, or null if default/unset.

getWaypointStyle(Player viewer, String name)

  • Description: Retrieves the WaypointStyle assigned to a player's static waypoint.
  • Returns: WaypointStyle - The style (DEFAULT or BOWTIE).

getWaypoints(Player viewer)

  • Description: Retrieves all static waypoints registered for a player.
  • Parameters:
    • viewer (Player): The viewer player.
  • Returns: Map<String, Location> - Copy of all registered waypoint names and locations.
  • Throws:
    • NullPointerException if viewer is null.
    • IllegalStateException if the API has not been initialized.

setGlobalWaypoint(String name, Location location, Color color, WaypointStyle style)

  • Description: Sets a server-wide static waypoint visible to all players in that world.
  • Parameters:
    • name (String): Unique identifier for this global waypoint.
    • location (Location): The world coordinates to display.
    • color (Color, nullable): Optional Bukkit Color.
    • style (WaypointStyle, nullable): Optional WaypointStyle.
  • Throws:
    • NullPointerException if name or location is null.
    • IllegalStateException if the API has not been initialized.

Additional setGlobalWaypoint Overloads:

  • setGlobalWaypoint(String name, Location location, Color color)
  • setGlobalWaypoint(String name, Location location, int rgbColor, WaypointStyle style)
  • setGlobalWaypoint(String name, Location location, int rgbColor)
  • setGlobalWaypoint(String name, Location location, WaypointStyle style)
  • setGlobalWaypoint(String name, Location location)

removeGlobalWaypoint(String name)

  • Description: Removes a global static waypoint across all players.
  • Parameters:
    • name (String): The identifier of the global waypoint to remove.
  • Throws:
    • NullPointerException if name is null.
    • IllegalStateException if the API has not been initialized.

clearGlobalWaypoints()

  • Description: Clears all server-wide static waypoints.
  • Throws:
    • IllegalStateException if the API has not been initialized.

hasGlobalWaypoint(String name)

  • Description: Checks whether a global static waypoint is registered.
  • Parameters:
    • name (String): The waypoint identifier.
  • Returns: boolean - true if registered.
  • Throws:
    • NullPointerException if name is null.
    • IllegalStateException if the API has not been initialized.

getGlobalWaypoint(String name)

  • Description: Retrieves the location of a global static waypoint.
  • Parameters:
    • name (String): The waypoint identifier.
  • Returns: Location - Clone of the global location, or null if not found.
  • Throws:
    • NullPointerException if name is null.
    • IllegalStateException if the API has not been initialized.

getGlobalWaypointColor(String name)

  • Description: Retrieves the Bukkit Color of a global static waypoint.
  • Returns: Color - The color, or null if default.

getGlobalWaypointStyle(String name)

  • Description: Retrieves the WaypointStyle of a global static waypoint.
  • Returns: WaypointStyle - The style (DEFAULT or BOWTIE).

getGlobalWaypoints()

  • Description: Retrieves all registered global static waypoints.
  • Returns: Map<String, Location> - Copy of all global waypoint names and locations.
  • Throws:
    • IllegalStateException if the API has not been initialized.

Death Waypoint Tracking

setDeathWaypointsEnabled(boolean enabled)

  • Description: Enables or disables automatic server-wide death waypoint tracking. When enabled, dying players automatically receive a static waypoint marker on their locator bar at their death coordinates upon respawning.
  • Parameters:
    • enabled (boolean): true to enable automatic death waypoints on death.
  • Throws:
    • IllegalStateException if the API has not been initialized.

isDeathWaypointsEnabled()

  • Description: Checks whether automatic death waypoints are enabled.
  • Returns: boolean - true if active.

setDeathWaypointAutoClearRadius(double blocks)

  • Description: Configures the distance in blocks within which a player must arrive for their death waypoint to automatically clear from their HUD. Defaults to 5.0 blocks. Pass 0 or negative to disable auto-clearing upon arrival.
  • Parameters:
    • blocks (double): Arrival radius in blocks.

getDeathWaypointAutoClearRadius()

  • Description: Gets the current arrival distance radius for auto-clearing death waypoints.
  • Returns: double - Distance in blocks.

setDeathWaypoint(Player player, Location deathLocation)

  • Description: Explicitly sets a death waypoint for player with default red color (#FF2222) and circular marker style.
  • Parameters:
    • player (Player): Target player.
    • deathLocation (Location): Death coordinates.

setDeathWaypoint(Player player, Location deathLocation, int rgbColor, WaypointStyle style)

  • Description: Explicitly sets a death waypoint for player with a custom RGB color integer and WaypointStyle.

clearDeathWaypoint(Player player)

  • Description: Clears any active death waypoint from player's locator bar HUD.

getDeathWaypoint(Player player)

  • Description: Retrieves the location of player's active death waypoint, or null if none is active.
  • Returns: Location - Waypoint coordinates, or null.

Enum: WaypointStyle

Visual marker icons rendered on the locator bar HUD:

Constant Description
DEFAULT Default circular dot marker.
BOWTIE Bowtie/arrow marker icon (standard for player waypoints).

Enum: LocatorBarCondition

Enum constants representing contextual state filters:

Constant Description
SNEAKING Excludes any target player who is currently sneaking/crouching (player.isSneaking()).
INVISIBLE Excludes any target player who has the Invisibility potion effect, entity invisibility metadata, or zero transmit range attribute.
PUMPKIN Excludes any target player wearing a Carved Pumpkin (Material.CARVED_PUMPKIN) in their helmet slot.
MOB_HEAD Excludes any target player wearing a mob head or skull (Player Head, Zombie Head, Skeleton Skull, Wither Skeleton Skull, Creeper Head, Piglin Head, Dragon Head).
HEAD_WEARABLE Composite condition that matches either a Carved Pumpkin or any Mob Head/Skull.
SPECTATOR Excludes target players in Spectator mode from non-spectator viewers.
VANISHED Excludes target players hidden via Bukkit's visibility system (!viewer.canSee(target)).
SAME_VEHICLE Excludes target players riding the exact same vehicle or mount as the viewer.
SWIMMING Excludes target players who are currently swimming or crawling.
GLIDING Excludes target players who are gliding with Elytra.
SLEEPING Excludes target players who are sleeping in a bed.
CREATIVE Excludes target players who are in Creative mode.
ADVENTURE Excludes target players who are in Adventure mode.
SURVIVAL Excludes target players who are in Survival mode.
NON_SURVIVAL Composite condition that excludes target players in any non-survival mode (Creative, Adventure, Spectator).
ALL Wildcard condition that excludes any target player matching any of the above conditions.

Events: dev.mukulx.locatorbarapi.event

All events inherit from org.bukkit.event.Event and support both Paper and Folia threaded region listeners.

PlayerLocatorBarTrackEvent

  • Package: dev.mukulx.locatorbarapi.event
  • Interfaces: Cancellable
  • Description: Fired before a candidate target player is tracked/rendered on a viewer's locator bar HUD.
  • Methods:
    • getViewer(): Player - The player observing the locator bar.
    • getTarget(): Player - The player about to appear.
    • isCancelled(): boolean
    • setCancelled(boolean cancel): Cancelling prevents the target from appearing on the viewer's locator bar.

PlayerLocatorBarUntrackEvent

  • Package: dev.mukulx.locatorbarapi.event
  • Description: Fired when a target player is removed from a viewer's locator bar HUD.
  • Methods:
    • getViewer(): Player - The player observing the locator bar.
    • getTarget(): Player (nullable) - The player removed, or null if disconnected.
    • getTargetId(): UUID (nullable) - The unique identifier of the target player (always available even if the player has disconnected).

PlayerLocatorBarModeChangeEvent

  • Package: dev.mukulx.locatorbarapi.event
  • Interfaces: Cancellable
  • Description: Fired when a player's locator bar operating mode changes (HIDDEN, MANAGED, VANILLA).
  • Methods:
    • getPlayer(): Player - The player whose mode is changing.
    • getOldMode(): String - Previous mode name.
    • getNewMode(): String - New mode name.
    • isCancelled(): boolean
    • setCancelled(boolean cancel): Cancelling prevents the mode transition.

WorldLocatorBarToggleEvent

  • Package: dev.mukulx.locatorbarapi.event
  • Interfaces: Cancellable
  • Description: Fired when a world's locator bar gamerule state is toggled via LocatorBarAPI.setWorldEnabled().
  • Methods:
    • getWorld(): World - The affected world.
    • isEnabled(): boolean - Target state (true for enabled, false for disabled).
    • isCancelled(): boolean
    • setCancelled(boolean cancel): Cancelling prevents the gamerule change.