Package com.winterhavenmc.library.messagebuilder.pipeline.adapters.location

Interface Locatable

Functional Interface:
This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.
@FunctionalInterface public interface Locatable
Represents an object that has a Location, which can be extracted and used for macro substitution in messages.

This interface is used by the LocationAdapter to extract structured location data for use in messages. It supports both full string representations and granular subfields such as world name and block coordinates.

Any plugin-defined object can implement this interface to automatically enable macro expansion of the form:

  • {OBJECT.LOCATION} – full formatted location string
  • {OBJECT.LOCATION.WORLD} – world name (optionally aliased by Multiverse)
  • {OBJECT.LOCATION.X}, {OBJECT.LOCATION.Y}, {OBJECT.LOCATION.Z} – localized coordinate values

The resulting macro values are extracted via extractLocation(MacroKey, AdapterContextContainer). This method is used internally by the MessageBuilder pipeline and should not need to be called directly.

  • Method Details

    • getLocation

      org.bukkit.Location getLocation()
      Returns the Bukkit Location associated with this object.
      Returns:
      the location of the object, or null if none exists

    • extractLocation

      default MacroStringMap extractLocation(MacroKey baseKey, AdapterContextContainer ctx)
      Extracts macro key-value pairs representing location data from this object.

      The returned MacroStringMap may contain:

      • LOCATION – formatted string of world name and coordinates
      • LOCATION.WORLD – resolved world name (Multiverse alias if available)
      • LOCATION.X, Y, Z – localized block coordinates
      Parameters:
      baseKey - the top-level macro key associated with this object
      ctx - a container providing access to formatters and world name resolution
      Returns:
      a MacroStringMap containing extracted location-related macro keys

    • getLocationWorldName

      static Optional<String> getLocationWorldName(org.bukkit.Location location, AdapterContextContainer ctx)
      Resolves the name of the world for the given Location.

      If Multiverse is installed and enabled, this method may return an alias rather than the raw world name.

      Parameters:
      location - the Bukkit location
      ctx - the context container with the WorldNameResolver
      Returns:
      an optional world name, or empty if it could not be resolved

    • formatLocation

      static Optional<String> formatLocation(org.bukkit.Location location, AdapterContextContainer ctx)
      Produces a formatted string representation of the given location, consisting of the world name followed by localized coordinates.

      Example output: world [123, 64, -512]

      Parameters:
      location - the location to format
      ctx - the context container with the number formatter and world name resolver
      Returns:
      an Optional<String> containing the formatted location, or empty if the location is null