Top Bar

Manages the top navigation bar entries, visibility, and active item state.

Overview

ui_topBar controls the top navigation bar in the game UI. It manages a list of entries (defined in ui_topBar_config), handles item selection/navigation, and synchronises state with the CEF UI via guihooks.

Extension path: lua/ge/extensions/ui/topBar.lua Dependencies: ui_topBar_config

Exports (M)

Function	Signature	Description
`show`	`()`	Shows the top bar.
`hide`	`()`	Hides the top bar.
`selectItem`	`(item)`	Selects an entry by id or table, triggers its action.
`selectPreviousItem`	`(loop)`	Navigates to the previous visible item.
`selectNextItem`	`(loop)`	Navigates to the next visible item.
`setActiveItem`	`(item)`	Sets the active item without triggering action.
`addEntry`	`(key, entry)`	Adds a new top bar entry.
`removeEntry`	`(key)`	Removes an entry by key.
`updateEntry`	`(key, entry)`	Updates an existing entry or adds it.
`updateEntries`	`(entries)`	Replaces all entries.
`getEntry`	`(key) → entry`	Returns a single entry.
`getEntries`	`() → table`	Returns all entries.
`requestData`	`()`	Sends all bar state + game state to UI.
`requestEntries`	`()`	Sends entries to UI.
`requestGameState`	`()`	Sends game state flags to UI.
`updateVisibleItems`	`()`	Recalculates which items are visible.
`updateActiveItem`	`()`	Matches active item to current UI state.
`onExtensionLoaded`	`()`	Hook - initializes top bar entries and requests game state.
`onGameStateUpdate`	`(state)`	Hook - updates top bar when game state changes.
`onAnyMissionChanged`	`(state, mission)`	Hook - refreshes top bar on mission changes.
`onUiChangedState`	`(state)`	Hook - responds to UI state changes.
`onUIStateTriggered`	`(state, opened, stack)`	Hook - responds to UI state triggers.

State (`M.state`)

Field	Type	Description
`visible`	`bool`	Whether the bar is shown.
`visibleItems`	`string[]`	IDs of currently visible entries.
`activeItem`	`string`	ID of the currently active entry.
`currentUIState`	`string`	Current UI angular state.

Data Fields

Field	Description
`M.dependencies`	`{'ui_topBar_config'}` - top bar configuration module.

Internals

Visibility Filtering

updateVisibleItems() filters entries by:

Blacklisted states - item.blackListStates vs currentUIState
Hidden callback - item.isHidden() returns true
In-game only - item.onlyIngame vs getMissionFilename()

Entries are sorted by order and their IDs emitted via ui_topBar_visibleItemsChanged.

Active Item Matching

updateActiveItem() matches currentUIState against:

Entry's targetState (exact match)
Entry's substates (prefix match)

Game State

getGameState() returns flags: isInGame, isCareerActive, isGarageActive, isMissionActive, isScenarioActive, isScenarioUnrestricted.

How It Works

On load, the extension sets manual unload mode.
Entries come from ui_topBar_config.TopBarEntries.
When the UI requests data, requestData merges entries + game state + bar state.
selectItem finds the entry, sets it active, and calls its targetState change or action().
Keyboard/gamepad navigation uses selectPreviousItem / selectNextItem.

Lua Examples

-- Select the bigmap entry
extensions.ui_topBar.selectItem("bigmap")

-- Hide the top bar
extensions.ui_topBar.hide()

-- Add a custom entry
extensions.ui_topBar.addEntry("myMod", {
  id = "myMod", label = "My Mod", icon = "star",
  targetState = "menu.mymod", order = 50
})

Hooks Triggered

Hook	When
`ui_topBar_show` / `ui_topBar_hide`	Bar shown/hidden
`ui_topBar_activeItemChanged`	Active item changes
`ui_topBar_visibleItemsChanged`	Visible items recalculated
`ui_topBar_entryAdded/Removed/Changed`	Entry mutations
`ui_topBar_entriesChanged`	Bulk entry update
`ui_topBar_dataRequested`	Full data requested
`ui_topBar_gameStateChanged`	Game state sent

Additional Exports

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

M.addEntry
M.getEntries
M.getEntry
M.hide
M.onAnyMissionChanged
M.onExtensionLoaded
M.onGameStateUpdate
M.onUIStateTriggered
M.onUiChangedState
M.removeEntry
M.requestData
M.requestEntries
M.requestGameState
M.selectItem
M.selectNextItem
M.selectPreviousItem
M.setActiveItem
M.show
M.updateActiveItem
M.updateEntries
M.updateEntry
M.updateVisibleItems

Manages the top navigation bar entries, visibility, and active item state.

Overview

Extension path: lua/ge/extensions/ui/topBar.lua Dependencies: ui_topBar_config

Exports (M)

Function	Signature	Description
`show`	`()`	Shows the top bar.
`hide`	`()`	Hides the top bar.
`selectItem`	`(item)`	Selects an entry by id or table, triggers its action.
`selectPreviousItem`	`(loop)`	Navigates to the previous visible item.
`selectNextItem`	`(loop)`	Navigates to the next visible item.
`setActiveItem`	`(item)`	Sets the active item without triggering action.
`addEntry`	`(key, entry)`	Adds a new top bar entry.
`removeEntry`	`(key)`	Removes an entry by key.
`updateEntry`	`(key, entry)`	Updates an existing entry or adds it.
`updateEntries`	`(entries)`	Replaces all entries.
`getEntry`	`(key) → entry`	Returns a single entry.
`getEntries`	`() → table`	Returns all entries.
`requestData`	`()`	Sends all bar state + game state to UI.
`requestEntries`	`()`	Sends entries to UI.
`requestGameState`	`()`	Sends game state flags to UI.
`updateVisibleItems`	`()`	Recalculates which items are visible.
`updateActiveItem`	`()`	Matches active item to current UI state.
`onExtensionLoaded`	`()`	Hook - initializes top bar entries and requests game state.
`onGameStateUpdate`	`(state)`	Hook - updates top bar when game state changes.
`onAnyMissionChanged`	`(state, mission)`	Hook - refreshes top bar on mission changes.
`onUiChangedState`	`(state)`	Hook - responds to UI state changes.
`onUIStateTriggered`	`(state, opened, stack)`	Hook - responds to UI state triggers.

State (`M.state`)

Field	Type	Description
`visible`	`bool`	Whether the bar is shown.
`visibleItems`	`string[]`	IDs of currently visible entries.
`activeItem`	`string`	ID of the currently active entry.
`currentUIState`	`string`	Current UI angular state.

Data Fields

Field	Description
`M.dependencies`	`{'ui_topBar_config'}` - top bar configuration module.

Internals

Visibility Filtering

updateVisibleItems() filters entries by:

Blacklisted states - item.blackListStates vs currentUIState
Hidden callback - item.isHidden() returns true
In-game only - item.onlyIngame vs getMissionFilename()

Entries are sorted by order and their IDs emitted via ui_topBar_visibleItemsChanged.

Active Item Matching

updateActiveItem() matches currentUIState against:

Entry's targetState (exact match)
Entry's substates (prefix match)

Game State

getGameState() returns flags: isInGame, isCareerActive, isGarageActive, isMissionActive, isScenarioActive, isScenarioUnrestricted.

How It Works

On load, the extension sets manual unload mode.
Entries come from ui_topBar_config.TopBarEntries.
When the UI requests data, requestData merges entries + game state + bar state.
selectItem finds the entry, sets it active, and calls its targetState change or action().
Keyboard/gamepad navigation uses selectPreviousItem / selectNextItem.

Lua Examples

-- Select the bigmap entry
extensions.ui_topBar.selectItem("bigmap")

-- Hide the top bar
extensions.ui_topBar.hide()

-- Add a custom entry
extensions.ui_topBar.addEntry("myMod", {
  id = "myMod", label = "My Mod", icon = "star",
  targetState = "menu.mymod", order = 50
})

Hooks Triggered

Hook	When
`ui_topBar_show` / `ui_topBar_hide`	Bar shown/hidden
`ui_topBar_activeItemChanged`	Active item changes
`ui_topBar_visibleItemsChanged`	Visible items recalculated
`ui_topBar_entryAdded/Removed/Changed`	Entry mutations
`ui_topBar_entriesChanged`	Bulk entry update
`ui_topBar_dataRequested`	Full data requested
`ui_topBar_gameStateChanged`	Game state sent

Additional Exports

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

M.addEntry
M.getEntries
M.getEntry
M.hide
M.onAnyMissionChanged
M.onExtensionLoaded
M.onGameStateUpdate
M.onUIStateTriggered
M.onUiChangedState
M.removeEntry
M.requestData
M.requestEntries
M.requestGameState
M.selectItem
M.selectNextItem
M.selectPreviousItem
M.setActiveItem
M.show
M.updateActiveItem
M.updateEntries
M.updateEntry
M.updateVisibleItems

Top Bar

Overview

Exports (M)

State (`M.state`)

Data Fields

Internals

Visibility Filtering

Active Item Matching

Game State

How It Works

Lua Examples

Hooks Triggered

Additional Exports

On this page

Top Bar

Overview

Exports (M)

State (`M.state`)

Data Fields

Internals

Visibility Filtering

Active Item Matching

Game State

How It Works

Lua Examples

Hooks Triggered

Additional Exports

On this page