Campaign Exploration
Free-roam exploration mode between campaign scenarios. Manages trigger zones, location markers, road navigation, minimap UI, vehicle spawning, and transitions between exploration and scenarios.
Free-roam exploration mode between campaign scenarios. Manages trigger zones, location markers, road navigation, minimap UI, vehicle spawning, and transitions between exploration and scenarios.
Dependencies
M.dependencies = {'campaign_campaigns'}Overview
Depends on campaign_campaigns. Provides the "overworld" between campaign missions - the player drives freely, encounters location triggers, views mission info, accepts scenarios, and navigates via ground markers. Handles subsection prefab spawning, site/scenario/transition triggers, and minimap display.
Public API
| Function | Args | Returns | Description |
|---|---|---|---|
M.startSubsectionExploration | subsectionKey, locationMarker, spawningData | - | Starts exploration in a campaign subsection |
M.endSubsectionExploration | - | - | Cleans up exploration (prefabs, vehicles, markers, UI) |
M.stop | - | - | Stops exploration mode and cleans up UI |
M.getExplorationActive | - | boolean | Whether exploration is currently active |
M.isValidSubsection | campaign, subsectionName | boolean | Checks if subsection exists in campaign |
M.isValidLocation | campaign, subsectionName, locationKey | boolean | Checks if location exists in subsection |
M.accept | - | - | UI callback: show mission details or trigger acceptance |
M.decline | - | - | UI callback: decline mission and show short info |
M.setFocusPOI | poi | - | Sets focused point of interest with ground marker navigation |
M.onFocusPOI | poi | - | UI callback: focus a POI from map view |
M.buildRoadIndicator | - | - | Builds road navigation path to focused POI |
M.queryRoadNodeToPosition | vehicle, position, owner | - | Finds closest road node to a position |
M.toggleMinimap | - | - | Toggles minimap UI (pauses/resumes sim time) |
M.updateMapUI | - | - | Sends full minimap data to UI |
M.refreshLocationMarkers | subsection | - | Creates/refreshes 3D markers for locations |
M.startTimeTrail | scenarioFile, trackFile, vehicleFile | - | Starts a quick race time trial from exploration |
M.uiEventSelectVehicle | vehicleData | - | Handles vehicle selection from garage/dealer UI |
M.uiEventGarageExit | - | - | Handles garage UI exit |
M.onBeamNGTrigger | data | - | Processes trigger enter/exit events |
M.onUpdate | - | - | Per-frame: loads next scenario when flagged |
M.onPreRender | dt | - | Per-frame: road queries, marker updates, vehicle spawning |
M.onVehicleSpawned | vehicleId | - | Tracks recently spawned vehicles |
M.onClientStartMission | levelPath | - | Processes pending exploration after level load |
M.onClientEndMission | levelPath | - | Cleans up exploration on mission end |
M.onUiChangedState | curUIState, prevUIState | - | Handles UI state transitions during exploration |
M.onCameraToggled | data | - | Handles FreeCam/GameCam transitions |
M.onSerialize | - | table | Serializes exploration state |
M.onDeserialized | data | - | Restores exploration state |
M.onSaveCampaign | saveCallback | - | Provides state for campaign save |
M.onResumeCampaign | campaignInProgress, data | - | Restores state from save |
M.onUILayoutLoaded | layoutType | - | Shows map hint when exploration layout loads |
Internal State
| Field | Type | Description |
|---|
Trigger Flow
Player enters trigger zone → onBeamNGTrigger
→ Site location? → handleSiteTrigger (transition/missionGiver/HQ/vendor)
→ Scenario? → handleScenarioTrigger → openShortLocationInfo → accept()
→ Ramp trigger? → Save checkpoint position
Player exits trigger → Clear trigger state, close dialogueInput Filtering
Blacklisted actions during exploration:
{"switch_next_vehicle", "switch_previous_vehicle", "loadHome", "saveHome",
"reload_vehicle", "reload_all_vehicles", "vehicle_selector", "parts_selector",
"dropPlayerAtCamera", "toggleWalkingMode", "toggleTraffic", "toggleAITraffic"}Location Marker System
-- 3D markers are TSStatic checkpoint models
-- Colors indicate state:
-- White = available scenario (can improve)
-- Yellow = available site
-- Green = focused/selected POIMinimap Data
The minimap provides:
- POI positions normalized to map coordinates
- Player position and heading
- Location states (ready/completed/medal)
- Mission log entries (photo safari)
Notes
- Level transitions are handled asynchronously - spawning data is stored in
pendingSpawningData - Ramp triggers save checkpoint positions for jump recovery
- Exploration uses
core_gamestate.setGameState('exploration', ...)in shipping builds - Vehicle freezing (
controller.setFreeze) is used during UI interactions - The
race_markermodule provides destination markers with nav paths - Collision is reloaded when transitioning from a scenario
See Also
- Campaign System - Campaign orchestration
- Campaign Loader - Campaign file and save management
- Campaign Photo Safari - Photo mode missions in exploration
Additional Exports
M.recentlySpawnedVehicle- (undocumented)M.state- (undocumented)
Campaign Dealer
Vehicle and item stock management for campaign dealer/vendor locations. Tracks purchasable inventory with add/remove/buy operations and campaign save/resume support.
Campaign Photo Safari
Photo safari mission system for campaign exploration. Players drive to locations, enter photo mode, and capture specific objects within camera constraints.