Skip to main content

Holograms

Package: dev.anchorlight.stonelib.hologram

HologramService shows floating text using Paper's own TextDisplay entities, so there is no dependency on a hologram plugin. Each hologram is tagged with an id you choose, so it can be found again, including after a restart.

API​

MethodMeaning
new HologramService(JavaPlugin)
create(UUID id, Location, List<Component> lines)Removes any existing hologram with this id, then spawns a new one.
update(UUID id, List<Component> lines)Replaces the text of an existing hologram. Does nothing if it is not found.
remove(UUID id)Removes the hologram. Does nothing if it is not found.
has(UUID id)Whether the hologram can be found.

All four must be called on the main thread.

Example​

HologramService holograms = new HologramService(this);

UUID leaderboardId = UUID.nameUUIDFromBytes("leaderboard:hub".getBytes(StandardCharsets.UTF_8));

holograms.create(leaderboardId, hubLeaderboardLocation, List.of(
        MiniMessages.parse("<gold><bold>Top Questers"),
        MiniMessages.parse("<white>1. <name1> <gray>- <points1>", "name1", first.name(), "points1", first.points()),
        MiniMessages.parse("<white>2. <name2> <gray>- <points2>", "name2", second.name(), "points2", second.points())));

// later, when scores change
holograms.update(leaderboardId, freshLines);

Deriving the id from a fixed name, as above, gives the same id on every start, which is what lets the plugin find its hologram again.

How it works​

  • The hologram is a single TextDisplay entity. Lines are joined with newlines into its text.
  • It uses the CENTER billboard, so it always turns to face the viewer.
  • The id is stored in the entity's persistent data container under the key <yourplugin>:stonelib-hologram-id.
  • Everything else is Paper's defaults. To change the background, shadow, alignment, scale, or line width, find the entity yourself by that key, or spawn your own TextDisplay.

Behaviour to know about​

  • Holograms persist in the world. TextDisplay entities are saved with their chunk, so a hologram survives a restart without being recreated. That is why create removes an existing one first.
  • Lookups only see loaded chunks. update, remove, and has search entities in loaded chunks. A hologram in an unloaded chunk is reported as missing, and calling create for it spawns a second copy that appears when the chunk loads. Create holograms at locations that are loaded, such as spawn, or make sure the chunk is loaded first.
  • Every call searches all loaded text displays. Each call scans every TextDisplay in every world. That is fine for a handful of holograms updated now and then, but not for updating many holograms every tick. For fast-changing text, keep a reference to the entity yourself.
  • Creation failures are logged, not thrown. If the world is missing or the spawn fails, a warning is logged and nothing is created.