EliteHolographics

EliteHolographics is a modern, high-performance Minecraft server plugin built using the Spigot/Paper API. Unlike legacy hologram plugins that rely on invisible armor stands and packet manipulation, this plugin utilizes native TextDisplay and Interaction entities (introduced in Minecraft 1.19.4).

Architectural Highlights

• Native Rendering: By leveraging TextDisplay entities, the plugin shifts the rendering overhead entirely to the client. This dramatically reduces server-side entity ticking and lag.
• Modern Text Engine: Fully integrates the Kyori Adventure API and MiniMessage. This allows server administrators to use advanced formatting, including RGB gradients, hex colors, hover events, and clean font styles.
• Smart Chunk & World Management: Listens to chunk and world loading events to dynamically manage entity lifecycles. It automatically cleans up or respawns displays when chunks unload/load, preventing "ghost entities" or duplicated holograms.
• Asynchronous-Friendly Tasks: Animation scaling and placeholder parsing are handled via scheduled Bukkit tasks, preventing main-thread stalling.

---

Requirements

To run this plugin successfully, your server environment must meet the following criteria:

• Server Platform: Paper (Paper recommended as they natively bundle the Kyori Adventure libraries used in this code).
• Minecraft Version: Minecraft 1.21 or newer (Required for TextDisplay and Interaction entity support).
• Java Version: Java 21 or higher.

Optional Dependencies

• PlaceholderAPI (PAPI): If present, the plugin automatically hooks into it to allow live-updating server placeholders.

⚠️ Technical Note on PAPI: The plugin passes a null player object when parsing placeholders (PlaceholderAPI.setPlaceholders(null, text)). This means only global placeholders (e.g., %server_tps%, %server_online%) will display properly. Player-specific placeholders (e.g., %player_name%) are not supported on the hologram text itself, though {player} is supported inside interactive click actions.

---

Core Features

1. Advanced Text Formatting (MiniMessage)

No more awkward &c or §e color codes. The plugin natively interprets MiniMessage. For example, setting a line to: "<gradient:gold:yellow>✦ Welcome to the Server ✦</gradient>" will render a smooth color transition.

2. Live Animations

The plugin includes an AnimationManager that reads custom configurations from the plugins/EliteHolographics/animations/ folder.

• Animations are configured frame-by-frame via YAML files.
• You can define a custom tick interval (e.g., interval: 10 for twice per second).
• The plugin cycles through these frames smoothly in-place without needing to completely recreate the entity.

3. Interactivity & Click Actions

When a hologram is toggled to interactive, the plugin calculates its exact physical boundary box (lines * 0.28f + 0.15f) and overlays an invisible Interaction entity. When a player right-clicks this space, it triggers a chain of actions with a 500ms anti-spam cooldown. Supported actions:

• COMMAND: Forces the player to run a command.
• CONSOLE: Executes a command via the server console.
• MESSAGE: Sends a private, formatted MiniMessage to the clicking player.
• BROADCAST: Sends a formatted MiniMessage to everyone on the server.

4. Layout Customization

• Billboard Mode (Default): The hologram automatically rotates to face the player flawlessly from any direction (Billboard.CENTER).
• Static Mode: Locks the panel to a fixed direction (north, south, east, west) making it look like a flat wall display or sign.
• Custom Backgrounds: Background boxes can be toggled on/off completely or tinted using hexadecimal codes (e.g., #FF6600).

---

Command Reference & Permissions

All operations run through the base command /holo.

Management Commands

Command	Description	Permission
/holo list	Lists all created holograms on the server.	elite.holo.use
/holo info <name>	Previews a hologram's lines and internal data properties.	elite.holo.use
/holo near [radius]	Locates all holograms within a specific radius.	elite.holo.use
/holo create <name> [text]	Spawns a new hologram at your current coordinates.	elite.holo.create
/holo delete <name>	Permanently removes a hologram and its entry from the file.	elite.holo.delete
/holo reload	Clears all active tasks, reloads files, and re-spawns entities.	elite.holo.reload

Modification Commands

Command	Description	Permission
/holo addline <name> <text>	Appends a brand new line to the bottom of the hologram.	elite.holo.edit
/holo edit <name> <line#> <text>	Replaces the text of an existing line number.	elite.holo.edit
/holo removeline <name> <line#>	Removes a line. (Will block removing the last remaining line).	elite.holo.edit
/holo insertline <name> <line#> <text>	Inserts text at a specific index, pushing other lines down.	elite.holo.edit
/holo placeatme <name>	Teleports a hologram directly to your current location.	elite.holo.move
/holo move <name> <x> <y> <z>	Moves a hologram to specific coordinates. Supports relative ~.	elite.holo.move

Appearance & Display Options

Command	Description	Permission
/holo static <north|south|east|west> <name>	Locks the hologram rotation to a fixed cardinal wall-direction.	elite.holo.edit
/holo bg <name> <on|off|reset>	Toggles or resets the native black translucent background box.	elite.holo.edit
/holo bgc <name> <#RRGGBB>	Restores background and colors it using a Hex code.	elite.holo.edit
/holo papi <name> <on|off>	Dictates whether global PAPI placeholders refresh every second.	elite.holo.edit

Interactivity Commands

Command	Description	Permission
/holo interactive <name>	Toggles right-click capabilities on or off.	elite.holo.edit
/holo actions <name>	Displays a numbered configuration list of existing click actions.	elite.holo.use
/holo addaction <name> <TYPE> <val>	Binds a COMMAND, CONSOLE, MESSAGE, or BROADCAST execution.	elite.holo.edit
/holo removeaction <name> <index>	Removes a specific action script by its list index number.	elite.holo.edit
/holo clearactions <name>	Wipes out all configured click scripts and turns off interactivity.	elite.holo.edit

Animation Engine Commands

Command	Description	Permission
/holo listanim	Lists all parsed animation configurations available on the system.	elite.holo.use
/holo newanim <name>	Generates a template animation YAML file in the plugin directory.	elite.holo.create
/holo createanim <name> <anim>	Spawns a new hologram bound directly to a file-based loop.	elite.holo.create
/holo setanim <name> <anim>	Upgrades a static hologram to run a specific file-based loop.	elite.holo.edit
/holo removeanim <name>	Strips an animation off a hologram, reverting it to static text.	elite.holo.edit

---

File Structure & Usage Guide

Stored Holograms (holos.yml)

Holograms are flat-saved inside plugins/EliteHolographics/holos.yml. Here is an example layout generated by the plugin's code:

holos:
  spawn_welcome:
    world: world
    x: 100.5
    y: 64.0
    z: -200.5
    lines:
      - "<gradient:gold:yellow>⭐ WELCOME TO ELITE MC ⭐</gradient>"
      - "<gray>Players Online: <aqua>%server_online%</aqua></gray>"
    isStatic: false
    yaw: 0.0
    showBackground: true
    papiRefresh: true
    interactive: true
    actions:
      - "MESSAGE:<green>You clicked the server info board!"
      - "CONSOLE:eco give {player} 10"

Creating Animations

• To build an animation, run /holo newanim pulse. This produces a clean layout template inside plugins/EliteHolographics/animations/pulse.yml. You can open this file and configure frame cycles like this:

interval: 10
frames:
  - - "<red>●</red> <white>Server Feature</white>"
    - "<gray>Click here to learn more!</gray>"
  - - "<gold>●</gold> <white>Server Feature</white>"
    - "<yellow>Click here to learn more!</yellow>"

Once edited, type /holo reload to load it into memory, then attach it to your display via /holo setanim <hologram_name> pulse.