Gameplay Playmode Markers

Clusters POI data into playmode marker groups (missions, parking, zones, walking, gas stations, drift lines, etc.) and provides spatial queries via a KD-tree for efficient visibility lookups.

Public API

| Function | Signature | Returns | Description | |------ | M.dependencies | table | {"gameplay_rawPois"} |----|-----------|---------|-------------| | M.getPlaymodeClusters | () | table | Returns all playmode clusters for the current level, building them lazily | | M.getPlaymodeClustersAsQuadtree | () | kdtree | Returns a 2D KD-tree of clusters for spatial queries | | M.getMarkerForCluster | (cluster) | marker | Gets or creates the visual marker object for a cluster | | M.isStateWithPlaymodeMarkers | () | bool | Returns true if the current game state shows playmode markers | | M.clear | () | nil | Clears all cached clusters and markers |

Hooks

Dependencies

• gameplay_rawPois

Internals

How It Works

1. getPlaymodeClusters() checks the current POI generation from gameplay_rawPois
2. If stale, clears existing clusters/markers and re-fetches raw POIs for the current level
3. POIs are grouped by marker type (mission, parking, zone, etc.)
4. Each marker type's factory module (gameplay/markers/<type>) clusters its own POIs
5. All clusters are sorted by ID and validated for required fields (id, visibilityPos, visibilityRadius)
6. getPlaymodeClustersAsQuadtree() builds a 2D KD-tree using cluster visibility bounds for fast spatial lookup
7. getMarkerForCluster() lazily creates, sets up, and caches marker objects per cluster

Usage Examples

-- Get all clusters for the level
local clusters = gameplay_playmodeMarkers.getPlaymodeClusters()

-- Spatial query: find clusters near a position
local kd = gameplay_playmodeMarkers.getPlaymodeClustersAsQuadtree()
local nearby = kd:queryBox(x - r, y - r, x + r, y + r)

-- Get the visual marker for a specific cluster
local marker = gameplay_playmodeMarkers.getMarkerForCluster(clusters[1])

-- Check if we should display markers in the current state
if gameplay_playmodeMarkers.isStateWithPlaymodeMarkers() then
  -- show markers
end

Notes

• Valid states for markers: freeroam and career (configurable via M.validPlaymodeMarkersStates)
• Generation tracking auto-invalidates caches when raw POIs change
• Each marker type factory must implement a cluster(pois, allClusters) function

Module Variables

See Also

• Gameplay Achievement - Related reference
• Gameplay City - Related reference
• discover - Discover / Experience System - Related reference
• Gameplay Systems Guide - Guide