Status Effect HUD

Status Effect HUD

Status Effect HUD is a lightweight Factorio 2.1 framework that lets other mods display compact, live status rows in the player's top GUI.

Features

• Multiple registered rows with deterministic ordering
• Icons, labels, tooltips, timers, alerts, and rich-text captions
• Automatic refresh every 30 ticks and refresh on player join
• Per-player visibility overrides
• Runtime metadata updates without unregistering a row
• Dynamic icon, label, and tooltip values from a mod's callback
• Save/load-safe element registry
• Multiplayer-safe rendering

Basic Integration

Register a remote callback in your mod:

remote.add_interface("my-mod", {
  get_hud_data = function(player_index, element_name)
    return {
      caption = "Online",
      visible = true,
    }
  end,
})

Register the row with Status Effect HUD during on_init or on_configuration_changed:

remote.call("status-effect-hud", "register_element", {
  mod_name = "my-mod",
  element_name = "status",
  label = "Status:",
  icon = "item/iron-plate",
  tooltip = "Current status",
  order = 10,
  data_callback_name = "get_hud_data",
})

The callback receives player_index and element_name, and returns:

{
  caption = "Ready",
  visible = true,
  label = "Status:",       -- optional dynamic title
  icon = "item/iron-plate", -- optional dynamic icon
  tooltip = "Updated help",  -- optional dynamic tooltip
}

Layout Options

Registration accepts these optional numeric settings:

• width: total row width; default 220
• icon_size: icon width and height; default 28
• title_width: reserved label width; default 84
• value_width: minimum value width; default 64
• value_margin: right margin for the value; default 8
• value_align: "left", "center", or "right"; default "right"
• order: lower values appear higher in the stack

Runtime API

Update metadata without removing the row:

remote.call("status-effect-hud", "update_element", "my-mod", "status", {
  label = "Warning:",
  icon = "utility/warning_icon",
  order = 5,
})

Override visibility for one player:

remote.call("status-effect-hud", "set_element_visibility", "my-mod", "status", player.index, false)
remote.call("status-effect-hud", "clear_element_visibility", "my-mod", "status", player.index)

Remove a row completely:

remote.call("status-effect-hud", "unregister_element", "my-mod", "status")

The callback remains the source of truth unless a per-player visibility override is set. All registration data and visibility overrides are stored in Factorio's persistent storage table.