Bindings Legend

HUD overlay showing contextual input bindings with modifier support, vehicle-specific actions, and auto-fade.

Overview

ui_bindingsLegend manages the on-screen bindings/controls legend. It dynamically shows relevant keybindings based on active modifiers, vehicle-specific actions, and gameplay context, with priority-based layering and auto-fade.

Extension path: lua/ge/extensions/ui/bindingsLegend.lua
Dependencies: core_input_actions, core_input_bindings

Exports (M)

Data Fields

Internals

Action Sets & Priority

Actions are stored as labeled sets with priority. Higher priority sets take precedence:

addActions("vehicleSpecific", vehicleSpecificActions, {
  priority = 10,
  removeIfOverwrittenWithHigherPriority = true,
  ttl = 10  -- auto-remove after 10 seconds
})

When multiple sets exist, only the highest-priority set's actions are shown (others are hidden).

Modifier System

The module tracks 6 custom modifiers + shift/ctrl/alt via bitmask:

-- Modifier constants
local MODIFIER1 = 64   -- custom modifier 1
local MODIFIER2 = 128  -- custom modifier 2
-- ...up to MODIFIER6 = 2048

onModifierChanged(newModifiers) scans all bindings to find actions matching the exact modifier combination, then displays them as a "modified" action set at priority 9.

Vehicle-Specific Actions

On vehicle switch (onVehicleSwitched):

1. Fetches actions with cat == "vehicle_specific" from core_input_actions
2. Shows them temporarily (10s TTL) in "fleeting" mode
3. Displays a message: "Press [action] to show/hide vehicle specific actions"

Fade Behavior

The legend auto-fades after fadeDelaySeconds (default 7s) of inactivity. New data resets the timer. Currently shouldFade() always returns false (fade disabled).

UI Data Structure

guihooks.trigger("setActionsForLegend", {
  actions = {...},            -- sorted action list
  constantActions = {...},    -- always-shown actions
  additionalData = {
    vehicleSpecificStatus = "enabled"|"disabled"|"fleeting"|"inactive",
    resetFade = true,
  },
  modifierActionInfos = {     -- modifier button states
    customModifier1 = { active = true },
    shift = { active = false },
  },
  showApp = true
})

Event Hooks

How It Works

1. Gameplay systems call addActions() to push context-sensitive bindings
2. Modifier keys trigger onModifierChanged() to show modified bindings
3. Vehicle switches temporarily show vehicle-specific actions
4. All action sets are merged by priority and sent to UI
5. Legend auto-fades after inactivity (currently disabled)

Additional Exports

The following exports are available but not yet documented in detail:

• M.addActions
• M.enableShowVehicleSpecificActions
• M.onActionFilterUpdated
• M.onClientEndMission
• M.onClientStartMission
• M.onDeserialized
• M.onDeviceChanged
• M.onExtensionLoaded
• M.onModifierChanged
• M.onUpdate
• M.onVehicleSwitched
• M.resetFade
• M.sendDataToUI
• M.setDebug
• M.toggleShowApp
• M.toggleShowVehicleSpecificActions
• M.triggerInputAction