App Selector (General)

Grid selector backend for browsing and adding UI apps to layouts.

Overview

ui_appSelector_general implements the grid selector API for the UI Apps panel. It provides tile generation, filtering by app type, search, display settings, and detail views with an "Add to Layout" button.

Extension path: lua/ge/extensions/ui/appSelector/general.lua
Dependencies: ui_apps

Exports (M)

Function	Signature	Description
`getAppData`	`() → table`	Returns cached app data (apps, filters, display settings). Reinitializes on mod changes.
`getTiles`	`(path) → groups[]`	Returns sorted/grouped tile arrays for the grid selector.
`getFilters`	`() → filterData`	Returns current filter state (type-based set filters).
`toggleFilter`	`(filterKey, value)`	Toggles a filter option on/off.
`updateRangeFilter`	`(filterKey, min, max)`	Updates a range filter (unused currently).
`resetRangeFilter`	`(filterKey)`	Resets a range filter.
`resetSetFilter`	`(filterKey)`	Resets a set filter to default.
`getDisplayDataOptions`	`() → options[]`	Returns display size dropdown options.
`setDisplayDataOption`	`(key, value)`	Persists a display option (e.g., tile size).
`resetDisplayDataToDefaults`	`()`	Resets display options to defaults.
`getSearchText`	`() → string`	Returns current search query.
`setSearchText`	`(val)`	Sets the search query text.
`getScreenHeaderTitleAndPath`	`(path) → table`	Returns breadcrumb path segments and title for the header.
`getDetails`	`(details) → table`	Returns detail view data for a selected app (preview, specs, buttons).
`executeButton`	`(buttonId, data)`	Executes a detail panel button callback by ID.
`executeDoubleClick`	`(details)`	Double-click spawns the app into the current layout.
`getManagementDetails`	`()`	Returns management details (empty buttons for apps).
`toggleFavourite`	`(itemDetails)`	No-op - apps don't support favourites yet.
`exploreFolder`	`(path)`	No-op - apps don't support folder exploration.
`goToMod`	`(modId)`	No-op - apps don't support mod navigation.
`profilerFinish`	`()`	No-op profiler finish hook.
`closedFromUI`	`()`	No-op callback for when selector closes.
`onModDeactivated`	`()`	Hook - marks app data as changed on mod deactivation.
`onModActivated`	`()`	Hook - marks app data as changed on mod activation.
`onModManagerReady`	`()`	Hook - marks app data as changed when mod manager is ready.
`onModManagerStateChanged`	`()`	Hook - marks app data as changed when mod manager state changes.
`onSettingsChanged`	`()`	Hook - marks app data as changed when settings change.

Data Fields

Field	Description
`M.dependencies`	`{"ui_apps"}` - app management system.

Internals

Grid Selector Integration

This module implements the full GridSelector API contract used by the Angular UI. Key modules are loaded via require:

displayDataModule - Persists tile size to /settings/appSelectorData.json
filterModule - Manages type-based set filters with search
buttonModule - Handles detail panel button callbacks
translateHelper - Wraps translateLanguage() for i18n

Tile Generation

Apps are fetched from ui_apps.getUIAppsData().availableApps, filtered, sorted (non-auxiliary first, then alphabetical), and grouped by category:

-- Category sort order (hardcoded)
local categoryOrder = { "Dashboard", "Telemetry", "General", "Gameplay", "Debug" }

Each tile includes: key, name, preview, sourceIcons (BeamNG official badge, mouse-required icon), and isAuxiliary.

Detail View

The detail panel shows app name, preview image, description, and specs (interactivity, version, types). The primary button triggers:

guihooks.trigger('appContainer:spawn', { appName = app.appName })
guihooks.trigger('ChangeState', {state = 'menu.appedit', params = {mode = 'edit'}})

Data Invalidation

App data is reloaded when mods activate/deactivate:

M.onModDeactivated = function() appDataChanged = true end
M.onModActivated = function() appDataChanged = true end
M.onModManagerReady = function() appDataChanged = true end

How It Works

UI opens the app selector → calls getTiles() to populate the grid
User types in search → setSearchText() filters by localized name/description
User clicks a tile → getDetails() returns preview, specs, and "Add to Layout" button
User clicks "Add to Layout" or double-clicks → spawns the app into the current layout via appContainer:spawn
Display size persisted to JSON so it survives sessions

Additional Exports

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

M.getAppData
M.closedFromUI
M.executeButton
M.executeDoubleClick
M.exploreFolder
M.getDetails
M.getDisplayDataOptions
M.getFilters
M.getManagementDetails
M.getScreenHeaderTitleAndPath
M.getSearchText
M.getTiles
M.goToMod
M.profilerFinish
M.resetDisplayDataToDefaults
M.resetRangeFilter
M.resetSetFilter
M.setDisplayDataOption
M.setSearchText
M.toggleFavourite
M.toggleFilter
M.updateRangeFilter

Grid selector backend for browsing and adding UI apps to layouts.

Overview

Extension path: lua/ge/extensions/ui/appSelector/general.lua
Dependencies: ui_apps

Exports (M)

Function	Signature	Description
`getAppData`	`() → table`	Returns cached app data (apps, filters, display settings). Reinitializes on mod changes.
`getTiles`	`(path) → groups[]`	Returns sorted/grouped tile arrays for the grid selector.
`getFilters`	`() → filterData`	Returns current filter state (type-based set filters).
`toggleFilter`	`(filterKey, value)`	Toggles a filter option on/off.
`updateRangeFilter`	`(filterKey, min, max)`	Updates a range filter (unused currently).
`resetRangeFilter`	`(filterKey)`	Resets a range filter.
`resetSetFilter`	`(filterKey)`	Resets a set filter to default.
`getDisplayDataOptions`	`() → options[]`	Returns display size dropdown options.
`setDisplayDataOption`	`(key, value)`	Persists a display option (e.g., tile size).
`resetDisplayDataToDefaults`	`()`	Resets display options to defaults.
`getSearchText`	`() → string`	Returns current search query.
`setSearchText`	`(val)`	Sets the search query text.
`getScreenHeaderTitleAndPath`	`(path) → table`	Returns breadcrumb path segments and title for the header.
`getDetails`	`(details) → table`	Returns detail view data for a selected app (preview, specs, buttons).
`executeButton`	`(buttonId, data)`	Executes a detail panel button callback by ID.
`executeDoubleClick`	`(details)`	Double-click spawns the app into the current layout.
`getManagementDetails`	`()`	Returns management details (empty buttons for apps).
`toggleFavourite`	`(itemDetails)`	No-op - apps don't support favourites yet.
`exploreFolder`	`(path)`	No-op - apps don't support folder exploration.
`goToMod`	`(modId)`	No-op - apps don't support mod navigation.
`profilerFinish`	`()`	No-op profiler finish hook.
`closedFromUI`	`()`	No-op callback for when selector closes.
`onModDeactivated`	`()`	Hook - marks app data as changed on mod deactivation.
`onModActivated`	`()`	Hook - marks app data as changed on mod activation.
`onModManagerReady`	`()`	Hook - marks app data as changed when mod manager is ready.
`onModManagerStateChanged`	`()`	Hook - marks app data as changed when mod manager state changes.
`onSettingsChanged`	`()`	Hook - marks app data as changed when settings change.

Data Fields

Field	Description
`M.dependencies`	`{"ui_apps"}` - app management system.

Internals

Grid Selector Integration

This module implements the full GridSelector API contract used by the Angular UI. Key modules are loaded via require:

displayDataModule - Persists tile size to /settings/appSelectorData.json
filterModule - Manages type-based set filters with search
buttonModule - Handles detail panel button callbacks
translateHelper - Wraps translateLanguage() for i18n

Tile Generation

Apps are fetched from ui_apps.getUIAppsData().availableApps, filtered, sorted (non-auxiliary first, then alphabetical), and grouped by category:

-- Category sort order (hardcoded)
local categoryOrder = { "Dashboard", "Telemetry", "General", "Gameplay", "Debug" }

Each tile includes: key, name, preview, sourceIcons (BeamNG official badge, mouse-required icon), and isAuxiliary.

Detail View

The detail panel shows app name, preview image, description, and specs (interactivity, version, types). The primary button triggers:

guihooks.trigger('appContainer:spawn', { appName = app.appName })
guihooks.trigger('ChangeState', {state = 'menu.appedit', params = {mode = 'edit'}})

Data Invalidation

App data is reloaded when mods activate/deactivate:

M.onModDeactivated = function() appDataChanged = true end
M.onModActivated = function() appDataChanged = true end
M.onModManagerReady = function() appDataChanged = true end

How It Works

UI opens the app selector → calls getTiles() to populate the grid
User types in search → setSearchText() filters by localized name/description
User clicks a tile → getDetails() returns preview, specs, and "Add to Layout" button
User clicks "Add to Layout" or double-clicks → spawns the app into the current layout via appContainer:spawn
Display size persisted to JSON so it survives sessions

Additional Exports

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

M.getAppData
M.closedFromUI
M.executeButton
M.executeDoubleClick
M.exploreFolder
M.getDetails
M.getDisplayDataOptions
M.getFilters
M.getManagementDetails
M.getScreenHeaderTitleAndPath
M.getSearchText
M.getTiles
M.goToMod
M.profilerFinish
M.resetDisplayDataToDefaults
M.resetRangeFilter
M.resetSetFilter
M.setDisplayDataOption
M.setSearchText
M.toggleFavourite
M.toggleFilter
M.updateRangeFilter

App Selector (General)

Overview

Exports (M)

Data Fields

Internals

Grid Selector Integration

Tile Generation

Detail View

Data Invalidation

How It Works

Additional Exports

On this page

App Selector (General)

Overview

Exports (M)

Data Fields

Internals

Grid Selector Integration

Tile Generation

Detail View

Data Invalidation

How It Works

Additional Exports

On this page