Boss Systems
Encounter HUD & Combat Screens
What players see during and after an encounter fight: the HUD panel (hud block of an encounter definition), HUD themes, the death recap window and the boss-defeated overlay. All of it is client-side presentation driven by data.
The hud block
Part of an encounter definition in config/encounters/*.json.
"hud": {
"enabled": true,
"theme": "void-trials",
"showPlayerBoard": true,
"playerBoardPosition": "bottom",
"elements": [
{ "type": "title", "textKey": "albase:encounter-ossuary-hud-title", "fontScale": 1.2 },
{ "type": "boss-name", "icon": "tombstone", "color": "#FFFFFF", "showTimer": true },
{ "type": "challenge-list", "showStatus": true, "showProgress": false }
]
}| Field | Default | Description |
|---|---|---|
enabled | true | false hides the panel for this encounter |
theme | default | Theme name (see Themes). The old field style is still read as a fallback and logs a warning |
panelWidth, maxPanelWidth | theme | Per-encounter width override |
showPlayerBoard | false | List participants with alive/dead state |
playerBoardPosition | bottom | bottom or right |
layout | none | Free tag used by packs (wave-progress in the shipped wave encounters); not interpreted by the panel |
elements | [] | Rows, drawn top to bottom in the listed order |
Element fields
| Field | Default | Description |
|---|---|---|
type | required | See the table below |
enabled | true | Per-element switch (the Ossuary disables boss-health-bar this way) |
showIf | none | Comma-separated conditions, all must hold (below) |
textKey | none | Lang key (used by title, custom-text) |
format | built-in | Format string with placeholders ({0}, {1}...), or a lang key |
fontScale | 1.0 | Text size multiplier |
icon | per type | Icon name (below) |
color, textColor, iconColor | theme | #RRGGBB |
showBar | false | Draw a progress bar under the row |
showTimer, italic | false, true | boss-name and text options |
showOnlyDuringBossWave | false | boss-health-bar: hide before the boss wave |
countdown, showElapsed, elapsedTextKey, elapsedFormat, showLimit, softResetKey, softResetFallback | timer / fight-timer options: show a countdown or the elapsed time, text when the encounter soft-reset | |
showStatus, showProgress, showAbilityCode, statusKeys, statusFallbacks | true | challenge-list: status per challenge (active, passed, failed, pending mapped to lang keys / fallback words) |
position, offsetX and offsetY exist in the schema and appear in older packs, but rows are stacked in order; do not rely on them for placement.
Element types
type | Shows |
|---|---|
title | Heading text from textKey |
boss-name | Boss display name (with showTimer, the fight time) |
boss-health-bar | Boss health bar and name (needs a boss to exist) |
wave-counter | Wave n / total (format default from lang) |
kill-counter, mob-counter | Kills / mobs alive |
timer, fight-timer | Preparation / cooldown / fight timers |
alive-players | Alive participants |
difficulty-badge | Selected difficulty |
tier-label | Tier of the fight |
modifier | Rolled modifier name |
custom-text | textKey or format text |
challenge-list | Rolled challenges with live status |
Row icons are drawn from icon or the type's default; known names include pyramid, blades, scarab, sun, ankh, eye, void, crossbone, tombstone, coffin.
showIf
"showIf": "bosswave,hasmodifier" - every condition must be true. Known conditions: bosswave, haschallenges, hasmodifier, hasboss, passive / active (ambient encounter waiting vs fighting), hascooldown. An unknown word counts as true.
Themes (config/gui/hud-themes.json)
One object per theme name; packs add themes, a later pack overrides a theme of the same name. Built-in themes are default (gold cartouche), bone and void. A custom theme with a built-in name merges over that built-in; otherwise it merges over default, so only the fields you want to change are needed.
{
"bone-ossuary": {
"frame": "bone",
"frameSymbol": "crossbone",
"hideCornerSymbols": true,
"panelWidth": 340,
"padding": 12,
"textShadow": true,
"colors": { "bgTop": "#1A1512", "bgBottom": "#0E0B0A", "bgAlpha": 0.94, "border": "#8A8278", "accent": "#E8DCCA" },
"fonts": { "label": 12, "value": 13, "timer": 14, "title": 14 },
"layout": { "lineHeight": 20, "barWidth": 180 }
}
}| Field | Description |
|---|---|
frame | cartouche, bone, glass or none |
frameSymbol | Corner symbol (icon name); hideCornerSymbols hides them |
panelWidth, maxPanelWidth, padding, textShadow | Panel geometry |
colors | bgTop, bgBottom, bgAlpha, border, borderAlpha, textPrimary, textSecondary, accent, accentSecondary, danger, success, barBg, barFill, barFillLow, parchment, title, pending |
fonts | label, value, timer, title (sizes) |
layout | Row sizes: lineHeight, headerHeight, barHeight, barWidth, iconSize, iconGap, playerRowHeight, challengeRowHeight, playerBoardMaxColumns, and spacing values (headerGap, dividerGap, playerListGap, modifierHeight, modifierGap, tierLabelHeight, tierLabelGap, titleLineHeight, titleGap, timerLineHeight, timerGap) |
Unknown keys are ignored. The shipped hud-themes.json contains bossName, challengePassed and challengePending colours; these are not read by the current panel. Shipped themes: void, bone, gold, duat, void-trials, bone-ossuary.
Death recap (config/combat/death-recap.json)
Shown to a player who dies in an encounter. The file name must contain death-recap; the last one loaded wins. Without it the window shows only a default summary block.
| Field | Description |
|---|---|
title.showBossName / title.showTier | Show the boss name and the tier line (default true) |
title.tierFormat | roman (default) or number |
title.bossTitlePrefix, title.bossTitleSuffix | Lang key built as prefix + bossKey + suffix for the boss name (suffix default -title) |
sections | Ordered list of blocks |
theme | Reserved - currently not applied |
Section type values:
| Type | Fields |
|---|---|
summary | labelKey, labelFallback - heading |
stats | fields (labelKey, fallback, format, value = time, damageDealt or damageTaken), minLabelKey/secLabelKey and minFallback/secFallback for the time units. time format placeholders: {0} minutes, {1} minute label, {2} seconds, {3} second label |
challenges | headerKey/headerFallback, passedKey/passedFallback, failedKey/failedFallback, allPassedKey/allPassedFallback (text when every challenge passed), namePrefix (challenge name key = prefix + challenge id) |
separator | Blank spacer |
Boss defeated overlay (config/combat/boss-defeated.json)
File name must contain boss-defeated.
| Field | Default | Description |
|---|---|---|
titleKey | alegacyvsquest:boss-defeated-title | Title lang key |
showDuration | true | Fight duration |
showDamageTable | true | Per-player damage |
showChallenges | true | Read but not used by the overlay yet |
theme | Reserved - currently not applied |
The sound is bossDefeatedSound in config/gui/combat.json (see Boss Status Effect HUD).