Freeroam Big Map Markers

Manages clustering and rendering of POI markers on the big map. Handles quadtree-based spatial clustering, marker lifecycle, mouse hover detection, and visibility filtering.

Internal State

Field	Type	Description
`M.buildPoiList`	varies	Assigned as `buildPoiList`

Public API

Function	Signature	Returns	Description
`M.setupFilter`	`(validIds, radius)`	`nil`	Sets which POI IDs are visible and the cluster merge radius
`M.displayBigMapMarkers`	`(dtReal)`	`nil`	Updates and renders all visible bigmap markers
`M.handleMouse`	`(camMode, uiPopupOpen, mouseMoved, poiIsSelected)`	`string\|nil`	Returns hovered POI ID via ray-sphere intersection
`M.getIdsFromHoveredPoiId`	`(id)`	`table\|nil`	Returns all POI IDs in the cluster containing the given ID
`M.getClusterMarker`	`(cluster)`	`marker`	Gets or creates a bigmap marker for a cluster
`M.getAllClustersBySettings`	`(settingsId)`	`table`	Returns all clusters for a given filter settings ID
`M.hideMarkers`	`()`	`nil`	Hides all current and old markers
`M.clearMarkers`	`()`	`nil`	Destroys all marker objects and clears caches
`M.setNextMarkersFullAlphaInstant`	`()`	`nil`	Forces next marker update to show at full alpha

Internals

Cluster Settings: Each setupFilter() call creates a settings entry keyed by radius#-sortedIds. Only one is "current" at a time
Old Markers: When filter changes, existing markers move to oldMarkersByClusterId for gradual fade-out cleanup
Quadtree Clustering: Uses quadtree module to spatially group POIs within the merge radius
Marker Factory: bigmapMarkerFactory creates individual marker objects and merges clusters

How It Works

setupFilter(validIds, radius) - configures which POIs to show and at what cluster radius
getAllClustersBySettings() - lazily clusters POIs using a quadtree; invalidated when gameplay_rawPois generation changes
displayBigMapMarkers() - iterates all cluster settings, shows/hides markers based on which is active, calls marker:update()
handleMouse() - casts a ray from camera (mouse or controller crosshair) and tests against icon sphere radii

Usage Examples

-- Set visible POIs with a merge radius
freeroam_bigMapMarkers.setupFilter({"mission_001", "garage_west"}, 50)

-- Get clusters for current settings
local clusters = freeroam_bigMapMarkers.getAllClustersBySettings(settingsId)

-- Check what's under the cursor
local hoveredId = freeroam_bigMapMarkers.handleMouse(camMode, false, true, false)

-- Clean up
freeroam_bigMapMarkers.clearMarkers()

Notes

Cluster radius is snapped to multiples of 5 for cache efficiency
Mouse hover uses a sphere radius proportional to camera distance and FOV
Depends on gameplay_rawPois for POI data and bigmapMarker factory for rendering

Internal State

Field	Type	Description
`M.buildPoiList`	varies	Assigned as `buildPoiList`

Public API

Function	Signature	Returns	Description
`M.setupFilter`	`(validIds, radius)`	`nil`	Sets which POI IDs are visible and the cluster merge radius
`M.displayBigMapMarkers`	`(dtReal)`	`nil`	Updates and renders all visible bigmap markers
`M.handleMouse`	`(camMode, uiPopupOpen, mouseMoved, poiIsSelected)`	`string\|nil`	Returns hovered POI ID via ray-sphere intersection
`M.getIdsFromHoveredPoiId`	`(id)`	`table\|nil`	Returns all POI IDs in the cluster containing the given ID
`M.getClusterMarker`	`(cluster)`	`marker`	Gets or creates a bigmap marker for a cluster
`M.getAllClustersBySettings`	`(settingsId)`	`table`	Returns all clusters for a given filter settings ID
`M.hideMarkers`	`()`	`nil`	Hides all current and old markers
`M.clearMarkers`	`()`	`nil`	Destroys all marker objects and clears caches
`M.setNextMarkersFullAlphaInstant`	`()`	`nil`	Forces next marker update to show at full alpha

Internals

Cluster Settings: Each setupFilter() call creates a settings entry keyed by radius#-sortedIds. Only one is "current" at a time
Old Markers: When filter changes, existing markers move to oldMarkersByClusterId for gradual fade-out cleanup
Quadtree Clustering: Uses quadtree module to spatially group POIs within the merge radius
Marker Factory: bigmapMarkerFactory creates individual marker objects and merges clusters

How It Works

setupFilter(validIds, radius) - configures which POIs to show and at what cluster radius
getAllClustersBySettings() - lazily clusters POIs using a quadtree; invalidated when gameplay_rawPois generation changes
displayBigMapMarkers() - iterates all cluster settings, shows/hides markers based on which is active, calls marker:update()
handleMouse() - casts a ray from camera (mouse or controller crosshair) and tests against icon sphere radii

Usage Examples

-- Set visible POIs with a merge radius
freeroam_bigMapMarkers.setupFilter({"mission_001", "garage_west"}, 50)

-- Get clusters for current settings
local clusters = freeroam_bigMapMarkers.getAllClustersBySettings(settingsId)

-- Check what's under the cursor
local hoveredId = freeroam_bigMapMarkers.handleMouse(camMode, false, true, false)

-- Clean up
freeroam_bigMapMarkers.clearMarkers()

Notes

Cluster radius is snapped to multiples of 5 for cache efficiency
Mouse hover uses a sphere radius proportional to camera distance and FOV
Depends on gameplay_rawPois for POI data and bigmapMarker factory for rendering

Freeroam Big Map Markers

Internal State

Public API

Internals

How It Works

Usage Examples

Notes

See Also

On this page

Freeroam Big Map Markers

Internal State

Public API

Internals

How It Works

Usage Examples

Notes

See Also

On this page