Panels & Layout

Overview

A HUD is a named entry under huds with one or more panels. Each panel has an anchor, layout, offsets, and lines. A line is either a single text content string or a map of elements (for row-style multi-part lines).

huds
 └── main                    # HudDefinition
      ├── permission / condition
      └── panels
           └── top-bar       # PanelDefinition
                ├── anchor, layout, offsets, ...
                └── lines
                     └── info   # PanelLineDefinition
                          └── elements (optional)
                               └── player  # ElementDefinition

Anchors

anchor places the panel on the virtual GUI screen (480×270 model used by shaders and the online editor):

Anchor	Position
TOP_LEFT	Top-left corner
TOP	Top center
TOP_RIGHT	Top-right corner
LEFT	Middle left
CENTER	Screen center
RIGHT	Middle right
BOTTOM_LEFT	Bottom-left corner
BOTTOM	Bottom center
BOTTOM_RIGHT	Bottom-right corner

Panels that share the same anchor are stacked with panel-spacing (global) and each panel’s own offsets.

Layout Modes

Layout	Behavior
ROW	Lines (or elements within a line) flow horizontally
COLUMN	Lines stack vertically

Panel Options

panels:
  sidebar:
    anchor: RIGHT
    layout: COLUMN
    offset-x: -5
    offset-y: 0
    layer: 0
    opacity: 1.0
    background: true
    padding: 4
    padding-y: 0
    gap: 0
    align: right
    line-spacing: 13
    permission: ""
    condition: null
    lines: {}

Option	Type	Default	Description
anchor	Enum	CENTER	Screen anchor (see table above)
layout	Enum	COLUMN	ROW or COLUMN
offset-x	Integer	0	Horizontal pixel offset from the anchor
offset-y	Integer	0	Vertical pixel offset from the anchor
layer	Integer	0	Draw order layer
opacity	Double	1.0	Panel opacity
background	Boolean	false	Draw a semi-transparent background behind lines
padding	Integer	4	Horizontal padding around content / background
padding-y	Integer	0	Extra vertical padding for background
gap	Integer	2	Gap between elements in a ROW line
align	String	"left"	Horizontal alignment: left, center, right
line-spacing	Integer	13	Vertical spacing between lines in a column
permission	String	""	Permission required to see the panel
condition	Object / null	null	Visibility condition
lines	Map	{}	Named lines

Legacy keys offsetx, offsety, and paddingy are still accepted and mapped to the hyphenated options.

Lines

Each entry under lines is a PanelLineDefinition.

Simple content line

lines:
  health:
    content: "<font:small><red>HP <white>%player_health%</font>"
    offset: 0
    update-interval: -1
    permission: ""
    condition: null

Multi-element line (ROW panels)

When elements is set, the line is composed of multiple pieces (typical for top bars):

lines:
  info:
    content: ""
    elements:
      player:
        content: "<font:small><white>%player_name%</font>"
        offset: 0
        update-interval: -1
        permission: ""
        condition: null
      coords:
        content: "<font:small><gray>%player_x% %player_y% %player_z%</font>"

Option	Type	Default	Description
content	String	""	MiniMessage + placeholders (ignored when elements is used for composition)
offset	Integer	0	Extra pixel offset for this line
update-interval	Integer	-1	Content refresh interval in ticks (-1 = global update-interval-ticks)
permission	String	""	Permission required for this line
condition	Object / null	null	Visibility condition
elements	Map / null	null	Named elements for multi-part lines

Element options

Option	Type	Default	Description
content	String	""	Display text
offset	Integer	0	Extra spacing offset
update-interval	Integer	-1	Per-element refresh interval in ticks
permission	String	""	Permission required for this element
condition	Object / null	null	Visibility condition

Conditions

Conditions can be attached to a HUD, panel, line, or element. If the condition fails, that part is hidden.

condition:
  left: "%player_world%"
  operator: "=="
  right: "world"

Field	Description
left	Left value (literal or PlaceholderAPI string with %...%)
operator	Comparison operator
right	Right value (literal or placeholders)

Operators

Operator	Numbers	Strings
==	Equal	Equal
!=	Not equal	Not equal
<	Less than	—
>	Greater than	—
<=	Less or equal	—
>=	Greater or equal	—

Numeric comparison is used when both sides parse as numbers; otherwise string comparison applies (== / != only for non-numeric).

Examples

Show a VIP panel only for players with a custom placeholder flag:

vip-panel:
  anchor: LEFT
  permission: "server.vip"
  condition:
    left: "%player_has_permission_server.vip%"
    operator: "=="
    right: "yes"
  lines:
    title:
      content: "<font:small><gold>VIP ACTIVE</font>"

Hide a line in the nether:

coords:
  content: "<font:small><gray>%player_x% %player_y% %player_z%</font>"
  condition:
    left: "%player_world%"
    operator: "!="
    right: "world_nether"

Permissions Hierarchy

Visibility checks are layered:

1. HUD permission / condition
2. Panel permission / condition
3. Line permission / condition
4. Element permission / condition

Empty permission means no permission check at that level.

Coordinate Model

The plugin and online editor share a 480×270 GUI coordinate model (1080p at GUI scale 4):

• Panel offset-x / offset-y are pixels relative to the anchor
• Background is drawn slightly above the text baseline (padding-aware)
• Use /minehud debug in-game to print resolved line positions (also written to the server log)
• The editor Debug checkbox shows the same pixel metrics

Practical Tips

• Use <font:small> for dense status text
• Set per-line update-interval for expensive placeholders (e.g. economy) and keep static text at the global interval
• Prefer softreload after text-only edits; use full reload after adding panels/lines that change pack assets
• Multiple HUDs under huds can target different permission groups or conditions