The hologram file

You never need to touch the files: the web editor and the commands write them. This page is for those who like to, and for reading what the editor made.

Each hologram is one file, plugins/HologramBB/holograms/<id>.yml. After editing one by hand, run /hbb reload; a mistake is reported in the console with the file and the key, and the other holograms still load.

Settings and layers

location: { world: world, x: 0.5, y: 65.0, z: 0.5, yaw: 0 }
view-distance: 48        # blocks
look-radius: 1.0         # how close to its centre a player must aim to be looking at it
update-interval: 20      # ticks between placeholder refreshes in text, 0 for never
hitbox: [1.0, 2.5]       # optional: width and height of the click box

layers:                  # drawn in this order
  title:
    type: text           # text | item | block
    text: "<gold>SHOP"   # MiniMessage, {player}, %placeholders%
    offset: [0, 2.2, 0]  # or one number, for height only
    scale: 1.0           # or [x, y, z]
    rotation: [0, 0, 0]  # degrees around x, y, z
    billboard: center    # fixed | vertical | horizontal | center
    background: transparent   # transparent | default | "#AARRGGBB"
    shadow: false
    see-through: false
    line-width: 200
    alignment: center    # center | left | right
    opacity: 255
    brightness: -1       # 0..15, or -1 for the world's light
    glow: none           # "#RRGGBB" for a coloured outline
    shadow-radius: 0     # ground shadow; 0 for none
    shadow-strength: 1
  icon:
    type: item
    item: EMERALD
    display: fixed       # none | head | gui | ground | fixed | ...
  base:
    type: block
    block: "minecraft:oak_log[axis=x]"

visibility:              # all optional
  permission: shop.see
  condition: "%player_level% >= 10"
  manual: false

Behavior

What a hologram does is a small set of states, walked by every player on their own. A state repeats its loop animations while the player is in it; its on list reacts to triggers, top to bottom, and the first one with a goto ends the list.

behavior:
  initial: idle
  states:
    idle:
      loop: [ "bob", "spin@icon" ]
      on:
        - when: { near: 4 }
          play: [ "pop-in@title" ]
          goto: close
    close:
      loop: [ "bob", "spin(period=30)@icon" ]
      on:
        - when: look
          play: [ "wiggle@icon" ]
        - when: right-click
          play: [ "bounce" ]
          run: [ "[player] warp shop", "[sound] entity.villager.yes" ]
        - when: { placeholder: "%vault_eco_balance% < 100" }
          text: { title: "<red>No money" }
        - when: { far: 6 }
          goto: idle

A hologram that only repeats animations can use the short form loop: [ bob ] instead of behavior.

Triggers

Each fires once, on the moment it becomes true.

Trigger	Fires when
near: 4	the player comes within 4 blocks
far: 6	the player goes beyond 6 blocks (use more than near, so it does not flicker)
look / look-away	they start / stop looking at it, with no block in the way
click, left-click, right-click	they click it
after: 200	200 ticks after the state began
placeholder: "%x% >= 10"	the comparison becomes true: < <= > >= == !=

A player who comes into range is met as one who just walked away: if the first state comes close to a state that walks away with animations, the hologram starts as it would be after that walk, already hidden if leaving hides it.

What a trigger does

Key	Does
play	Animations to start once
text	Text changes for that player: { layer: "new text" }
run	[player] command, [console] command, [message] text, [sound] name volume pitch. A line with no tag runs as the player.
goto	The state to go to

Animations

An animation is named name, name@layer or name(setting=value,…)@layer. Without @layer it plays on every layer. The ready-made ones are in Effects.

Your own go under clips: in the file, or in plugins/HologramBB/clips.yml to share them between holograms:

clips:
  sway:
    duration: 40
    loop: true
    tracks:
      - layer: title           # optional; otherwise the layer it is played on
        property: rotation-z   # translation-x/y/z, rotation-x/y/z, scale, opacity,
                               # reveal, count, rainbow, glow
        keyframes:
          - { t: 0,  value: -4, ease: ease-in-out-sine }
          - { t: 20, value: 4,  ease: ease-in-out-sine }
          - { t: 40, value: -4 }

ease shapes the stretch that starts at that keyframe: any easings.net name (ease-out-back, easeInOutSine), linear, step, or cubic-bezier(x1,y1,x2,y2).

The editor section

A hologram saved from the web editor also has an editor: section: the moments and their timelines, so it opens again as you left it. The plugin ignores it and plays the behavior and clips the editor wrote next to it. Editing those two by hand while keeping editor: means the editor will write over your changes the next time it saves; remove editor: if you take over by hand.