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 }
  ]
}
FieldDefaultDescription
enabledtruefalse hides the panel for this encounter
themedefaultTheme name (see Themes). The old field style is still read as a fallback and logs a warning
panelWidth, maxPanelWidththemePer-encounter width override
showPlayerBoardfalseList participants with alive/dead state
playerBoardPositionbottombottom or right
layoutnoneFree 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

FieldDefaultDescription
typerequiredSee the table below
enabledtruePer-element switch (the Ossuary disables boss-health-bar this way)
showIfnoneComma-separated conditions, all must hold (below)
textKeynoneLang key (used by title, custom-text)
formatbuilt-inFormat string with placeholders ({0}, {1}...), or a lang key
fontScale1.0Text size multiplier
iconper typeIcon name (below)
color, textColor, iconColortheme#RRGGBB
showBarfalseDraw a progress bar under the row
showTimer, italicfalse, trueboss-name and text options
showOnlyDuringBossWavefalseboss-health-bar: hide before the boss wave
countdown, showElapsed, elapsedTextKey, elapsedFormat, showLimit, softResetKey, softResetFallbacktimer / fight-timer options: show a countdown or the elapsed time, text when the encounter soft-reset
showStatus, showProgress, showAbilityCode, statusKeys, statusFallbackstruechallenge-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

typeShows
titleHeading text from textKey
boss-nameBoss display name (with showTimer, the fight time)
boss-health-barBoss health bar and name (needs a boss to exist)
wave-counterWave n / total (format default from lang)
kill-counter, mob-counterKills / mobs alive
timer, fight-timerPreparation / cooldown / fight timers
alive-playersAlive participants
difficulty-badgeSelected difficulty
tier-labelTier of the fight
modifierRolled modifier name
custom-texttextKey or format text
challenge-listRolled 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 }
  }
}
FieldDescription
framecartouche, bone, glass or none
frameSymbolCorner symbol (icon name); hideCornerSymbols hides them
panelWidth, maxPanelWidth, padding, textShadowPanel geometry
colorsbgTop, bgBottom, bgAlpha, border, borderAlpha, textPrimary, textSecondary, accent, accentSecondary, danger, success, barBg, barFill, barFillLow, parchment, title, pending
fontslabel, value, timer, title (sizes)
layoutRow 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.

FieldDescription
title.showBossName / title.showTierShow the boss name and the tier line (default true)
title.tierFormatroman (default) or number
title.bossTitlePrefix, title.bossTitleSuffixLang key built as prefix + bossKey + suffix for the boss name (suffix default -title)
sectionsOrdered list of blocks
themeReserved - currently not applied

Section type values:

TypeFields
summarylabelKey, labelFallback - heading
statsfields (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
challengesheaderKey/headerFallback, passedKey/passedFallback, failedKey/failedFallback, allPassedKey/allPassedFallback (text when every challenge passed), namePrefix (challenge name key = prefix + challenge id)
separatorBlank spacer

Boss defeated overlay (config/combat/boss-defeated.json)

File name must contain boss-defeated.

FieldDefaultDescription
titleKeyalegacyvsquest:boss-defeated-titleTitle lang key
showDurationtrueFight duration
showDamageTabletruePer-player damage
showChallengestrueRead but not used by the overlay yet
themeReserved - currently not applied

The sound is bossDefeatedSound in config/gui/combat.json (see Boss Status Effect HUD).

Press ESC to close