Gameplay Selector

Backend module for the gameplay grid selector - manages display options, filters, tiles, favourites, and navigation for scenarios, campaigns, challenges, and freeroam.

Overview

ui_gameplaySelector_general is the backend that powers the gameplay selector grid UI. It aggregates tiles from tile generators (campaigns, levels, missions, scenarios), applies filtering and display preferences, and provides details/actions for selected items.

Extension path: lua/ge/extensions/ui/gameplaySelector/general.lua

Dependencies: ui_gameplaySelector_tiles

Exports (M)

Function	Signature	Description
`getUiData`	`()`	Returns items, displayData, filters, and backendName.
`getGameplayData`	`()`	Returns full gameplay data (initializes on first call).
`getTiles`	`(path)`	Returns grouped/clustered tiles for a navigation path.
`passesFilters`	`(item)`	Checks if an item passes active filters.
`getDisplayData`	`()`	Returns current display settings.
`updateDisplayData`	`(key, value)`	Updates a display setting.
`getDetails`	`(item)`	Returns detail panel data for an item.
`executeButton`	`(buttonId, data?)`	Executes a detail panel button action.
`executeDoubleClick`	`(item)`	Executes the double-click action for an item.
`toggleFavourite`	`(itemDetails)`	Toggles favourite status for an item.
`openGameplaySelector`	`()`	Opens the selector with default settings.
`openChallengesSelector`	`()`	Opens filtered to Challenges.
`openScenariosSelector`	`()`	Opens filtered to Scenarios.
`openCampaignsSelector`	`()`	Opens filtered to Campaigns.
`openRallySelector`	`()`	Opens filtered to Rally stages/loops.

Filter API

Function	Signature	Description
`getFilters`	`() → filterData`	Returns filter list and state.
`toggleFilter`	`(key, value)`	Toggles a set filter option.
`setSearchText`	`(text)`	Sets search text.
`clearAllFilters`	`()`	Resets all filters and search.
`onModManagerStateChanged`	`()`	Hook - marks gameplay data as changed.
`onSettingsChanged`	`()`	Hook - marks gameplay data as changed.
`updateFilterData`	`(...)`	Updates filter data for the gameplay selector.
`isFavourite`	`(...)`	Checks if an item is marked as favourite.
`isRecent`	`(...)`	Checks if an item was recently used.
`trackRecent`	`(...)`	Marks an item as recently used.
`getActiveFilters`	`(...)`	Returns currently active filters.
`updateRangeFilter`	`(...)`	Updates a range-type filter value.
`resetRangeFilter`	`(...)`	Resets a range filter to default.
`resetDisplayDataToDefaults`	`(...)`	Resets all display options to defaults.
`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 an item.
`exitCallback`	`(...)`	Callback invoked on exit.
`exploreFolder`	`(path)`	Opens the file explorer for an item's folder.
`goToMod`	`(modId)`	Navigates to the mod page for an item.
`closedFromUI`	`()`	Cleanup hook when the selector is closed.
`getDisplayDataOptions`	`() → options[]`	Returns display data configuration options.
`getScreenHeaderTitleAndPath`	`(path) → table`	Returns the header title and breadcrumb path.
`getSearchText`	`() → string`	Returns the current search text.
`onModDeactivated`	`()`	Hook - marks gameplay data as changed on mod deactivation.
`onModActivated`	`()`	Hook - marks gameplay data as changed on mod activation.
`onModManagerReady`	`()`	Hook - marks gameplay data as changed when mod manager is ready.
`resetSetFilter`	`(filterKey)`	Resets a set filter to default.
`setDisplayDataOption`	`(key, value)`	Sets a display data option.
`exploreFolder`	`(...)`	Opens the file explorer for an item's folder.
`goToMod`	`(...)`	Navigates to the mod page for an item.

Data Fields

Field	Description
`M.backendName`	`"gameplaySelector"` - backend identifier.
`M.dependencies`	`{"ui_gameplaySelector_tiles"}` - tile generation system.
`M.displayDataInstance`	Display data module instance for managing view preferences.

Internals

Display Data Options

Persisted to /settings/gameplaySelectorData.json. Key options:

Key	Default	Description
`groupMode`	`"system"`	Groups: System, Type, Level, None
`clusterMode`	`"automatic"`	Clustering: Automatic, Type, Level, None
`displaySize`	`"medium"`	Tile size: List through Huge
`sorting`	`"automatic"`	Sort mode: Automatic, Name, Date
`showAuxContent`	`true`	Show auxiliary/debug content
`showCareerContent`	`false`	Show career-only missions

Filter System

Filters are built from gameplay item properties: system, type, level. Items are checked against both standard filters and career content filtering:

function M.passesFilters(item)
  if not filter.passesFilters(item) then return false end
  if item.isCareerOnly and not displayData.showCareerContent then return false end
  return true
end

Data Initialization

On first access or mod activation, tiles are collected via the hook system:

extensions.hook("onGameplaySelectorGetTiles", items, M)

Tile generators register via this hook to provide their items.

How It Works

UI opens the selector → openGameplaySelector() clears filters and navigates
getUiData() aggregates items from all tile generators via hooks
Items are filtered and grouped based on display settings
getTiles(path) delegates to the tiles module for grouping/clustering
Selecting an item calls getDetails() which hooks into generators for detail panels
Button clicks trigger executeButton() which invokes the registered callback

Additional Exports

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

M.getGameplayData
M.onModActivated
M.onModDeactivated
M.onModManagerReady
M.onModManagerStateChanged
M.onSettingsChanged
M.clearAllFilters
M.closedFromUI
M.executeButton
M.executeDoubleClick
M.exitCallback
M.exploreFolder
M.getActiveFilters
M.getDetails
M.getDisplayData
M.getDisplayDataOptions
M.getFilters
M.getManagementDetails
M.getScreenHeaderTitleAndPath
M.getSearchText
M.getTiles
M.getUiData
M.goToMod
M.isFavourite
M.isRecent
M.openCampaignsSelector
M.openChallengesSelector
M.openGameplaySelector
M.openRallySelector
M.openScenariosSelector
M.profilerFinish
M.resetDisplayDataToDefaults
M.resetRangeFilter
M.resetSetFilter
M.setDisplayDataOption
M.setSearchText
M.toggleFavourite
M.toggleFilter
M.trackRecent
M.updateDisplayData
M.updateFilterData
M.updateRangeFilter

Backend module for the gameplay grid selector - manages display options, filters, tiles, favourites, and navigation for scenarios, campaigns, challenges, and freeroam.

Overview

Extension path: lua/ge/extensions/ui/gameplaySelector/general.lua

Dependencies: ui_gameplaySelector_tiles

Exports (M)

Function	Signature	Description
`getUiData`	`()`	Returns items, displayData, filters, and backendName.
`getGameplayData`	`()`	Returns full gameplay data (initializes on first call).
`getTiles`	`(path)`	Returns grouped/clustered tiles for a navigation path.
`passesFilters`	`(item)`	Checks if an item passes active filters.
`getDisplayData`	`()`	Returns current display settings.
`updateDisplayData`	`(key, value)`	Updates a display setting.
`getDetails`	`(item)`	Returns detail panel data for an item.
`executeButton`	`(buttonId, data?)`	Executes a detail panel button action.
`executeDoubleClick`	`(item)`	Executes the double-click action for an item.
`toggleFavourite`	`(itemDetails)`	Toggles favourite status for an item.
`openGameplaySelector`	`()`	Opens the selector with default settings.
`openChallengesSelector`	`()`	Opens filtered to Challenges.
`openScenariosSelector`	`()`	Opens filtered to Scenarios.
`openCampaignsSelector`	`()`	Opens filtered to Campaigns.
`openRallySelector`	`()`	Opens filtered to Rally stages/loops.

Filter API

Function	Signature	Description
`getFilters`	`() → filterData`	Returns filter list and state.
`toggleFilter`	`(key, value)`	Toggles a set filter option.
`setSearchText`	`(text)`	Sets search text.
`clearAllFilters`	`()`	Resets all filters and search.
`onModManagerStateChanged`	`()`	Hook - marks gameplay data as changed.
`onSettingsChanged`	`()`	Hook - marks gameplay data as changed.
`updateFilterData`	`(...)`	Updates filter data for the gameplay selector.
`isFavourite`	`(...)`	Checks if an item is marked as favourite.
`isRecent`	`(...)`	Checks if an item was recently used.
`trackRecent`	`(...)`	Marks an item as recently used.
`getActiveFilters`	`(...)`	Returns currently active filters.
`updateRangeFilter`	`(...)`	Updates a range-type filter value.
`resetRangeFilter`	`(...)`	Resets a range filter to default.
`resetDisplayDataToDefaults`	`(...)`	Resets all display options to defaults.
`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 an item.
`exitCallback`	`(...)`	Callback invoked on exit.
`exploreFolder`	`(path)`	Opens the file explorer for an item's folder.
`goToMod`	`(modId)`	Navigates to the mod page for an item.
`closedFromUI`	`()`	Cleanup hook when the selector is closed.
`getDisplayDataOptions`	`() → options[]`	Returns display data configuration options.
`getScreenHeaderTitleAndPath`	`(path) → table`	Returns the header title and breadcrumb path.
`getSearchText`	`() → string`	Returns the current search text.
`onModDeactivated`	`()`	Hook - marks gameplay data as changed on mod deactivation.
`onModActivated`	`()`	Hook - marks gameplay data as changed on mod activation.
`onModManagerReady`	`()`	Hook - marks gameplay data as changed when mod manager is ready.
`resetSetFilter`	`(filterKey)`	Resets a set filter to default.
`setDisplayDataOption`	`(key, value)`	Sets a display data option.
`exploreFolder`	`(...)`	Opens the file explorer for an item's folder.
`goToMod`	`(...)`	Navigates to the mod page for an item.

Data Fields

Field	Description
`M.backendName`	`"gameplaySelector"` - backend identifier.
`M.dependencies`	`{"ui_gameplaySelector_tiles"}` - tile generation system.
`M.displayDataInstance`	Display data module instance for managing view preferences.

Internals

Display Data Options

Persisted to /settings/gameplaySelectorData.json. Key options:

Key	Default	Description
`groupMode`	`"system"`	Groups: System, Type, Level, None
`clusterMode`	`"automatic"`	Clustering: Automatic, Type, Level, None
`displaySize`	`"medium"`	Tile size: List through Huge
`sorting`	`"automatic"`	Sort mode: Automatic, Name, Date
`showAuxContent`	`true`	Show auxiliary/debug content
`showCareerContent`	`false`	Show career-only missions

Filter System

Filters are built from gameplay item properties: system, type, level. Items are checked against both standard filters and career content filtering:

function M.passesFilters(item)
  if not filter.passesFilters(item) then return false end
  if item.isCareerOnly and not displayData.showCareerContent then return false end
  return true
end

Data Initialization

On first access or mod activation, tiles are collected via the hook system:

extensions.hook("onGameplaySelectorGetTiles", items, M)

Tile generators register via this hook to provide their items.

How It Works

UI opens the selector → openGameplaySelector() clears filters and navigates
getUiData() aggregates items from all tile generators via hooks
Items are filtered and grouped based on display settings
getTiles(path) delegates to the tiles module for grouping/clustering
Selecting an item calls getDetails() which hooks into generators for detail panels
Button clicks trigger executeButton() which invokes the registered callback

Additional Exports

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

M.getGameplayData
M.onModActivated
M.onModDeactivated
M.onModManagerReady
M.onModManagerStateChanged
M.onSettingsChanged
M.clearAllFilters
M.closedFromUI
M.executeButton
M.executeDoubleClick
M.exitCallback
M.exploreFolder
M.getActiveFilters
M.getDetails
M.getDisplayData
M.getDisplayDataOptions
M.getFilters
M.getManagementDetails
M.getScreenHeaderTitleAndPath
M.getSearchText
M.getTiles
M.getUiData
M.goToMod
M.isFavourite
M.isRecent
M.openCampaignsSelector
M.openChallengesSelector
M.openGameplaySelector
M.openRallySelector
M.openScenariosSelector
M.profilerFinish
M.resetDisplayDataToDefaults
M.resetRangeFilter
M.resetSetFilter
M.setDisplayDataOption
M.setSearchText
M.toggleFavourite
M.toggleFilter
M.trackRecent
M.updateDisplayData
M.updateFilterData
M.updateRangeFilter

Gameplay Selector - General

Overview

Exports (M)

Filter API

Data Fields

Internals

Display Data Options

Filter System

Data Initialization

How It Works

Additional Exports

On this page

Gameplay Selector - General

Overview

Exports (M)

Filter API

Data Fields

Internals

Display Data Options

Filter System

Data Initialization

How It Works

Additional Exports

On this page