Tile Clustering
Groups gameplay items into clusters by level, type, or automatic system-based rules, and creates summary tiles for the grid UI.
Groups gameplay items into clusters by level, type, or automatic system-based rules, and creates summary tiles for the grid UI.
Overview
tileClustering provides clustering logic for the gameplay selector. Items are grouped into clusters (by level, type, or automatic rules), and each cluster produces a summary tile showing preview, favourite status, and sub-element count.
Module path: lua/ge/extensions/ui/gameplaySelector/tileClustering.lua (loaded via require)
Exports (M)
| Function | Signature | Description |
|---|---|---|
setBackend | (backend) | Sets the backend reference for favourite/recent queries. |
clusterItems | (items, clusterMode) | Groups items into clusters by the specified mode. |
createTileFromClusteredItems | (clusteredItems, group, clusterMode) | Creates a summary tile for a cluster. |
getClusterModeFunction | (clusterMode) | Returns the clustering key function. |
getClusteredItemsFavouriteIconPercent | (clusteredItems) | Returns favourite/recent stats for a cluster. |
getClusteredItemsStats | (clusteredItems, sortMode) | Returns preview image and representative item. |
getSourceIcons | (clusteredItems) | Collects and sorts source icons from all items. |
Internals
Cluster Modes
| Mode | Behavior |
|---|---|
level | Groups by item.level |
type | Groups by item.type |
automatic | System-aware: Freeroam/Scenarios→level, Challenges→type, Campaigns→no clustering |
none | All items in one "None" cluster |
Automatic Mode Logic
['automatic'] = function(item)
local system = item.system or "Other..."
if system == "Campaigns (deprecated)" then return "None"
elseif system == "Freeroam" then return item.level or "Other..."
elseif system == "Scenarios (deprecated)" then return item.level or "Other..."
elseif system == "Challenges" then return item.type or "Other..."
elseif item.level then return item.level
else return "Other..." end
endCluster Tile Creation
Each cluster tile includes:
- key - unique identifier combining group and cluster key
- name - cluster label (level name, type name, etc.)
- preview - best preview image from contained items
- subElementCount - number of items in the cluster
- favouriteIdx / recentIdx - highest favourite / lowest recent across items
- gotoPath - navigation path for drilling into the cluster
- sourceIcons - merged and sorted icons from all items
Source Icon Ordering
Icons are sorted by a predefined priority: beamNG > camshaft > puzzleModule > cup > bug, then alphabetically for unknown icons.
How It Works
clusterItems(items, "automatic")groups items by the automatic key function- Each cluster is a table with
itemsByKey,count, andlist createTileFromClusteredItemspicks the right tile creator for the cluster mode- The tile creator computes preview, stats, and navigation path
- Grid UI renders cluster tiles; clicking one navigates to the detail view
Additional Exports
The following exports are available but not yet documented in detail:
M.clusterItemsM.createTileFromClusteredItemsM.getClusterModeFunctionM.getClusteredItemsFavouriteIconPercentM.getClusteredItemsStatsM.getSourceIconsM.setBackend
Gameplay Selector - General
Backend module for the gameplay grid selector - manages display options, filters, tiles, favourites, and navigation for scenarios, campaigns, challenges, and freeroam.
Gameplay Selector Tiles
Main tile processing module - handles path-based navigation, grouping, clustering, filtering, and sorting for the gameplay grid.