Class Hologram

java.lang.Object
de.oliver.fancyholograms.api.hologram.Hologram
public abstract class Hologram extends Object
Abstract base class for creating, updating, and managing holograms.

This class provides the basic functionality needed to work with holograms across multiple versions of Minecraft. To create a hologram specific to a version of Minecraft, extend this class and implement the abstract methods.

Note that the specific way holograms are created, updated, and deleted will vary depending on the Minecraft version.

A Hologram object includes data about the hologram and maintains a set of players to whom the hologram is shown.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected final @NotNull HologramData
    data
     
    static final int
    LINE_WIDTH
     
    protected static final int
    MINIMUM_PROTOCOL_VERSION
     
    static final org.bukkit.Color
    TRANSPARENT
     
    protected final @NotNull Set<UUID>
    viewers
    Set of UUIDs of players to whom the hologram is currently shown.

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    Hologram(@NotNull HologramData data)
     

  • Method Summary

    Modifier and Type
    Method
    Description
    protected abstract void
    create()
     
    final void
    createHologram()
    Create the hologram entity.
    protected abstract void
    delete()
     
    final void
    deleteHologram()
    Deletes the hologram entity.
    final boolean
    equals(@Nullable Object o)
     
    final void
    forceHideHologram(org.bukkit.entity.Player player)
    Forcefully hides the hologram from a player.
    final void
    forceShowHologram(org.bukkit.entity.Player player)
    Forcefully shows the hologram to a player.
    final void
    forceUpdate()
    Forcefully updates and refreshes hologram for players.
    void
    forceUpdateShownStateFor(org.bukkit.entity.Player player)
    Checks and forcefully updates the shown state for a player.
    final @NotNull HologramData
    getData()
     
    abstract @Nullable org.bukkit.entity.Display
    getDisplayEntity()
    Deprecated, for removal: This API element is subject to removal in a future version.
    abstract int
    getEntityId()
    Returns the entity id of this hologram This id is for packet use only as the entity is not registered to the server
    @NotNull String
    getName()
     
    final net.kyori.adventure.text.Component
    getShownText(@Nullable org.bukkit.entity.Player player)
    Gets the text shown in the hologram.
    final @NotNull Set<UUID>
    getViewers()
     
    final int
    hashCode()
     
    protected abstract boolean
    hide(@NotNull org.bukkit.entity.Player player)
     
    final void
    hideHologram(Collection<? extends org.bukkit.entity.Player> players)
    Hides the hologram from a collection of players.
    final void
    hideHologram(org.bukkit.entity.Player player)
    Hides the hologram from a player.
    final boolean
    isViewer(@NotNull UUID player)
     
    final boolean
    isViewer(@NotNull org.bukkit.entity.Player player)
     
    boolean
    isWithinVisibilityDistance(@NotNull org.bukkit.entity.Player player)
     
    boolean
    meetsVisibilityConditions(@NotNull org.bukkit.entity.Player player)
     
    final void
    queueUpdate()
    Queues hologram to update and refresh for players Use forceUpdate() if this hologram is not registered to the HologramManager.
    protected abstract void
    refresh(@NotNull org.bukkit.entity.Player player)
     
    void
    refreshForViewers()
    Refreshes the hologram for the players currently viewing it.
    void
    refreshForViewersInWorld()
    Refreshes the hologram for players currently viewing it in the same world as the hologram.
    final void
    refreshHologram(@NotNull Collection<? extends org.bukkit.entity.Player> players)
    Refreshes the hologram's data for a collection of players.
    final void
    refreshHologram(@NotNull org.bukkit.entity.Player player)
    Refreshes the hologram's data for a player.
    protected boolean
    shouldShowTo(@NotNull org.bukkit.entity.Player player)
     
    protected abstract boolean
    show(@NotNull org.bukkit.entity.Player player)
     
    final void
    showHologram(Collection<? extends org.bukkit.entity.Player> players)
    Shows the hologram to a collection of players.
    final void
    showHologram(org.bukkit.entity.Player player)
    Shows the hologram to a player.
    protected abstract void
    update()
     
    final void
    updateHologram()
    Deprecated, for removal: This API element is subject to removal in a future version.
    in favour of queueUpdate()
    void
    updateShownStateFor(org.bukkit.entity.Player player)
    Checks and updates the shown state for a player.

    Methods inherited from class Object

    clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • LINE_WIDTH

      public static final int LINE_WIDTH
      See Also:

    • TRANSPARENT

      public static final org.bukkit.Color TRANSPARENT

    • MINIMUM_PROTOCOL_VERSION

      protected static final int MINIMUM_PROTOCOL_VERSION
      See Also:

    • data

      @NotNull protected final @NotNull HologramData data

    • viewers

      @NotNull protected final @NotNull Set<UUID> viewers
      Set of UUIDs of players to whom the hologram is currently shown.

  • Constructor Details

    • Hologram

      protected Hologram(@NotNull @NotNull HologramData data)

  • Method Details

    • getName

      @NotNull public @NotNull String getName()

    • getData

      @NotNull public final @NotNull HologramData getData()

    • getEntityId

      public abstract int getEntityId()
      Returns the entity id of this hologram This id is for packet use only as the entity is not registered to the server
      Returns:
      entity id

    • getDisplayEntity

      @Internal @Deprecated(forRemoval=true, since="2.4.1") @Nullable public abstract @Nullable org.bukkit.entity.Display getDisplayEntity()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Returns the Display entity of this Hologram object. The entity is not registered in the world or server. Only use this method if you know what you're doing.

      This method will return null in 1.20.5 and newer versions

      Returns:
      the Display entity of this Hologram object

    • create

      protected abstract void create()

    • delete

      protected abstract void delete()

    • update

      protected abstract void update()

    • show

      protected abstract boolean show(@NotNull @NotNull org.bukkit.entity.Player player)

    • hide

      protected abstract boolean hide(@NotNull @NotNull org.bukkit.entity.Player player)

    • refresh

      protected abstract void refresh(@NotNull @NotNull org.bukkit.entity.Player player)

    • createHologram

      public final void createHologram()
      Create the hologram entity. Only run this if creating custom Hologram implementations as this is run in HologramManager.create(HologramData).

    • deleteHologram

      public final void deleteHologram()
      Deletes the hologram entity.

    • showHologram

      public final void showHologram(Collection<? extends org.bukkit.entity.Player> players)
      Shows the hologram to a collection of players. Use forceShowHologram(Player) if this hologram is not registered to the HologramManager.
      Parameters:
      players - The players to show the hologram to

    • showHologram

      public final void showHologram(org.bukkit.entity.Player player)
      Shows the hologram to a player. Use forceShowHologram(Player) if this hologram is not registered to the HologramManager.
      Parameters:
      player - The player to show the hologram to

    • forceShowHologram

      public final void forceShowHologram(org.bukkit.entity.Player player)
      Forcefully shows the hologram to a player.
      Parameters:
      player - The player to show the hologram to

    • hideHologram

      public final void hideHologram(Collection<? extends org.bukkit.entity.Player> players)
      Hides the hologram from a collection of players. Use forceHideHologram(Player) if this hologram is not registered to the HologramManager.
      Parameters:
      players - The players to hide the hologram from

    • hideHologram

      public final void hideHologram(org.bukkit.entity.Player player)
      Hides the hologram from a player. Use forceHideHologram(Player) if this hologram is not registered to the HologramManager.
      Parameters:
      player - The player to hide the hologram from

    • forceHideHologram

      public final void forceHideHologram(org.bukkit.entity.Player player)
      Forcefully hides the hologram from a player.
      Parameters:
      player - The player to show the hologram to

    • updateHologram

      @Deprecated(forRemoval=true) public final void updateHologram()
      Deprecated, for removal: This API element is subject to removal in a future version.
      in favour of queueUpdate()
      Queues hologram to update and refresh for players.

    • queueUpdate

      public final void queueUpdate()
      Queues hologram to update and refresh for players Use forceUpdate() if this hologram is not registered to the HologramManager.

    • forceUpdate

      public final void forceUpdate()
      Forcefully updates and refreshes hologram for players.

    • refreshForViewers

      public void refreshForViewers()
      Refreshes the hologram for the players currently viewing it.

    • refreshForViewersInWorld

      public void refreshForViewersInWorld()
      Refreshes the hologram for players currently viewing it in the same world as the hologram.

    • refreshHologram

      public final void refreshHologram(@NotNull @NotNull org.bukkit.entity.Player player)
      Refreshes the hologram's data for a player.
      Parameters:
      player - the player to refresh for

    • refreshHologram

      public final void refreshHologram(@NotNull @NotNull Collection<? extends org.bukkit.entity.Player> players)
      Refreshes the hologram's data for a collection of players.
      Parameters:
      players - the collection of players to refresh for

    • getViewers

      @NotNull public final @NotNull Set<UUID> getViewers()
      Returns:
      a copy of the set of UUIDs of players currently viewing the hologram

    • isViewer

      public final boolean isViewer(@NotNull @NotNull org.bukkit.entity.Player player)
      Parameters:
      player - the player to check for
      Returns:
      whether the player is currently viewing the hologram

    • isViewer

      public final boolean isViewer(@NotNull @NotNull UUID player)
      Parameters:
      player - the uuid of the player to check for
      Returns:
      whether the player is currently viewing the hologram

    • shouldShowTo

      protected boolean shouldShowTo(@NotNull @NotNull org.bukkit.entity.Player player)

    • meetsVisibilityConditions

      public boolean meetsVisibilityConditions(@NotNull @NotNull org.bukkit.entity.Player player)

    • isWithinVisibilityDistance

      public boolean isWithinVisibilityDistance(@NotNull @NotNull org.bukkit.entity.Player player)

    • updateShownStateFor

      public void updateShownStateFor(org.bukkit.entity.Player player)
      Checks and updates the shown state for a player. If the hologram is shown and should not be, it hides it. If the hologram is not shown and should be, it shows it. Use forceUpdateShownStateFor(Player) if this hologram is not registered to the HologramManager.
      Parameters:
      player - the player to check and update the shown state for

    • forceUpdateShownStateFor

      public void forceUpdateShownStateFor(org.bukkit.entity.Player player)
      Checks and forcefully updates the shown state for a player. If the hologram is shown and should not be, it hides it. If the hologram is not shown and should be, it shows it.
      Parameters:
      player - the player to check and update the shown state for

    • getShownText

      public final net.kyori.adventure.text.Component getShownText(@Nullable @Nullable org.bukkit.entity.Player player)
      Gets the text shown in the hologram. If a player is specified, placeholders in the text are replaced with their corresponding values for the player.
      Parameters:
      player - the player to get the placeholders for, or null if no placeholders should be replaced
      Returns:
      the text shown in the hologram

    • equals

      public final boolean equals(@Nullable @Nullable Object o)
      Overrides:
      equals in class Object

    • hashCode

      public final int hashCode()
      Overrides:
      hashCode in class Object