Getting started

From an empty server to a clickable panel on a wall.

You need a Paper server on Minecraft 1.19.4 or newer, Java 17 or newer, and a matching PacketEvents build. The placement commands require holopanels.admin plus the relevant administrative child permission; operators receive them by default.

1. Install the jar and its one dependency

   HoloPanels needs packetevents. Panels are sent as packets, so nothing is saved into the world and no entity exists for another plugin to trip over. Put both jars in plugins/ and start the server.

2. Copy an example view

   Six complete views ship in the repository's examples/ directory. They are not inside the jar, so copy the ones you want:

   cp examples/views/*.yml   plugins/HoloPanels/views/
   cp examples/boards.yml    plugins/HoloPanels/boards.yml

   Between them they use every panel type, every built-in action and every condition kind.

3. Check the files before applying them

   /holopanels validate
   

   This parses everything and reports problems without touching what is running. Then apply it:

   /holopanels reload
   

4. Put a board somewhere

   Look at the wall you want it on and run:

   /holopanels wall welcome
   

   wall raycasts up to 12 blocks, sits the board just off the face it hit, and works out the yaw so the board faces out of the wall. If you would rather place it where you stand, /holopanels here welcome uses your feet and your facing.

5. Line it up

   /holopanels nudge welcome right 0.2
   /holopanels nudge welcome up 0.1
   

   nudge moves the board along its own axes, the same ones panel offsets use, so a placement can be trimmed by tenths without editing a file. Every placement command writes boards.yml and reloads, and comments in the file survive the rewrite.

A minimal board without the repository examples

Create views/welcome.yml:

id: holopanels:welcome
panels:
  greeting:
    type: text
    lines:
      - "<aqua><bold>Welcome</bold>"
      - "<gray>Hello, <white>%player_name%</white>."

Add an unplaced board to boards.yml:

boards:
  welcome:
    root-view: holopanels:welcome

Validate, reload, then place it with /holopanels wall welcome. Without PlaceholderAPI the %player_name% token remains literal, while the rest of the panel still renders.

What ends up on disk

A board is a position in the world; a view is what it shows. They are separate files because they change for different reasons: you move a board in game, and you edit a view in a text editor.

Placing boards without leaving the game

• /holopanels here <board>: at your feet, facing the way you look.
• /holopanels wall <board> [gap]: against the block you are looking at.
• /holopanels move <board> <x> <y> <z> [yaw]: exact coordinates. ~ keeps the current value, so move welcome ~ ~1 ~ raises it a block and move welcome ~ ~ ~ 90 turns it where it stands.
• /holopanels nudge <board> <direction> [distance]: right, left, up, down, forward or back, in the board's own axes.
• /holopanels unplace <board>: drop the anchor, keep the board defined.
• /holopanels remove <board> confirm: delete it from boards.yml entirely.

unplace and remove differ on purpose. unplace clears the anchor and leaves the board ready to be placed again; remove takes its view binding, distances and conditions with it, which is why it asks for confirm.

When something does not appear

Work down this list before anything else:

1. /holopanels list: is the board placed at all?
2. /holopanels debug: what is currently rendered to you, including which view your session is on.
3. Is the board's own visible-if passing for your account? A board that fails its condition is never rendered and never has a click region.
4. Are you inside visibility-distance? Clicking additionally needs to be inside click-distance.
5. If %placeholders% are showing as literal text, PlaceholderAPI is not installed, which is a quick way to confirm the rest of the pipeline works.

For the complete diagnostic path, including click and reload failures, continue to Troubleshooting.