Introduction

Get familiar with HoloEasy.

What is HoloEasy

HoloEasy is an open-source library for creating holograms in Minecraft that uses ProtocolLib (or PacketEvents) to handle packets. This allows for greater performance as the server does not have to manage these entities.

Frequently Asked Questions

Why?

HoloEasy only uses packets instead of registering the entity in the actual Minecraft server.

Do I need Kotlin with HoloEasy?

No, the API wasn't created for only Kotlin users, but rather to provide a clean, fluent API that works well in both Java and Kotlin environments.

Who is HoloEasy designed for?

For library and plugin devs.

Requirements

The prerequisites:

Java 8
ProtocolLib / experimental PacketEvents

If you opt for PacketEvents, the dependency is not included by HoloEasy and neither is the instance registration. More information in the example.

Installation

Learn how to install and integrate HoloEasy in your projects.

Maven

1. Add the JitPack repository to your build file.

<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>

2. Add the core dependency.

<dependency>
    <groupId>com.github.unldenis.holoeasy</groupId>
    <artifactId>holoeasy-core</artifactId>
    <version>4.3.2</version>
</dependency>

3. For java plugins include also the kotlin stdlib.

<dependency>
    <groupId>org.jetbrains.kotlin</groupId>
    <artifactId>kotlin-stdlib</artifactId>
    <version>1.9.21</version>
</dependency>

4. Once you’re done, you may now proceed creating your first hologram.

Gradle

1. Add the JitPack repository to your build file.

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        mavenCentral()
        maven { url 'https://jitpack.io' }
    }
}

2. Add the core dependency.

implementation 'com.github.unldenis.holoeasy:holoeasy-core:4.3.2'

3. For java plugins include also the kotlin stdlib.

implementation 'org.jetbrains.kotlin:kotlin-stdlib:1.9.21'

4. Once you’re done, you may now proceed creating your first hologram.

Hello World

Your first hologram.

Start programming

1. Register HoloEasy api.

@Override
public void onEnable() {
    HoloEasy.bind(plugin, PacketImpl.ProtocolLib /* PacketImpl.PacketEvents */ );
}

2. Define your first Hologram class.

public class HelloWorldHologram extends Hologram  {

    Line<String> line = textLine("Hello World");

    public HelloWorldHologram(@NotNull Location location) {
        super(location);
    }
}

3. Now spawn a hologram.

public void create(Location location) {
    HelloWorldHologram hologram = new HelloWorldHologram(location);
    hologram.show();
}

4. Congratulations! You have created your first Hologram.

Concepts

Learn how to use HoloEasy in your projects.

Hologram

The main class is Hologram. This is an abstract class, so to define your holograms you must extend this class.

A hologram is composed of lines, defined by the Line<*> interface. The lines can be either text or an item/block/dropped item.

As you saw in the Hello World example, the Hologram class provides these three methods, textLine, itemLine and blockLine, which should preferably be assigned to a class field; however, you can also call them in the constructor.

The order of the fields will correspond to the order of the lines in the hologram.

Having them as fields or accessible through a getter allows you to retrieve information or perform actions on a specific line.

public class MyHolo extends Hologram {

    public Line<String> counter = textLine("Hello World");
    public Line<ItemStack> status = itemLine(new ItemStack(Material.RED_DYE));

    public MyHolo(@NotNull Location location) {
        super(location);
    }
}

In this example, the hologram will display the text "Hello World" with a RED_DYE dropped below it.

For more complex lines, take a look at TextLine, ItemLine or BlockLine. Once we've created our hologram class, we can instantiate it. This does not mean the hologram is visible yet.

Pool

The structure of the hologram has been defined. But before proceeding, you need to understand what are your requirements.

Do you need a hologram visible to all players within a certain radius? Or do you need a hologram to be shown to one or more specific players?

In the first case, you may want to use a Pool. A Pool is a container for holograms and manages showing them asynchronously to players within a certain radius of the holograms, while hiding them from players who are too far away or leave the server.

A Pool can be interactive, allowing you to click on lines (if defined that way in the class), or not. If you don't have any specific needs, you can show the hologram with the show method.

public void create() {
    MyHolo hologram = new MyHolo(location);
    hologram.show(/* pool */);
}

In this case, the hologram is added and displayed using the Standard Pool. This pool is accessible from the HoloEasy class, from which you can obtain all the holograms in this pool.

It is always possible to create one or more Pools for greater flexibility and customization with HoloEasy.startPool and HoloEasy.startInteractivePool.

Custom Logic

As mentioned earlier, if you're not using a Pool, it is your responsibility to manage the hologram's visibility. In this case, the Hologram class provides two methods: show(Player) and hide(Player).

What's next

Docs needed

As you have seen, a breaking version, 4.0.0, has been released. With this version I thought it would be better to also create explanatory and intuitive documentation.

I'm open and would appreciate some PR to improve this book as well. The code can be found in the /book folder of the repo.

There are still parts of the documentation that have not been completed, I will gradually create them over time, but in the meantime you also have access to the examples of the holoeasy-example-packetevents and holoeasy-example-protocollib modules.