XML Format

This document describes the XML format used by Hudkit to define HUD layouts. You can edit this XML directly in Studio or provide it manually in offline mode.

Document Structure

<?xml version="1.0" encoding="UTF-8"?>
<hud>
    <layout>
        ...
    </layout>
</hud>

Root Elements

Element	Description
<hud>	Root element of the document
<layout>	Container for all HUD elements. This has to be a direct child of <hud>

Element Types

<group>

An ignored element meant for organization. Groups don’t render anything themselves but help structure your HUD defenition.

<group key="player-info">
    <element>....</element>
    <element>...</element>
</group>

Attributes:

Attribute	Type	Required	Description
key	string	No	Identifier for progrematic access

Any unrecognized XML tag behaves the same as <group>. It passes through to its children without rendering anything. This means when writing XML by hand, you can use any tag name for organization.

<element>

A positioned container that holds visible content like text or images.

<element key="health" x="10" y="-20" anchor="bottom-left" align="left">
    <text key="health-text">Health: %player_health%</text>
</element>

Attributes:

Attribute	Type	Required	Default	Description
key	string	No	-	Identifier for progrematic access
x	integer	Yes	-	Horizontal offset from anchor (in font pixels)
y	integer	Yes	-	Vertical offset from anchor (in font pixels)
anchor	string	No	center	Screen anchor point (see Anchor Values)
align	string	No	center	Text alignment (see Alignment Values)

<text>

Text content to display. Supports MiniMessage formatting and placeholders.

<text key="welcome-message">Welcome, %player_name%!</text>

Attributes:

Attribute	Type	Required	Description
key	string	No	Identifier for progrematic access

background

Adds a background fill behind the parent element’s content.

<element key="score" x="0" y="0" anchor="top-center" align="center">
    <background type="fill" expandX="4" expandY="2" />
    <text key="score-text">Score: 100</text>
</element>

Attributes:

Attribute	Type	Required	Default	Description
type	string	Yes	-	Background type. Currently only fill is supported
expandX	integer	No	0	Horizontal padding in font pixels
expandY	integer	No	0	Vertical padding in font pixels
expand	integer	No	0	Shorthand for both expandX and expandY

Anchor Values

The anchor attribute determines where on the screen the element is positioned relative to.

Value	Description
top-left	Top-left corner of the screen
top-center	Top center of the screen
top-right	Top-right corner of the screen
middle-left	Middle left of the screen
center	Center of the screen (default)
middle-right	Middle right of the screen
bottom-left	Bottom-left corner of the screen
bottom-center	Bottom center of the screen
bottom-right	Bottom-right corner of the screen

Alignment Values

The align attribute determines how text is aligned within the element.

Value	Description
left	Text aligned to the left
center	Text centered (default)
right	Text aligned to the right

Placeholders

Text content can include placeholders that are resolved at runtime. Placeholders are wrapped in percent signs:

<text key="player-info">%player_name% - %player_level%</text>

See Dynamic Content for how to implement placeholder resolution.

MiniMessage Formatting

Text content supports MiniMessage formatting for rich text:

<text key="colored">
    <![CDATA[<red>Health:</red> <green>100</green>]]>
</text>

When using angle brackets in text content, wrap it in <![CDATA[...]]> to prevent XML parsing issues.