Holograms

A hologram is a stack of display entities sent as packets. Nothing exists on the server, so a piston cannot push one, a mob cannot kill one, and a crash cannot leave one behind. Every plugin declares its holograms in its own configuration; ExyliaLib has no hologram file and no hologram command.

Hologram trophy = Holograms.show(this, "trophy", location, config.trophy());

Holograms need PacketEvents. Without it Holograms.isSupported() is false, a warning is logged once, and every call still works but draws nothing. A section with enabled: false does the same.

Showing one

Every method is safe from any thread. Placeholders used in lines are resolved off the main thread, so their resolvers must be async-safe. A line with no placeholders never schedules a refresh.

The configuration

spawn-hologram:
  enabled: true
  type: TEXT
  lines:
    - '<head:Notch><spin:45>'
    - '<size:2><shine:highlight,speed=15,pause=1,width=4>{primary}&lWELCOME'
    - '<gap:0.1><flow>{secondary}Season II · open now'
    - '<if:"%player_level% >= 10">{success}You qualify'
    - '<button:join>{letters}Click to join'
  per-player: true
  view-distance: 32
  offset-y: 2
  properties:
    billboard: CENTER
    distance-scale:
      enabled: true
      start: 8
      end: 32
      max: 2.5
  config:
    update-interval: 20
  click:
    commands:
      - '[PAGE] next'
    sound: 'UI_BUTTON_CLICK;0.6;1.4'
    buttons:
      join:
        - 'arena join'
  pages:
    - lines:
        - '{primary}&lRULES'
        - '{letters}No griefing.'
      click:
        - '[PAGE] previous'
  page-interval: 10s

persistent, config.spawn-on-chunk-load and config.remove-on-chunk-unload are still read, so old files load, but they do nothing.

properties

Size by distance

properties.distance-scale grows the hologram as a viewer walks away, so it stays readable from across a spawn. It is min up to start blocks, grows evenly, and stays at max from end on, worked out per viewer in steps of 0.1.

One line can carry its own curve with <autoscale> (the hologram's curve) or <autoscale:start,end,max>.

Line tags

A line can start with tags that style that line alone. Only known tags at the start of a line are read; the first unknown one stops the reading and stays in the text, so <gradient:...> still reaches the text parser. A value containing > is quoted: <if:"%kills% > 10">. Durations take a bare number of seconds, s or ms.

Look and layout

Models

Motion and text

The client animates motion between keyframes sent every half second, so periods start at two seconds.

Shining and flowing lines are redrawn at most ten times a second.

Who sees it

Clicks and buttons

click makes the hologram clickable. Without commands it cannot be clicked, unless code sets onClick.

A command line runs as the player, or from the console with console:. It can start with a filter — left:, right:, shift_left:, shift_right: or shift: — and takes the effect tokens ([MESSAGE], [SOUND], [TITLE], [SERVER], [TELEPORT] world;x;y;z, [ACTION] ns:id, [DELAY] 1s, …).

A <button:join> line runs click.buttons.join when that line is clicked, and gets its own background that lights when aimed at. The aimed target grows by hover-scale and sinks briefly when pressed.

Pages

Every viewer sees one page at a time, kept per player. lines is page 1 and runs click.commands; each entry under pages runs its own click while the viewer is on it.

page-interval turns pages on its own, and its timer restarts on every turn.

The Hologram handle

HologramLine: lines as data

An editor that lets staff style lines reads and writes them through HologramLine instead of parsing tags by hand.

HologramLine line = HologramLine.parse("<size:2><spin>&6Champion");
 
String edited = line.toBuilder()
        .size(1.5)
        .spin(null)          // null removes a tag
        .glow("#8a51c4")
        .build()
        .raw();              // tags in a fixed order, then the text

of(text) builds a plain line, builder() an empty one; every tag is a nullable field, null meaning not written. item, block and head clear each other. isModel() and hasTags() answer what they say. The bare defaults are constants: DEFAULT_SPIN, DEFAULT_BOB, DEFAULT_TYPEWRITER and the rest.