Asynchronous, high-performance Minecraft Hologram library for 1.8-1.20.1 servers.
This library can only be used on spigot servers higher or on version 1.8.8.
The plugin ProtocolLib is required on your server.
These are the lines provided by the library, thanks to the composition of various parts. The library is structured so that you too can create your own custom hologram.
To be integrated into a Hologram composed of multiple lines you need to implement ILine.
#
Animation
Hologram Integration
Clickable
Line
TextLine
✅
✅(w/ Pool)
TextALine
✅
✅
ClickableTextLine
✅
✅
BlockLine
✅
BlockALine
✅
✅
BlockLine
✅
Lets started
The library has been designed in such a way that it can be useful in any situation. What does it mean?
That you can choose to show a hologram to a single player for a few seconds or
for example use pools that automatically manage holograms and show them to players only if at least in a certain radius from them.
So the library uses the following concepts:
A Line itself is a hologram. The library through composition creates different types.
A set of lines are used to create holograms. Holograms can also consist of a single line. You have to show holograms manually for each player.
Pools are a set of holograms. Pools are not just containers. in fact they take care of showing and hiding holograms (not lines) to the different players in the server.
This allows for greater efficiency as holograms are shown for example only within a range for each player.
// create new hologram pool
HologramPool _pool = new HologramPool(plugin, 70);
// compose an interactive hologram pool
// this allows me to hear clicks towards text lines.
InteractiveHologramPool pool = new InteractiveHologramPool(_pool, 0.5f, 5f);
Hologram(Builder)
Using the builder you can easily create basic holograms in a single line of code.
The builder will take care of creating the hologram, loading it and adding it to the pool.
You can check the {@link HologramBuilder} class for more information.
If you don't want to add it to the pool just call build and not loadAndBuild!
Hologram.builder(plugin, loc) // initialize the builder
.addTextLine("Hello") // add a text line
.addTextLine("%%player%%") // add another text line
.addClickableTextLine("Click me", 0.5f, 5f) // add a clickable text line
.addBlockLine(new ItemStack(Material.GOLD_BLOCK)) // add a block line
.addBlockLine(new ItemStack(Material.DIAMOND_BLOCK), AnimationType.CIRCLE) // add a block line with animation
.placeholders(placeholders) // add placeholders
.loadAndBuild(pool); // load and build the hologram
Pool & Holograms & Lines.
Creating lines, holograms and assigning them to pools makes it easy to manage,
as holograms will be made visible and hidden automatically by the pool.
Even the management of clicks is manageable only thanks to the pool.
It is recommended to use the pool where possible.
// create new line structure (armorstand)
Line line = new Line(plugin);
// compose an TextLine hologram
TextLine textLine = new TextLine(line, "Hello", null, true);
// create new line structure (armorstand)
Line line2 = new Line(plugin);
// compose this second TextLine hologram
TextLine textLine2 = new TextLine(line2, "%%player%%", placeholders, true);
// append to hologram that will make all the hard work for you
// the TextSequentialLoader loader will load lines(text only) one after the other. It is an experimental function.
Hologram hologram = new Hologram(plugin, loc, new TextSequentialLoader());
// remember to call this method or hologram will not be visible
hologram.load(textLine, textLine2);
// add hologram to pool
pool.takeCareOf(hologram);
Hologram & Lines.
Creating lines and holograms allows you to manage multiple lines easily by assigning a single spawn.
Even the loader (or how the holograms will be spaced in the spawn) allow you to save many lines of code.
// create new line structure (armorstand)
Line line = new Line(plugin);
// compose an TextLine hologram
TextLine textLine = new TextLine(line, "Hi %%player%%", placeholders);
// create new line structure (armorstand)
Line line2 = new Line(plugin);
// compose this second BlockLine hologram
BlockLine BlockLine = new BlockLine(line2, new ItemStack(Material.GOLD_BLOCK));
// compose this second BlockAnimatedLine hologram
BlockALine BlockALine = new BlockALine(BlockLine, new StandardAnimatedLine(line2));
// append to hologram that will make all the hard work for you
// the TextBlockStandardLoader loader will load lines(text or block) one below the other.
Hologram hologram = new Hologram(plugin, loc, new TextBlockStandardLoader());
// remember to call this method or hologram will not be visible
hologram.load(textLine, BlockALine);
// show to player
hologram.show(player);
// start animation
BlockALine.setAnimation(AnimationType.CIRCLE, hologram);
// hide after 30 seconds to player
Bukkit.getScheduler().runTaskLater(plugin, () -> hologram.hide(player), 20L * 30);
Lines.
If, on the other hand, you want total control over a line of hologram, as for temporary holograms,
to be visible to certain players it may be convenient to use only the lines without holograms and pools.
// create new line structure (armorstand)
Line line = new Line(plugin, loc);
// compose an TextLine hologram
TextLine textLine = new TextLine(line, "Hi %%player%%", placeholders);
// show to player
textLine.show(player);
// hide after 30 seconds to player
Bukkit.getScheduler().runTaskLater(plugin, () -> textLine.hide(player), 20L * 30);
Bonus
Clickable line.
ClickableTextLine is useful if you need to hear clicks but without using a pool.
// create new line structure (armorstand)
Line line = new Line(plugin, loc);
// compose an TextLine hologram
TextLine textLine = new TextLine(line, "Click me");
// compose an experimental ClickableTextLine hologram
ClickableTextLine clickableTextLine = new ClickableTextLine(textLine, 0.5f, 5f);
// show to player
clickableTextLine.show(player);
// hide after 30 seconds to player
Bukkit.getScheduler().runTaskLater(plugin, () -> clickableTextLine.hide(player), 20L * 30);
New experimental ItemLine allows you to add items such as torch, diamond, and so on.
ItemLine in holograms is not yet integrated into the standard loader, you will need SingletonLoader if you use Holograms, and it must be the only line
ItemLine also allows you to set a 'handRotation', i.e. the rotation of the arm of the armorstand that holds the item.
Hologram hologram = Hologram.builder(plugin, loc) // initialize the builder
.addItemLine(new ItemStack(Material.TORCH), EulerAngle.ZERO) // add experimental item line
.loader(new SingletonLoader()) // a hologram loader with 1 line
.name("Since v2.6.0") // just a name
.loadAndBuild(pool);
ItemLine line = (ItemLine) hologram.getLines().get(0);
line.setHandRotation(new EulerAngle(Math.toRadians(270), 0, 0), hologram.getSeeingPlayers());
