Freeroam Selector (General)

Grid selector backend for browsing and launching freeroam levels/spawnpoints.

Overview

ui_freeroamSelector_general implements the grid selector API for the freeroam level picker. It provides tile generation, filtering, display settings, favourites, recent selections, and detail views with configurable action buttons.

Extension path: lua/ge/extensions/ui/freeroamSelector/general.lua
Dependencies: ui_gameplaySelector_tiles
Settings path: /settings/freeroamSelectorData.json

Exports (M)

Tile & Data

Function	Signature	Description
`getTiles`	`(path) → groups[]`	Returns grouped tiles for the grid selector.
`getGameplayData`	`() → table`	Returns cached freeroam data (items, filters, display settings).
`getUiData`	`() → table`	Returns UI-ready data package.
`getDetails`	`(item) → table`	Returns detail view via `onGameplaySelectorGetDetails` hook.
`executeButton`	`(buttonId, data)`	Executes a detail panel button callback.
`executeDoubleClick`	`(item)`	Runs the primary/double-click button action.

Filters

Function	Signature	Description
`getFilters`	`() → filterData`	Returns current filter state.
`toggleFilter`	`(key, value)`	Toggles a filter option.
`resetSetFilter`	`(key)`	Resets a set filter.
`getSearchText` / `setSearchText`	`(text?)`	Get/set search query.

Display & Preferences

Function	Signature	Description
`getDisplayDataOptions`	`() → options[]`	Returns all display option definitions.
`setDisplayDataOption`	`(key, value)`	Sets a display option (tile size, recent mode, etc.).
`toggleFavourite`	`(itemDetails) → bool`	Toggles favourite status for an item.

Function	Signature	Description
`getScreenHeaderTitleAndPath`	`(path) → table`	Returns breadcrumb title and path segments.
`openFreeroamSelector`	`()`	Opens the selector with freeroam filter pre-set.
`openFreeroamSelectorForFreeroamConfigurator`	`(callback)`	Opens in spawnpoint-selection mode with custom "Select Spawnpoint" button.
`closedFromUI`	`()`	Cleanup hook when the selector is closed.
`onModManagerStateChanged`	`()`	Hook - marks gameplay data as changed.
`onSettingsChanged`	`()`	Hook - marks gameplay data as changed.
`updateFilterData`	`(...)`	Updates filter data for the freeroam 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.
`getManagementDetails`	`(...)`	Returns management detail data for an item.
`exitCallback`	`(...)`	Callback invoked on exit.
`exploreFolder`	`(...)`	Opens the file explorer for an item's folder.
`goToMod`	`(...)`	Navigates to the mod page for an item.
`clearAllFilters`	`()`	Clears all active filters.
`passesFilters`	`(item) → bool`	Checks if an item passes current filter criteria.
`updateDisplayData`	`(key, value)`	Updates a display data value.
`setCustomDetailsButtons`	`(buttons)`	Sets custom buttons for the detail panel.
`getCustomDetailsButtons`	`() → table`	Returns the current custom detail buttons.
`onModDeactivated`	`()`	Hook - marks gameplay data as changed.
`onModActivated`	`()`	Hook - marks gameplay data as changed.
`onModManagerReady`	`()`	Hook - marks gameplay data as changed when mod manager is ready.
`getDisplayData`	`() → table`	Returns display data settings.

Data Fields

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

Internals

Display Data Options

Key configurable options persisted to JSON:

Key	Default	Description
`displaySize`	`"medium"`	Tile size (list/tiny/small/medium/large/huge)
`showAuxContent`	`true`	Show auxiliary debug content
`showRecentMode`	`"unclustered"`	Recent items display mode
`showFavouritesMode`	`"reducedClusters"`	Favourites display mode
`defaultFreeroamAction`	`"configureFreeroam"`	Primary button action

Tile Source

Items come from the onGameplaySelectorGetTiles extension hook, filtered to items with validBackends.freeroamSelector == true.

Filter Logic

Search matches against item name, level name, and custom filterHook extensions. Auxiliary content is hidden when showAuxContent is disabled.

Freeroam Configurator Mode

M.openFreeroamSelectorForFreeroamConfigurator(function(levelName, spawnPointName)
  -- callback receives selected level and spawnpoint
end)

This sets up custom "Select Spawnpoint" buttons and a custom breadcrumb path pointing back to the freeroam configurator.

Data Invalidation

Data reloads on onModActivated, onModDeactivated, and onModManagerReady.

How It Works

UI opens the freeroam selector → getTiles() populates the grid from extension hooks
User browses/searches/filters levels and spawnpoints
Clicking a tile → getDetails() fetches detail view via onGameplaySelectorGetDetails hook
Primary button starts freeroam or opens configurator (based on defaultFreeroamAction setting)
Favourites and recent selections are persisted for quick re-access

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.getCustomDetailsButtons
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.openFreeroamSelector
M.passesFilters
M.profilerFinish
M.resetDisplayDataToDefaults
M.resetRangeFilter
M.resetSetFilter
M.setCustomDetailsButtons
M.setDisplayDataOption
M.setSearchText
M.toggleFavourite
M.toggleFilter
M.trackRecent
M.updateDisplayData
M.updateFilterData
M.updateRangeFilter

Grid selector backend for browsing and launching freeroam levels/spawnpoints.

Overview

Extension path: lua/ge/extensions/ui/freeroamSelector/general.lua
Dependencies: ui_gameplaySelector_tiles
Settings path: /settings/freeroamSelectorData.json

Exports (M)

Tile & Data

Function	Signature	Description
`getTiles`	`(path) → groups[]`	Returns grouped tiles for the grid selector.
`getGameplayData`	`() → table`	Returns cached freeroam data (items, filters, display settings).
`getUiData`	`() → table`	Returns UI-ready data package.
`getDetails`	`(item) → table`	Returns detail view via `onGameplaySelectorGetDetails` hook.
`executeButton`	`(buttonId, data)`	Executes a detail panel button callback.
`executeDoubleClick`	`(item)`	Runs the primary/double-click button action.

Filters

Function	Signature	Description
`getFilters`	`() → filterData`	Returns current filter state.
`toggleFilter`	`(key, value)`	Toggles a filter option.
`resetSetFilter`	`(key)`	Resets a set filter.
`getSearchText` / `setSearchText`	`(text?)`	Get/set search query.

Display & Preferences

Function	Signature	Description
`getDisplayDataOptions`	`() → options[]`	Returns all display option definitions.
`setDisplayDataOption`	`(key, value)`	Sets a display option (tile size, recent mode, etc.).
`toggleFavourite`	`(itemDetails) → bool`	Toggles favourite status for an item.

Function	Signature	Description
`getScreenHeaderTitleAndPath`	`(path) → table`	Returns breadcrumb title and path segments.
`openFreeroamSelector`	`()`	Opens the selector with freeroam filter pre-set.
`openFreeroamSelectorForFreeroamConfigurator`	`(callback)`	Opens in spawnpoint-selection mode with custom "Select Spawnpoint" button.
`closedFromUI`	`()`	Cleanup hook when the selector is closed.
`onModManagerStateChanged`	`()`	Hook - marks gameplay data as changed.
`onSettingsChanged`	`()`	Hook - marks gameplay data as changed.
`updateFilterData`	`(...)`	Updates filter data for the freeroam 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.
`getManagementDetails`	`(...)`	Returns management detail data for an item.
`exitCallback`	`(...)`	Callback invoked on exit.
`exploreFolder`	`(...)`	Opens the file explorer for an item's folder.
`goToMod`	`(...)`	Navigates to the mod page for an item.
`clearAllFilters`	`()`	Clears all active filters.
`passesFilters`	`(item) → bool`	Checks if an item passes current filter criteria.
`updateDisplayData`	`(key, value)`	Updates a display data value.
`setCustomDetailsButtons`	`(buttons)`	Sets custom buttons for the detail panel.
`getCustomDetailsButtons`	`() → table`	Returns the current custom detail buttons.
`onModDeactivated`	`()`	Hook - marks gameplay data as changed.
`onModActivated`	`()`	Hook - marks gameplay data as changed.
`onModManagerReady`	`()`	Hook - marks gameplay data as changed when mod manager is ready.
`getDisplayData`	`() → table`	Returns display data settings.

Data Fields

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

Internals

Display Data Options

Key configurable options persisted to JSON:

Key	Default	Description
`displaySize`	`"medium"`	Tile size (list/tiny/small/medium/large/huge)
`showAuxContent`	`true`	Show auxiliary debug content
`showRecentMode`	`"unclustered"`	Recent items display mode
`showFavouritesMode`	`"reducedClusters"`	Favourites display mode
`defaultFreeroamAction`	`"configureFreeroam"`	Primary button action

M.openFreeroamSelectorForFreeroamConfigurator(function(levelName, spawnPointName)
  -- callback receives selected level and spawnpoint
end)

This sets up custom "Select Spawnpoint" buttons and a custom breadcrumb path pointing back to the freeroam configurator.

Data Invalidation

Data reloads on onModActivated, onModDeactivated, and onModManagerReady.

How It Works

UI opens the freeroam selector → getTiles() populates the grid from extension hooks
User browses/searches/filters levels and spawnpoints
Clicking a tile → getDetails() fetches detail view via onGameplaySelectorGetDetails hook
Primary button starts freeroam or opens configurator (based on defaultFreeroamAction setting)
Favourites and recent selections are persisted for quick re-access

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.getCustomDetailsButtons
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.openFreeroamSelector
M.passesFilters
M.profilerFinish
M.resetDisplayDataToDefaults
M.resetRangeFilter
M.resetSetFilter
M.setCustomDetailsButtons
M.setDisplayDataOption
M.setSearchText
M.toggleFavourite
M.toggleFilter
M.trackRecent
M.updateDisplayData
M.updateFilterData
M.updateRangeFilter

Freeroam Selector (General)

Overview

Exports (M)

Tile & Data

Filters

Display & Preferences

Navigation

Data Fields

Internals

Display Data Options

Tile Source

Filter Logic

Freeroam Configurator Mode

Data Invalidation

How It Works

Additional Exports

On this page

Freeroam Selector (General)

Overview

Exports (M)

Tile & Data

Filters

Display & Preferences

Navigation

Data Fields

Internals

Display Data Options

Tile Source

Filter Logic

Freeroam Configurator Mode

Data Invalidation

How It Works

Additional Exports

On this page