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)

Function	Signature	Description
`setAppVisibility`	`(containerId, appId, visible)`	Set visibility of a specific app.
`getAppVisibility`	`(containerId, appId)`	Returns visibility boolean for an app.
`showApp`	`(containerId, appId)`	Show an app.
`hideApp`	`(containerId, appId)`	Hide an app.
`toggleApp`	`(containerId, appId)`	Toggle an app's visibility.
`hideAllApps`	`(containerId)`	Hide all apps in a container.
`getVisibleApps`	`(containerId)`	Returns list of visible app IDs.
`getAvailableApps`	`(containerId)`	Returns all apps in a container.
`clearAllFlashMessages`	`()`	Clears flash message queue and hides app.
`clearMessagesFromSource`	`(source)`	Clears queued/current messages from a specific source.
`setDebug`	`(enabled)`	Toggles ImGui debug window.
`setVerboseLogging`	`(enabled)`	Toggles verbose logging.
`getGameplayAppContainerMounted`	`()`	Returns true if the UI component is mounted.

Legacy API (Deprecated)

Function	Replacement
`setContainerContext`	`setAppVisibility`
`getContainerContext`	`getVisibleApps`
`resetContainerContext`	`hideAllApps`
`onExtensionLoaded`	`()`
`onExtensionUnloaded`	`()`
`onScenarioFlashMessage`	`(...)`
`onScenarioFlashMessageClear`	`(...)`
`onScenarioNotRunning`	`()`
`onGameplayAppContainerMounted`	`(containerId)`
`onGameplayAppContainerUnmounted`	`(containerId)`
`onSerialize`	`()`
`onDeserialize`	`(data)`

Data Fields

Field	Description
`M.getAvailableContexts`	Alias for `getAvailableApps` - redirected for backwards compatibility.

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

Gameplay systems call showApp("gameplayApps", "drift") to activate HUD elements
Flash messages are queued via onGameplayFlashMessage and displayed one at a time
onUpdate advances message timers, cycling to the next message when duration expires
hideAllApps resets everything when a scenario ends or mode changes
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

Overview

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

Exports (M)

Function	Signature	Description
`setAppVisibility`	`(containerId, appId, visible)`	Set visibility of a specific app.
`getAppVisibility`	`(containerId, appId)`	Returns visibility boolean for an app.
`showApp`	`(containerId, appId)`	Show an app.
`hideApp`	`(containerId, appId)`	Hide an app.
`toggleApp`	`(containerId, appId)`	Toggle an app's visibility.
`hideAllApps`	`(containerId)`	Hide all apps in a container.
`getVisibleApps`	`(containerId)`	Returns list of visible app IDs.
`getAvailableApps`	`(containerId)`	Returns all apps in a container.
`clearAllFlashMessages`	`()`	Clears flash message queue and hides app.
`clearMessagesFromSource`	`(source)`	Clears queued/current messages from a specific source.
`setDebug`	`(enabled)`	Toggles ImGui debug window.
`setVerboseLogging`	`(enabled)`	Toggles verbose logging.
`getGameplayAppContainerMounted`	`()`	Returns true if the UI component is mounted.

Legacy API (Deprecated)

Function	Replacement
`setContainerContext`	`setAppVisibility`
`getContainerContext`	`getVisibleApps`
`resetContainerContext`	`hideAllApps`
`onExtensionLoaded`	`()`
`onExtensionUnloaded`	`()`
`onScenarioFlashMessage`	`(...)`
`onScenarioFlashMessageClear`	`(...)`
`onScenarioNotRunning`	`()`
`onGameplayAppContainerMounted`	`(containerId)`
`onGameplayAppContainerUnmounted`	`(containerId)`
`onSerialize`	`()`
`onDeserialize`	`(data)`

Data Fields

Field	Description
`M.getAvailableContexts`	Alias for `getAvailableApps` - redirected for backwards compatibility.

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

Gameplay systems call showApp("gameplayApps", "drift") to activate HUD elements
Flash messages are queued via onGameplayFlashMessage and displayed one at a time
onUpdate advances message timers, cycling to the next message when duration expires
hideAllApps resets everything when a scenario ends or mode changes
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

Gameplay App Containers

Overview

Exports (M)

Legacy API (Deprecated)

Data Fields

Internals

Container Structure

Flash Message Queue

Countdown Auto-Hide

How It Works

Additional Exports

See Also

On this page

Gameplay App Containers

Overview

Exports (M)

Legacy API (Deprecated)

Data Fields

Internals

Container Structure

Flash Message Queue

Countdown Auto-Hide

How It Works

Additional Exports

See Also

On this page