Freeroam Big Map Mode

M.dependencies = {'gameplay_rawPois', 'core_groundMarkers','core_camera','core_terrain', 'freeroam_bigMapMarkers'}

Dependencies

M.dependencies = {'gameplay_rawPois', 'core_groundMarkers','core_camera','core_terrain', 'freeroam_bigMapMarkers'}

Core controller for the big map (satellite view). Manages camera transitions, POI selection/hover, navigation routing, time-of-day changes, fog/shadow adjustments, level border fog walls, and UI interaction.

Internal State

Field	Type	Description

Public API

Function	Signature	Returns	Description
`M.enterBigMap`	`(options)`	`nil`	Opens the big map with optional config
`M.exitBigMap`	`(instant, closeEscMenu, forceGameCam)`	`nil`	Closes the big map
`M.toggleBigMap`	`()`	`nil`	Toggles big map open/close
`M.bigMapActive`	`()`	`boolean`	Returns whether big map is currently active
`M.isTransitionActive`	`()`	`boolean\|number`	Returns transition state (false/1/2)
`M.setOnlyIdsVisible`	`(list)`	`nil`	Sets which POI IDs are displayed
`M.setNavFocus`	`(pos)`	`nil`	Sets navigation destination
`M.selectPoi`	`(poiIdInCluster)`	`nil`	Selects a POI from code
`M.deselect`	`()`	`nil`	Deselects current POI
`M.poiHovered`	`(poiIdInCluster, hovered)`	`nil`	Handles POI hover from UI list
`M.navigateToMission`	`(poiId)`	`marker\|nil`	Sets navigation route to a mission/POI
`M.teleportToPoi`	`(poiId)`	`nil`	Quick-travels player vehicle to a POI
`M.zoom`	`(value)`	`nil`	Zooms the bigmap camera
`M.updateMergeRadius`	`(factor)`	`nil`	Updates cluster merge radius based on zoom
`M.getVerticalResolution`	`()`	`number`	Returns screen vertical resolution
`M.setRoutePreview`	`(route)`	`nil`	Sets mission route preview line
`M.clearRoutePreview`	`()`	`nil`	Clears route preview
`M.setRoutePreviewSimple`	`(from, to)`	-
`M.setBigmapScreenBounds`	`(windowSize, mapSize)`	-
`M.zoomInOut`	`(value, zoomIn)`	-
`M.controllerZoom`	`(value, zoomIn)`	-
`M.closePopupCallback`	`()`	-
`M.openPopupCallback`	`()`	-
`M.isUIPopupOpen`	`()`	-
`M.enterBigMapWithCustomPOIs`	`(poiIds, callback, options)`	-
`M.resetRoute`	`()`	-
`M.onClientStartMission`	`(levelPath)`	-
`M.onClientEndMission`	`(levelPath)`	-
`M.onMouseButton`	`(buttonDown)`	-
`M.onControllerSelect`	`()`	-
`M.camMoveController`	`(upDown, value)`	-
`M.camMoveKey`	`(value, direction)`	-
`M.onCameraPreRender`	`(camData)`	-
`M.onSerialize`	`()`	-
`M.onDeserialized`	`(v)`	-
`M.onMenuItemNavigation`	`()`	-
`M.onNavgraphReloaded`	`()`	-
`M.onChangeUiFilter`	`(value, dir)`	-
`M.onReachedTargetPos`	`()`	-

Key State

Field	Type	Description
`M.selectedPoiId`	`string\|nil`	Currently selected POI ID
`M.hoveredPoiId`	`string\|nil`	Currently hovered POI ID
`M.hoveredListItem`	`string\|nil`	Hovered item from UI list
`M.clusterMergeRadius`	`number`	Current cluster merge radius

Hooks Emitted

Hook	Args	When
`onBigMapActivated`	-	After big map fully opens
`onDeactivateBigMapCallback`	-	After big map fully closes
`onBigmapHoveredPoiIdChanged`	`hoveredPoiId`	Hover state changes
`onPoiSelectedFromBigmap`	`poiId`	POI selected
`onNavigateToMission`	`clusterId`	Navigation route set
`onSetBigmapNavFocus`	`pos`	Nav focus position set
`teleportedFromBigmap`	-	After quick travel

How It Works

Enter: Saves previous camera/fog/shadow/TOD state, calculates overhead camera position from terrain bounding box, builds transition camera path, pauses sim time
Transition: 4-marker camera path interpolates from vehicle orbit → overhead; fog fades out, shadows adjust, TOD shifts to bigMapTod
Active: Renders POI markers via bigMapMarkers, handles mouse/controller hover, draws navigation route as simplified cylinder path
Exit: Reverses transition, restores all previous state, pops action map

Options for `enterBigMap`

enterBigMap({
  instant = true,             -- Skip camera transition
  missionId = "mission_001",  -- Auto-open specific mission
  cameraAdditionalHeightFactor = 0.1,
  horizontalOffsetFactor = 1, -- UI sidebar compensation
})

Notes

Blocks most input actions while active via core_input_actionFilter
Uses BigMap action map for zoom/pan controls
Level borders rendered as fog wall TSStatic objects
Navigation route simplified based on camera height for performance
Career mode integration: delivery cargo screen intercepts toggle

Additional Exports

M.onUpdate - (undocumented)

Dependencies

M.dependencies = {'gameplay_rawPois', 'core_groundMarkers','core_camera','core_terrain', 'freeroam_bigMapMarkers'}

Internal State

Field	Type	Description

Public API

Function	Signature	Returns	Description
`M.enterBigMap`	`(options)`	`nil`	Opens the big map with optional config
`M.exitBigMap`	`(instant, closeEscMenu, forceGameCam)`	`nil`	Closes the big map
`M.toggleBigMap`	`()`	`nil`	Toggles big map open/close
`M.bigMapActive`	`()`	`boolean`	Returns whether big map is currently active
`M.isTransitionActive`	`()`	`boolean\|number`	Returns transition state (false/1/2)
`M.setOnlyIdsVisible`	`(list)`	`nil`	Sets which POI IDs are displayed
`M.setNavFocus`	`(pos)`	`nil`	Sets navigation destination
`M.selectPoi`	`(poiIdInCluster)`	`nil`	Selects a POI from code
`M.deselect`	`()`	`nil`	Deselects current POI
`M.poiHovered`	`(poiIdInCluster, hovered)`	`nil`	Handles POI hover from UI list
`M.navigateToMission`	`(poiId)`	`marker\|nil`	Sets navigation route to a mission/POI
`M.teleportToPoi`	`(poiId)`	`nil`	Quick-travels player vehicle to a POI
`M.zoom`	`(value)`	`nil`	Zooms the bigmap camera
`M.updateMergeRadius`	`(factor)`	`nil`	Updates cluster merge radius based on zoom
`M.getVerticalResolution`	`()`	`number`	Returns screen vertical resolution
`M.setRoutePreview`	`(route)`	`nil`	Sets mission route preview line
`M.clearRoutePreview`	`()`	`nil`	Clears route preview
`M.setRoutePreviewSimple`	`(from, to)`	-
`M.setBigmapScreenBounds`	`(windowSize, mapSize)`	-
`M.zoomInOut`	`(value, zoomIn)`	-
`M.controllerZoom`	`(value, zoomIn)`	-
`M.closePopupCallback`	`()`	-
`M.openPopupCallback`	`()`	-
`M.isUIPopupOpen`	`()`	-
`M.enterBigMapWithCustomPOIs`	`(poiIds, callback, options)`	-
`M.resetRoute`	`()`	-
`M.onClientStartMission`	`(levelPath)`	-
`M.onClientEndMission`	`(levelPath)`	-
`M.onMouseButton`	`(buttonDown)`	-
`M.onControllerSelect`	`()`	-
`M.camMoveController`	`(upDown, value)`	-
`M.camMoveKey`	`(value, direction)`	-
`M.onCameraPreRender`	`(camData)`	-
`M.onSerialize`	`()`	-
`M.onDeserialized`	`(v)`	-
`M.onMenuItemNavigation`	`()`	-
`M.onNavgraphReloaded`	`()`	-
`M.onChangeUiFilter`	`(value, dir)`	-
`M.onReachedTargetPos`	`()`	-

Key State

Field	Type	Description
`M.selectedPoiId`	`string\|nil`	Currently selected POI ID
`M.hoveredPoiId`	`string\|nil`	Currently hovered POI ID
`M.hoveredListItem`	`string\|nil`	Hovered item from UI list
`M.clusterMergeRadius`	`number`	Current cluster merge radius

Hooks Emitted

Hook	Args	When
`onBigMapActivated`	-	After big map fully opens
`onDeactivateBigMapCallback`	-	After big map fully closes
`onBigmapHoveredPoiIdChanged`	`hoveredPoiId`	Hover state changes
`onPoiSelectedFromBigmap`	`poiId`	POI selected
`onNavigateToMission`	`clusterId`	Navigation route set
`onSetBigmapNavFocus`	`pos`	Nav focus position set
`teleportedFromBigmap`	-	After quick travel

How It Works

Enter: Saves previous camera/fog/shadow/TOD state, calculates overhead camera position from terrain bounding box, builds transition camera path, pauses sim time
Transition: 4-marker camera path interpolates from vehicle orbit → overhead; fog fades out, shadows adjust, TOD shifts to bigMapTod
Active: Renders POI markers via bigMapMarkers, handles mouse/controller hover, draws navigation route as simplified cylinder path
Exit: Reverses transition, restores all previous state, pops action map

Options for `enterBigMap`

enterBigMap({
  instant = true,             -- Skip camera transition
  missionId = "mission_001",  -- Auto-open specific mission
  cameraAdditionalHeightFactor = 0.1,
  horizontalOffsetFactor = 1, -- UI sidebar compensation
})

Notes

Blocks most input actions while active via core_input_actionFilter
Uses BigMap action map for zoom/pan controls
Level borders rendered as fog wall TSStatic objects
Navigation route simplified based on camera height for performance
Career mode integration: delivery cargo screen intercepts toggle

Additional Exports

M.onUpdate - (undocumented)

Freeroam Big Map Mode

Dependencies

Internal State

Public API

Key State

Hooks Emitted

How It Works

Options for `enterBigMap`

Notes

Additional Exports

See Also

On this page

Freeroam Big Map Mode

Dependencies

Internal State

Public API

Key State

Hooks Emitted

How It Works

Options for `enterBigMap`

Notes

Additional Exports

See Also

On this page