Vehicle Selector

Central hub for the vehicle selector: data initialization, filtering, display settings, favourites, and opening modes.

Overview

ui_vehicleSelector_general is the main entry point for the vehicle selector system. It initializes vehicle/config data from core_vehicles, manages display settings (group/sort/cluster mode), handles filtering, tracks favourites and recent selections, and provides multiple "open" APIs for freeroam, challenge, and configurator contexts.

Extension path: lua/ge/extensions/ui/vehicleSelector/general.lua Dependencies: core_vehicles, ui_vehicleSelector_detailsInteraction, ui_vehicleSelector_tiles

Exports (M) - Key Functions

Function	Signature	Description
`getUiData`	`() → table`	Returns (and lazily initializes) all vehicle data, filters, display settings.
`getTiles`	`(...)`	Delegates to `ui_vehicleSelector_tiles.getTiles`.
`getDetails`	`(...)`	Delegates to `detailsInteraction.getDetails`.
`openVehicleSelectorForFreeroam`	`()`	Opens selector in freeroam mode (spawn/replace).
`openVehicleSelectorForFreeroamWithMod`	`(modId)`	Opens filtered to a specific mod.
`openVehicleSelectorForFreeroamConfigurator`	`(callback)`	Opens for vehicle selection with a callback.
`openVehicleSelectorForChallenge`	`(callback)`	Opens for challenge mode (currently WIP/disabled).
`closedFromUI`	`()`	Cleanup when selector is closed by UI.
`clearCache`	`()`	Forces re-initialization of vehicle data.
`getScreenHeaderTitleAndPath`	`(path) → table`	Returns breadcrumb title and path segments for the header.
`onModManagerStateChanged`	`()`	Hook - clears vehicle cache when mod manager state changes.
`updateDisplayData`	`(...)`	Updates vehicle display data.
`updateFilterData`	`(...)`	Updates filter data.
`isRecent`	`(model, config)`	Checks if a vehicle was recently used (alias: `isRecentVehicle`).
`trackRecent`	`(model, config)`	Marks a vehicle as recently used (alias: `trackRecentVehicle`).
`getActiveFilters`	`(...)`	Returns currently active filter state.
`profilerFinish`	`(...)`	Finishes a profiler measurement.
`setCustomDetailsButtons`	`(...)`	Sets custom buttons for the detail panel.
`getCustomDetailsButtons`	`()`	Returns the current custom detail buttons.
`getManagementDetails`	`(...)`	Returns management detail data for a vehicle.
`exitCallback`	`(...)`	Callback invoked on exit from the selector.
`exploreFolder`	`(...)`	Opens the file explorer for a vehicle's folder.
`goToMod`	`(...)`	Navigates to the mod page for a vehicle.
`isFilterLocked`	`(...)`	Checks if a specific filter is locked.
`createFilters`	`(...)`	Creates the vehicle filter set.
`onSettingsChanged`	`()`	Hook - marks vehicle data as changed when settings change.
`executeButton`	`(...)`	Executes a management button action.
`executeDoubleClick`	`(...)`	Executes the double-click action for a tile.
`setManagementButtonsEnabled`	`(...)`	Enables/disables management buttons.
`setDetailsButtonForFreeroam`	`(...)`	Sets the details button for freeroam mode.
`openVehicleSelectorForFreeroamModal`	`()`	Opens the vehicle selector in freeroam modal mode.
`emptyProfiler`	`()`	Returns a no-op profiler instance.
`onfilechanged`	`(...)`	Hook - responds to file changes (lowercase variant).

Filter Functions (delegated)

getFilters, toggleFilter, updateFilters, updateRangeFilter, resetRangeFilter, resetSetFilter, clearAllFilters, lockFilter, unlockFilter, lockFilterMode, lockFilterModeExclusive, clearLockedFilters, calculateActiveFilters, setupValidFilters, getValidFilters, passesFilters, getSearchText, setSearchText

Display Functions (delegated)

getDisplayData, getDisplayDataOptions, setDisplayDataOption, resetDisplayDataToDefaults, toggleFavourite, isFavourite, isRecentVehicle, trackRecentVehicle

Data Fields

Field	Description
`M.dependencies`	`{"core_vehicles", "ui_vehicleSelector_detailsInteraction", "ui_vehicleSelector_tiles"}` - vehicle data and sub-modules.
(internal) `displayDataInstance`	Local display data module instance for managing view preferences (not exported on M).

Internals

Data Initialization

initializeVehicleData() builds:

models / configs - flat lists from core_vehicles
filterList / filterByProp - from filterModule
displayData - persisted settings from /settings/vehicleSelectorData.json

Display Data Options

Configurable options include: Group by (Type/Brand/Country/etc.), Sort by (Name/Value/Weight/etc.), Cluster by, Expand configs, Display size, Filter Reset on Spawn, Recent/Favourites display mode, and developer toggles.

Default Vehicle

getDefaultVehicleInfo() reads settings/default.pc for legacy default vehicle support. getDefaultVehicleTile() converts it into a tile for the grid.

Cache Invalidation

onModActivated, onModDeactivated, onModManagerReady all set vehicleDataChanged = true, forcing re-initialization on next getUiData() call.

How It Works

UI navigates to vehicle selector → one of the openVehicleSelectorFor* functions is called.
This initializes data via getUiData(), configures buttons/filters, and triggers ChangeState.
The UI calls getTiles(path) to get grouped/clustered/sorted vehicle tiles.
On tile selection, getDetails returns specs and action buttons.
On close, closedFromUI resets filters and callbacks.

Lua Examples

-- Open the vehicle selector
extensions.ui_vehicleSelector_general.openVehicleSelectorForFreeroam()

-- Check if a vehicle is favourited
local fav = extensions.ui_vehicleSelector_general.isFavourite("pickup", "base")

-- Track a recently used vehicle
extensions.ui_vehicleSelector_general.trackRecentVehicle("pickup", "base")

-- Force refresh after mod changes
extensions.ui_vehicleSelector_general.clearCache()

Hooks

Hook	When
`onVehicleSelectorOpen` (ext)	Selector opened
`onVehicleSelectorClosed` (ext)	Selector closed
`gridSelectorRefreshAll` (guihook)	Data refresh requested
`ChangeState` (guihook)	UI navigation triggered

Additional Exports

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

M.calculateActiveFilters
M.clearAllFilters
M.clearCache
M.clearLockedFilters
M.closedFromUI
M.createFilters
M.emptyProfiler
M.executeButton
M.executeDoubleClick
M.getDefaultVehicleInfo
M.getDefaultVehicleTile
M.getDetails
M.getDisplayData
M.getDisplayDataOptions
M.getFilters
M.getManagementDetails
M.getScreenHeaderTitleAndPath
M.getSearchText
M.getTiles
M.getUiData
M.getValidFilters
M.goToMod
M.isFavourite
M.isFilterLocked
M.isRecentVehicle
M.lockFilter
M.lockFilterMode
M.lockFilterModeExclusive
M.onModActivated
M.onModDeactivated
M.onModManagerReady
M.onModManagerStateChanged
M.onfilechanged
M.openVehicleSelectorForChallenge
M.openVehicleSelectorForFreeroam
M.openVehicleSelectorForFreeroamConfigurator
M.openVehicleSelectorForFreeroamModal
M.openVehicleSelectorForFreeroamWithMod
M.p
M.passesFilters
M.profilerFinish
M.resetDisplayDataToDefaults
M.resetRangeFilter
M.resetSetFilter
M.setCustomDetailsButtons
M.setDetailsButtonForFreeroam
M.setDisplayDataOption
M.setManagementButtonsEnabled
M.setSearchText
M.setupValidFilters
M.toggleFavourite
M.toggleFilter
M.trackRecentVehicle
M.unlockFilter
M.updateFilters
M.updateRangeFilter

Overview

Extension path: lua/ge/extensions/ui/vehicleSelector/general.lua Dependencies: core_vehicles, ui_vehicleSelector_detailsInteraction, ui_vehicleSelector_tiles

Exports (M) - Key Functions

Function	Signature	Description
`getUiData`	`() → table`	Returns (and lazily initializes) all vehicle data, filters, display settings.
`getTiles`	`(...)`	Delegates to `ui_vehicleSelector_tiles.getTiles`.
`getDetails`	`(...)`	Delegates to `detailsInteraction.getDetails`.
`openVehicleSelectorForFreeroam`	`()`	Opens selector in freeroam mode (spawn/replace).
`openVehicleSelectorForFreeroamWithMod`	`(modId)`	Opens filtered to a specific mod.
`openVehicleSelectorForFreeroamConfigurator`	`(callback)`	Opens for vehicle selection with a callback.
`openVehicleSelectorForChallenge`	`(callback)`	Opens for challenge mode (currently WIP/disabled).
`closedFromUI`	`()`	Cleanup when selector is closed by UI.
`clearCache`	`()`	Forces re-initialization of vehicle data.
`getScreenHeaderTitleAndPath`	`(path) → table`	Returns breadcrumb title and path segments for the header.
`onModManagerStateChanged`	`()`	Hook - clears vehicle cache when mod manager state changes.
`updateDisplayData`	`(...)`	Updates vehicle display data.
`updateFilterData`	`(...)`	Updates filter data.
`isRecent`	`(model, config)`	Checks if a vehicle was recently used (alias: `isRecentVehicle`).
`trackRecent`	`(model, config)`	Marks a vehicle as recently used (alias: `trackRecentVehicle`).
`getActiveFilters`	`(...)`	Returns currently active filter state.
`profilerFinish`	`(...)`	Finishes a profiler measurement.
`setCustomDetailsButtons`	`(...)`	Sets custom buttons for the detail panel.
`getCustomDetailsButtons`	`()`	Returns the current custom detail buttons.
`getManagementDetails`	`(...)`	Returns management detail data for a vehicle.
`exitCallback`	`(...)`	Callback invoked on exit from the selector.
`exploreFolder`	`(...)`	Opens the file explorer for a vehicle's folder.
`goToMod`	`(...)`	Navigates to the mod page for a vehicle.
`isFilterLocked`	`(...)`	Checks if a specific filter is locked.
`createFilters`	`(...)`	Creates the vehicle filter set.
`onSettingsChanged`	`()`	Hook - marks vehicle data as changed when settings change.
`executeButton`	`(...)`	Executes a management button action.
`executeDoubleClick`	`(...)`	Executes the double-click action for a tile.
`setManagementButtonsEnabled`	`(...)`	Enables/disables management buttons.
`setDetailsButtonForFreeroam`	`(...)`	Sets the details button for freeroam mode.
`openVehicleSelectorForFreeroamModal`	`()`	Opens the vehicle selector in freeroam modal mode.
`emptyProfiler`	`()`	Returns a no-op profiler instance.
`onfilechanged`	`(...)`	Hook - responds to file changes (lowercase variant).

Filter Functions (delegated)

Display Functions (delegated)

getDisplayData, getDisplayDataOptions, setDisplayDataOption, resetDisplayDataToDefaults, toggleFavourite, isFavourite, isRecentVehicle, trackRecentVehicle

Data Fields

Field	Description
`M.dependencies`	`{"core_vehicles", "ui_vehicleSelector_detailsInteraction", "ui_vehicleSelector_tiles"}` - vehicle data and sub-modules.
(internal) `displayDataInstance`	Local display data module instance for managing view preferences (not exported on M).

Internals

Data Initialization

initializeVehicleData() builds:

models / configs - flat lists from core_vehicles
filterList / filterByProp - from filterModule
displayData - persisted settings from /settings/vehicleSelectorData.json

UI navigates to vehicle selector → one of the openVehicleSelectorFor* functions is called.
This initializes data via getUiData(), configures buttons/filters, and triggers ChangeState.
The UI calls getTiles(path) to get grouped/clustered/sorted vehicle tiles.
On tile selection, getDetails returns specs and action buttons.
On close, closedFromUI resets filters and callbacks.

Lua Examples

-- Open the vehicle selector
extensions.ui_vehicleSelector_general.openVehicleSelectorForFreeroam()

-- Check if a vehicle is favourited
local fav = extensions.ui_vehicleSelector_general.isFavourite("pickup", "base")

-- Track a recently used vehicle
extensions.ui_vehicleSelector_general.trackRecentVehicle("pickup", "base")

-- Force refresh after mod changes
extensions.ui_vehicleSelector_general.clearCache()

Hooks

Hook	When
`onVehicleSelectorOpen` (ext)	Selector opened
`onVehicleSelectorClosed` (ext)	Selector closed
`gridSelectorRefreshAll` (guihook)	Data refresh requested
`ChangeState` (guihook)	UI navigation triggered

Additional Exports

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

M.calculateActiveFilters
M.clearAllFilters
M.clearCache
M.clearLockedFilters
M.closedFromUI
M.createFilters
M.emptyProfiler
M.executeButton
M.executeDoubleClick
M.getDefaultVehicleInfo
M.getDefaultVehicleTile
M.getDetails
M.getDisplayData
M.getDisplayDataOptions
M.getFilters
M.getManagementDetails
M.getScreenHeaderTitleAndPath
M.getSearchText
M.getTiles
M.getUiData
M.getValidFilters
M.goToMod
M.isFavourite
M.isFilterLocked
M.isRecentVehicle
M.lockFilter
M.lockFilterMode
M.lockFilterModeExclusive
M.onModActivated
M.onModDeactivated
M.onModManagerReady
M.onModManagerStateChanged
M.onfilechanged
M.openVehicleSelectorForChallenge
M.openVehicleSelectorForFreeroam
M.openVehicleSelectorForFreeroamConfigurator
M.openVehicleSelectorForFreeroamModal
M.openVehicleSelectorForFreeroamWithMod
M.p
M.passesFilters
M.profilerFinish
M.resetDisplayDataToDefaults
M.resetRangeFilter
M.resetSetFilter
M.setCustomDetailsButtons
M.setDetailsButtonForFreeroam
M.setDisplayDataOption
M.setManagementButtonsEnabled
M.setSearchText
M.setupValidFilters
M.toggleFavourite
M.toggleFilter
M.trackRecentVehicle
M.unlockFilter
M.updateFilters
M.updateRangeFilter

Vehicle Selector

Overview

Exports (M) - Key Functions

Filter Functions (delegated)

Display Functions (delegated)

Data Fields

Internals

Data Initialization

Display Data Options

Default Vehicle

Cache Invalidation

How It Works

Lua Examples

Hooks

Additional Exports

See Also

On this page

Vehicle Selector

Overview

Exports (M) - Key Functions

Filter Functions (delegated)

Display Functions (delegated)

Data Fields

Internals

Data Initialization

Display Data Options

Default Vehicle

Cache Invalidation

How It Works

Lua Examples

Hooks

Additional Exports

See Also

On this page