Module hud

Multiplayer HUD utilities

This system handles heads-up display (HUD) functionality in multiplayer, including damage feedback, timers, round indicators, scoreboards and world markers.

Execution context: * Server-side: initialization and game state control (shared via shared._hud) * Client-side: rendering HUD elements and reacting to events

Main features: * Damage numbers and directional damage indicators * Round / match timers and respawn timers * Scoreboards, team score breakdown, and player lists * In-world markers (players, objectives, etc.) * Banners, titles.

Functions

hudAddUnstuckButton () Enable the "Unstuck" pause menu button (server).
hudTick (dt) Process HUD-related events and health bar updates (client).
hudDrawTimer (time[, alpha]) Draw a countdown timer on the screen (client).
hudShowBanner (text, color) Queue an animated banner to be shown on screen (client).
hudDrawScoreboard (show, title, columns, groups) Render the in-game scoreboard UI (client).
hudDrawResults (bannerLabel, bannerColor, title, columns, groups[, continueFunction[, continueLabel]]) Render the end-of-match results scoreboard UI (client).
hudDrawScore2Teams (team1Color, team1Score, team2Color, team2Score[, alpha]) Draw a simple two-team score HUD (client).
hudDrawRounds (currentRound, maxRound[, width]) Display the current round indicator (client).
hudDrawRoundScroreBreakdown (header, teamNames, teamColors, scoreTable, drawTotal[, highlightColumn[, minWidth]]) Draw a breakdown table of team scores per round (client).
hudDrawTitle (dt, title[, show]) Draw a animated title banner (client).
hudDrawInformationMessage (message, alpha) Draw a centered information message panel (client).
hudDrawCountDown (time) Draw a large numeric countdown in the center of the screen (client).
hudDrawRespawnTimer (time) Draw a respawn countdown for the local player (client).
hudDrawPlayerWorldMarkers (players, lineOfSightRequired, maxRange[, color]) Draw world markers for a list of players (client).
hudDrawWorldMarkers (markers) Draw dynamic in-world markers on the HUD (client).
hudDrawDamageIndicators (dt) Draw directional damage indicators for the local player (client).
hudGameIsSetup () Check if the game has been set up by the host.
hudDrawGameSetup (settings) Draws the host-only game setup UI and initializes settings (client).
hudDrawPlayerList () Draw the current player list (client).
hudDrawGameModeHelpText (header, text[, headerColor]) Draw a game mode help text box (client).
hudDrawResultsAnimation (time, text[, backgroundColor]) Draw the animated end-of-match banner and camera motion (client).
hudDrawFade (dt) Draw a full-screen fade effect based on queued events (client).
hudDrawBanner (dt) Draw banners (client).


Functions

hudAddUnstuckButton ()
Enable the "Unstuck" pause menu button (server).

Allows clients to respawn themselves if stuck in the environment. This button has a cooldown of 10 seconds per client.

hudTick (dt)
Process HUD-related events and health bar updates (client).

Handles playerhurt events to trigger damage indicators for the local player and updates per-player health bar state. Also adds the "Unstuck" button into the pause menu if enabled.

Parameters:

  • dt number Delta time in seconds, used to update internal states.
hudDrawTimer (time[, alpha])
Draw a countdown timer on the screen (client).

Shows time remaining in a human-readable MM:SS format (for example 1:25) near the top of the screen. Plays a warning sound during the last seconds. Should be called from the UI render loop.

Parameters:

  • time number Time in seconds to display.
  • alpha number Alpha multiplier in range [0..1] for fading the timer. (optional)
hudShowBanner (text, color)
Queue an animated banner to be shown on screen (client).

The banner is added to an internal queue and consumed by hudDrawBanner.

Parameters:

  • text string Text shown in the banner.
  • color table Background color {r, g, b, a} for the banner.
hudDrawScoreboard (show, title, columns, groups)
Render the in-game scoreboard UI (client).

Displays a styled scoreboard with a title, column headers, and grouped rows. Each group can have a name and color, and each row corresponds to a player. The scoreboard animates when opening/closing.

Parameters:

  • show bool Whether the scoreboard should be visible.
  • title string Optional title displayed at the top; if empty or nil no title is shown.
  • columns table List of column descriptor tables: * name (string) Header label. * width (number) Column width in pixels. * align (string, optional) "left", "center", or "right".
  • groups table List of group tables: * name (string) Group header text. * color (table) RGB color {r, g, b}. * outline (bool) Draw outline around the group (optional). * dim (bool) De-emphasize style for the group (optional). * rows (table) List of row tables: * player (number) Player ID. * columns (table) Per-column text values.
hudDrawResults (bannerLabel, bannerColor, title, columns, groups[, continueFunction[, continueLabel]])
Render the end-of-match results scoreboard UI (client).

Shows an animated results banner followed by a scoreboard with per-team results. Includes a button panel allowing the host to choose game modes or continue.

Parameters:

  • bannerLabel string Text used in the initial results banner.
  • bannerColor table Banner background color {r, g, b, a}.
  • title string Scoreboard title.
  • columns table List of column descriptor tables (see hudDrawScoreboard).
  • groups table List of group tables (see hudDrawScoreboard).
  • continueFunction function Callback executed when the "Play Again" / continue button is pressed. (optional)
  • continueLabel string Custom label for the continue button (defaults to "Play Again"). (optional)

Returns:

  1. number boardWidth Width of the scoreboard in pixels.
  2. number boardHeight Height of the scoreboard in pixels.
  3. number param Animation parameter in range [0..1].
hudDrawScore2Teams (team1Color, team1Score, team2Color, team2Score[, alpha])
Draw a simple two-team score HUD (client).

Displays two team scores side by side, each in a colored box, near the top of the screen.

Parameters:

  • team1Color table Color {r, g, b} for Team 1.
  • team1Score number Score for Team 1.
  • team2Color table Color {r, g, b} for Team 2.
  • team2Score number Score for Team 2.
  • alpha number Alpha multiplier in range [0..1]. (optional)
hudDrawRounds (currentRound, maxRound[, width])
Display the current round indicator (client).

Renders text such as Round 2/5 below the main timer.

Parameters:

  • currentRound number Current round number (starting from 1).
  • maxRound number Total number of rounds in the match.
  • width number Minimum width in pixels for the text box. (optional)
hudDrawRoundScroreBreakdown (header, teamNames, teamColors, scoreTable, drawTotal[, highlightColumn[, minWidth]])
Draw a breakdown table of team scores per round (client).

Displays a table with team names on rows and rounds as columns, optionally including a total column. A specific round column can be highlighted.

Parameters:

  • header string Header text displayed at the top of the table.
  • teamNames table List of team names (string).
  • teamColors table List of team colors {r, g, b}.
  • scoreTable table

    List of round score arrays. Each entry is:

    scoreTable[round][teamIndex] = score
  • drawTotal bool If true, draw an extra total column for each team.
  • highlightColumn number Round index to visually highlight in the table (<= 0 disables highlight). (optional)
  • minWidth number Minimum width in pixels for the entire table. (optional)

Returns:

  1. number totalWidth Actual drawn width in pixels.
  2. number totalHeight Actual drawn height in pixels.

Usage:

    Example
    -- construct the score matrix
    local roundScores = {}
    roundScores[1] = { team1_round1_score, team2_round1_score }
    roundScores[2] = { team1_round2_score, team2_round2_score }
    -- for as many rounds required.

    local teamColors = { {1, 0, 0}, {0, 0, 1} }
    local teamNames = { "Red team", "Blue team" }

    hudDrawRoundScroreBreakdown("Current score", teamNames, teamColors, roundScores, false, currRound)
hudDrawTitle (dt, title[, show])
Draw a animated title banner (client).

Fades a title message in and out near the top of the screen. If show is nil, the title will remain visible for 5 seconds and then fade out automatically.

Should be called every frame from the client’s UI draw loop.

Parameters:

  • dt number Time step in seconds, used for timing and fade animation.
  • title string Title text to display.
  • show bool Explicit visibility flag; if nil the function will auto-hide the title after 5 seconds. (optional)
hudDrawInformationMessage (message, alpha)
Draw a centered information message panel (client).

Renders a small text panel with the specified message near the top of the screen.

Parameters:

  • message string Text to display.
  • alpha number Alpha multiplier in range [0..1] for fading.
hudDrawCountDown (time)
Draw a large numeric countdown in the center of the screen (client).

Shows the remaining time as a big number with a fade effect.

Parameters:

  • time number Remaining time in seconds. Values <= 0 disable rendering.
hudDrawRespawnTimer (time)
Draw a respawn countdown for the local player (client).

When time is greater than 0, displays a "Respawn in..." message and a numeric countdown using hudDrawCountDown. Also triggers a brief fade effect as the respawn approaches.

Parameters:

  • time number Remaining respawn time in seconds, or nil / <= 0 if alive.
hudDrawPlayerWorldMarkers (players, lineOfSightRequired, maxRange[, color])
Draw world markers for a list of players (client).

Creates marker entries for each valid remote player and forwards them to hudDrawWorldMarkers. Uses the player position and name as label.

Parameters:

  • players table List of player IDs.
  • lineOfSightRequired bool If true, markers are hidden when occluded.
  • maxRange number Maximum range in meters; markers beyond this are hidden.
  • color table Color {r, g, b, a}; defaults to white. (optional)
hudDrawWorldMarkers (markers)
Draw dynamic in-world markers on the HUD (client).

Projects world-space marker positions to screen space and renders labels and/or icons. Markers may include line-of-sight checks, maximum range, and optional health bars for associated players.

Parameters:

  • markers table List of markers.

Usage:

  • A marker table can have these members:
    pos (Vec3)                  World-space position.
    offset (Vec3)               offset added before projection. (Optional)
    color ({r, g, b, a})        Marker color.
    label (string)              text label. (Optional)
    maxRange (number)           max distance (default 9999.0). (Optional)
    lineOfSightRequired (bool)  hide when occluded.
    player (number)             player ID used for occlusion/vehicle checks. (Optional)
    icon (string)               icon image path. (Optional)
    uiOffset ({x, y})           2D offset after projection. (Optional)
    drawIconInView (bool)       draw icon when marker is on-screen. (Optional)
    iconColor ({r, g, b})       icon color override. (Optional)
  • Example
   local worldMarkers = {}
   for p in Players() do
       local marker = {}
       marker.pos = GetPlayerTransform(p).pos
       marker.color = {1.0, 1.0, 1.0}
       marker.label = GetPlayerName(p)
       marker.offset = Vec(0,2,0)
       marker.lineOfSightRequired = false
       marker.player = p
       worldMarkers[1 + #worldMarkers] = marker
   end
   hudDrawWorldMarkers(worldMarkers)
hudDrawDamageIndicators (dt)
Draw directional damage indicators for the local player (client).

Renders fade-out indicators pointing towards recent damage sources, based on the local player’s orientation and the attack direction.

Parameters:

  • dt number Delta time in seconds, used to fade indicators.
hudGameIsSetup ()
Check if the game has been set up by the host.

Returns the current setup state as managed by the HUD system, typically toggled when the host presses Start in hudDrawGameSetup.

Returns:

    bool setup true if the game has been set up, false otherwise.
hudDrawGameSetup (settings)

Draws the host-only game setup UI and initializes settings (client).

For host:

Two buttons buttons will be drawn;

  • Start that progresses the setup (hudGameIsSetup() will return true).

  • Settings that toggles the visibility of the settings view where the host can choose settings from those provided.

For clients:

  • A message: "Waiting for host ..." is drawn on the screen until the host is done configuring settings.

Parameters:

  • settings table Array of groups containing configuration items.

Returns:

    bool started true if the Play/Start button has been pressed, false otherwise.

Usage:

    -- Example settings table that can be passed to hudDrawGameSetup(...)
local settings = {
  {
    title = "",
    items = {
      {
        key    = "savegame.mod.settings.time",
        label  = "Time",
        info   = "Select match time.",
        options = {
          { label = "05:00", value = 5*60 },
          { label = "10:00", value = 10*60 },
          { label = "03:00", value = 3*60 },
        }
      },
      {
        key    = "savegame.mod.settings.unlimited",
        label  = "Unlimited tool ammo",
        info   = "Toggle unlimited ammo",
        options = {
          { label = "On", value = 1 }, -- Use value = 1 or 0 for boolean values.
          { label = "Off", value = 0 },
        }
      }
    }
  }
}
hudDrawPlayerList ()
Draw the current player list (client).

Shows a panel listing all players in the session, highlighting the local player.

hudDrawGameModeHelpText (header, text[, headerColor])
Draw a game mode help text box (client).

Useful for explaining rules or objectives of the current game mode.

Parameters:

  • header string Header text shown at the top of the box. Ignored if nil or "".
  • text string Main body text to display.
  • headerColor table Color {r, g, b, a} for the header (defaults to yellow). (optional)
hudDrawResultsAnimation (time, text[, backgroundColor])
Draw the animated end-of-match banner and camera motion (client).

Moves the camera, plays intro/outro sounds, and animates a centered banner with the given text.

Parameters:

  • time number Elapsed animation time in seconds.
  • text string Banner text.
  • backgroundColor table Table representing background color ({r, g, b, a}). Defaults to COLOR_BLACK_TRNSP. (optional)

Returns:

    bool finished true when the animation has fully finished.
hudDrawFade (dt)
Draw a full-screen fade effect based on queued events (client).

Consumes hudFade events and performs fade-in, hold, and fade-out over time, optionally disabling HUD while fully black.

Parameters:

  • dt number Delta time in seconds.
hudDrawBanner (dt)
Draw banners (client).

Draws banners that have been enqueued via hudShowBanner. Should be called continuously to animate and consume the banner queue.

Parameters:

  • dt number Delta time in seconds used to advance the current banner animation.
generated by LDoc 1.5.0 Last updated 2025-12-09 10:41:23