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

Modification Commands

Appearance & Display Options

Interactivity Commands

Animation Engine Commands

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.