Gameplay App Containers

Manages visibility of in-game HUD apps (rally, drift, drag, countdown, flash messages) and a queued flash message system.

Overview

ui_gameplayAppContainers controls which gameplay HUD apps are visible during gameplay. It provides a container-based visibility system and a FIFO flash message queue with timer-based display cycling.

Extension path: lua/ge/extensions/ui/gameplayAppContainers.lua

Exports (M)

Legacy API (Deprecated)

Data Fields

Internals

Container Structure

The default container gameplayApps contains six apps:

local appContainersById = {
  ['gameplayApps'] = {
    apps = {
      rally = { visible = false },
      drift = { visible = false },
      drag = { visible = false },
      pointsBar = { visible = false },
      flashMessage = { visible = false },
      countdown = { visible = false },
    },
    trigger = 'setGameplayAppVisibility',
  }
}

Visibility changes trigger guihooks.trigger("setGameplayAppVisibility", ...) to update the UI.

Flash Message Queue

Messages are queued with a 50-message limit. Each message has a source, duration, and timer:

-- Messages routed from drift/drag sources
ui_gameplayAppContainers.onGameplayFlashMessage({
  source = 'drift',
  data = {{'Drift Combo x5!', 3.0, 0, false}}
})

The onUpdate callback processes the queue using dtSim accumulation - messages pause when the simulation is paused.

Countdown Auto-Hide

When scenario countdown messages are detected (ui.scenarios.go), the countdown app is shown and auto-hidden after the "Go" message TTL expires.

How It Works

1. Gameplay systems call showApp("gameplayApps", "drift") to activate HUD elements
2. Flash messages are queued via onGameplayFlashMessage and displayed one at a time
3. onUpdate advances message timers, cycling to the next message when duration expires
4. hideAllApps resets everything when a scenario ends or mode changes
5. State is serialized/deserialized for session persistence

Additional Exports

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

• M._countdownHideTimer
• M.clearAllFlashMessages
• M.clearMessagesFromSource
• M.getAppVisibility
• M.getAvailableApps
• M.getContainerContext
• M.getGameplayAppContainerMounted
• M.getVisibleApps
• M.hideAllApps
• M.hideApp
• M.onDeserialize
• M.onExtensionLoaded
• M.onExtensionUnloaded
• M.onGameplayAppContainerMounted
• M.onGameplayAppContainerUnmounted
• M.onGameplayFlashMessage
• M.onScenarioFlashMessage
• M.onScenarioFlashMessageClear
• M.onScenarioNotRunning
• M.onSerialize
• M.onUpdate
• M.resetContainerContext
• M.setAppVisibility
• M.setContainerContext
• M.setDebug
• M.setVerboseLogging
• M.showApp
• M.toggleApp