New API for developers

[d0by1]

Just making sure

• I have read the wiki and made sure, this feature is not yet in the plugin.
• I believe, that this feature is possible to implement.
• I made sure, that this feature has not been requested yet.

Problem

DecentHolograms currently lacks a true public API. Instead, plugin authors have been forced to rely on our internal classes, which creates several problems:

1. Overexposed internals
   Developers can access anything in the codebase—even parts they shouldn’t—which increases the risk of unintended side effects.

2. Breaking changes risk
   Every time we refactor or improve internal code, we must preserve backwards compatibility with whatever developers have accidentally relied on, limiting our ability to iterate.

3. Bloated, tangled “API”
   Over time the internals have grown into a disorganized mess. That not only makes it hard for us to build new features, but also forces third‑party authors to navigate a confusing and unstable surface.

Feature

Build a dedicated Developer API—completely separate from DecentHolograms’ internal code—that makes creating and managing holograms from other plugins a breeze. This API will expose only what’s needed through clean, well‑documented interfaces and utility classes, so developers never have to touch DH’s private logic.

Key features:

• Isolated holograms:
  Each API instance gets its own hologram registry. Holograms users create with the API won’t interfere with DH’s built‑in holograms or anyone else’s.

• Builders & utilities:
  For example, a simple, chainable HologramBuilder (and related helpers) will let users define, display, update, and destroy holograms in just a few lines of code.

• Visibility management:
  Let developers plug in their own logic to show, hide, or update holograms on a per‑player basis.

• Documentation & examples:
  Ship the API with Javadoc and sample code snippets to show common use cases and patterns.

Once the new Developer API is in place, the internal classes and methods will be officially deprecated, and they will be removed entirely in a future version. This should hopefully give developers enough time to switch to the new API.

Alternatives

No response

[Andre601]

I'm in favour of separation of the API. I myself did that on my own plugin, which helped a lot with maintainability in the end, as I could do whatever in my plugin and then simply trigger methods in the API for other plugins to respond to.

Tho, should this happen am I really hoping that Lombok is finally removed. This thing is no benefit to anyone here (At most you to not write code) and only makes things a lot more annoying to deal with.

Next, the HologramBuilder is a good idea to have. Tho, in that case would I propose to make the corresponding Hologram class a unmodifiable, read-only class to avoid problems.
To help with editing could it have a asBuilder() method that returns a new HologramBuilder with the Hologram's values pre-set, so a user can just edit it.
Tho, downside is, that one can't directly edit the hologram that way as it would be unmodifiable... So maybe a apply(...) accepting another HologramBuilder or Hologram could be given then... Or we tell the user to just replace the hologram in the registry. That would probs be better.

Finally would I like to mention some things I mentioned either here via issues or through Discord:

1. Rework of NBT stuff
Related: #238

The current NBT support is rather difficult to maintain.
Not only does it rely on a 3rd-party - NBT-API - which in the futurue will become plugin-only, losing DH's plugin-less dependencies, but the components are constantly shifting and turning, requiring us to adabt to every major change that affects (mostly) items.
Prime example is the Custom Model Data which had to be fixed twice within the last year alone due to Mojang changing it a lot.

This constant change makes it rather annoying to maintain, especially given only a few selected features are really used by the end-user.
Instead would I now say we try to remove our dependency on NBT-API and handle components ourself with a newer structure for defining them.
Also, we should only support a selected few in the process, so that maintenance remains manageable.

I personally would suggest to go with something like command flags, so that a user can define them more easily (and in any order they please).
As an example, /dh l add hologram 1 #ICON: PAPER --custommodeldata 1000 --glow true --glowcolor green would tell DH to create a PAPER item with custom model data 1000, apply the glow effect and then apply a glow color (This stuff may require working with packet-based teams for the colors).

2. Add what plugin created a hologram/Managed holograms
This was discussed on Discord.

A core issue currently with Holograns, is that there is no way to know if it was created by DH or was created by a plugin through its API.
This can make it difficult to find holograms managed by your plugin, as you're required to store either the Hologram Object or its name.
And neither is reliable, as Holograms can be modified by any plugin, which is why I would also propose that we make holograms only modifiable by the plugin that created it, if it wasn't DH itself. Question is how holograms made by a plugin that are set to be persistent should be handled... Maybe include the plugin name in the file content and only allow modifications via file and the plugin (So not even DH commands)?

That way could a plugin retrieve a list of all Holograms created from it, modify them as it pleases and continue, where currently you f.e. would look for speciffic name patterns, which isn't a sound solution.

[d0by1]

Regarding the API, I’m still in the planning phase. The main focus is simplicity and convenience. I want the API to be as easy to use as possible. I’ll definitely take your ideas into consideration, and we can go over some of the details later once I have a prototype ready.

Lombok is currently used pretty heavily in some of the worst parts of the project, so removing it all at once could be tricky. I understand the issues with it and I’d like to reduce or eliminate its use too. With the 2.9.0 update, I split the project into modules. None of the new ones use Lombok, and the API won’t either. At this point, it’s only used in the old, messy parts of the codebase.

Which brings me to another point: the 2.9.0 update and this upcoming API are just the beginning of a larger effort to clean up the entire codebase. The goal is to make the project actually maintainable, scalable, and not a total mess. Some of the next steps I have planned include:

• Reworking configs: not changing the structure, just how they’re handled in code.
• Reworking commands: again, just the internal logic and handling with scalability in mind to make it easier to add some new features later (display entities and such...)
• Refactoring/rewriting most of the internal code: this is actually the reason I’m working on the API right now. If I want to start changing the internals, I first need developers to stop relying on them. The idea is to get the proper API out, give people some time to migrate, and then start reworking the internals. The sooner the API is released, the more time developers will have to switch.

1. Rework of NBT stuff
This is a great point, and it’s definitely on the table now. With the NMS overhaul done, this should be easier than ever to implement. I also really like the idea of using command flags, that would be my go-to solution as well.

We can definitely start planning this. I’m not super familiar with NBT myself, so I’m not sure what all it would take, but I’ll put it on my list.

2. Add what plugin created a hologram/Managed holograms

This will be fixed with the new API, see the Isolated holograms point. I know this is a problem, and I definitely want to solve it.

As for persistent holograms, I’m still unsure how to approach that. I’ve even considered removing the feature entirely, since it adds complexity and I’m not sure how many people actually use it. That said, since the new API will use a completely different set of hologram objects, one option could be to store them in a separate folder just for API-created holograms. Another idea is to give users the ability to save/load their holograms into their own plugin folders using API methods. Something like a HologramDto they can work with directly. But I'm not sure.