Settings reference

Declare your controls in settings, a flat array where each entry is one object describing one row.

Every control takes id, type, label, default, and an optional description, which UMM shows as a tooltip when the player hovers the row. Two entries break that pattern: group is a divider with no value at all, and checks keeps its ids one level down in options.

toggle

{ id: "enabled", type: "toggle", label: "Enabled", default: true,
  description: "Optional hover tooltip." }

Value is a boolean.

slider

{ id: "opacity", type: "slider", label: "Opacity",
  min: 20, max: 100, step: 5, default: 90, unit: "%" }

min, max and step bound and quantise the value. Left out, they fall back to 0, 100 and 1. unit is optional and appended to the readout, for example 90%.

The readout doubles as an editor: clicking it swaps in a text field, so a player can type an exact value instead of dragging to it.

Value is a number.

select

{ id: "corner", type: "select", label: "Corner", default: "tl",
  options: [ { value: "tl", label: "Top Left" },
             { value: "tr", label: "Top Right" } ] }

value is what you store and receive; label is what the player sees. default is a value.

Optional sort: true lists options alphabetically by label. Optional icons: "hero" draws Deadlock hero portraits, which additionally requires a per-option img field holding the hero image alias.

Hero image aliases are not derivable

The image alias is not the internal hero_<x> name and cannot be computed from it: hero_atlas (Abrams) is bull, hero_ghost (Lady Geist) is spectre, hero_viper (Vyper) is kali. Verify any alias against the packed VPK before shipping it.

checks

{ type: "checks", label: "Visible Panels", description: "Optional hover tooltip.",
  options: [
    { id: "show_counters",  label: "Counters", default: true },
    { id: "show_breakdown", label: "Stats",    default: true }
  ] }

Several booleans on one row, rendered as inline checkboxes under a single label. Use it to group related on/off flags instead of stacking separate toggle rows.

The row itself has no id, no default and no value. Each option is an independent boolean keyed by its own id, exactly like a standalone toggle: applySetting(key, value) receives one call per option id, and storage is per option.

That makes a checks row interchangeable with the equivalent separate toggles. You can split or merge them later without changing any saved value.

The single reset icon restores every option to its own default.

group

{ type: "group", label: "Appearance" }

A titled divider, not a control. It carries no id, default or value. Every control after it falls under that heading until the next group.

settings: [
  { type: "group", label: "Appearance" },
  { id: "opacity", type: "slider", label: "Opacity", min: 20, max: 100, default: 90, unit: "%" },
  { type: "group", label: "Behaviour" },
  { id: "autohide", type: "toggle", label: "Auto-hide", default: false },
]

Note

If you iterate your own settings array anywhere, guard type === "group" and type === "checks". Neither carries a value, and checks holds its ids one level down in options.

Value precedence

When your mod registers, UMM merges your manifest into its registry. Strongest first:

1. Values already in the current session’s registry, so settings survive your mod re-registering on the way from the dashboard into a match.
2. The values you sent alongside the manifest, in the optional values field.
3. Your declared defaults.

This is what makes settings hold when the player goes from the main menu into a game, where your mod’s script boots afresh and announces itself again.

What survives a restart

Storage holds only the values that differ from your declared default; everything else is rebuilt from your manifest at boot. Values are keyed by setting id, so shipping an update that edits the manifest has consequences:

• Changing a default moves every player who never touched that setting onto the new value. Only the ones who had changed it keep what they had.
• Renaming a setting id orphans its stored value, the same way renaming your mod id does. So does renaming a select option’s value, which is what enum values are stored by. Reordering options is safe; an option that no longer exists falls back to the default.
• Removing a setting drops its stored value on the next save.
• Changing a slider’s min, max or step reinterprets stored values, because a slider value is stored as an index into that grid. A grid with a different number of steps is detected and falls back to the default, but one with the same number of steps is not, and the old index then reads as a different value. Give the setting a new id when you change its range.
• Two settings sharing one id in your manifest: only the first persists.
• Mod ids are stored as a 16-bit hash. Two loaded mods that collide there both fail to restore until one is renamed.

A mod that is not installed when settings are loaded keeps its stored values. UMM carries the section through untouched on the next save rather than dropping it, so uninstalling a mod for a few sessions does not lose its settings.

Each of these is logged to the console with a [UMM] prefix as it happens.