Marker Interaction
Central system for rendering and interacting with playmode markers (mission markers, parking spots, gas stations, etc.). Manages marker visibility, speed-based interaction gating, activity prompts, na
Central system for rendering and interacting with playmode markers (mission markers, parking spots, gas stations, etc.). Manages marker visibility, speed-based interaction gating, activity prompts, navigation, and ground marker rendering.
Public API
| Function | Signature | Returns | Description |
|---|---|---|---|
M.getCurrentInteractableElements | () | table | Returns elements currently within interaction range |
M.formatMission | (mission) | table | Formats a mission object for UI display |
M.formatDataForUi | () | table|nil | Returns formatted mission data for all current interactable elements |
M.closeViewDetailPrompt | (force?) | nil | Closes the activity accept dialogue |
M.showMissionMarkersToggled | (active) | nil | Clears and resends POI data when setting changes |
M.setMarkersVisibleTemporary | (visible) | nil | Temporarily shows/hides all markers |
M.skipNextIconFading | () | nil | Skips fade animation for next frame |
M.clearCache | () | nil | Forces re-evaluation of open prompts |
M.setForceReevaluateOpenPrompt | () | nil | Flags prompt re-evaluation on next frame |
M.onNavigateToMission | (poiId) | nil | Sets navigation target, resets focus |
M.onPreRender | (dtReal, dtSim) | nil | Main render/update loop |
M.getGameContext | (fromMissionMenu?) | table | Returns mission screen data |
M.abandonCurrent | value | - | abandonCurrent handler |
M.changeUserSettings | (id, settings) | - | changeUserSettings handler |
M.dependencies | value | - | Returns list of extension dependencies |
M.getClusterMarker | value | - | Returns ClusterMarker |
M.onAnyMissionChanged | (state) | - | Callback for AnyMissionChanged event |
M.onClientEndMission | (levelPath) | - | Callback for ClientEndMission event |
M.onSelectDetailPromptClicked | (idx) | - | Callback for SelectDetailPromptClicked event |
M.onSettingsChanged | () | - | Callback for SettingsChanged event |
M.onUIPlayStateChanged | (enteredPlay) | - | Callback for UIPlayStateChanged event |
M.restartCurrent | value | - | restartCurrent handler |
M.setPreselectedMissionId | (mId) | - | Sets PreselectedMissionId |
M.startMissionById | (id, userSettings, startingOptions) | - | startMissionById handler |
M.stopMissionById | (id, force) | - | stopMissionById handler |
Dependencies
gameplay_missions_missions,gameplay_missions_missionManager,freeroam_bigMapMode,gameplay_playmodeMarkers,freeroam_bigMapPoiProvider,ui_missionInfo
Internals
Speed-Based Interaction
Two speed gates control when markers become interactable:
- Parking speed (< 1 km/h → interactable): Uses hysteresis between 1–3 km/h
- Cruising speed (> 20 km/h → icons fade): Uses hysteresis between 20–30 km/h
Walking mode uses area enter/exit events instead of speed checks.
Marker Rendering Pipeline (onPreRender)
- Calculate vehicle position, bounding box, velocity
- Query
playmodeMarkersquadtree for nearby clusters (100m radius) - For each nearby cluster: show marker, call
marker:update(updateData), collect ground decals - If at parking speed: call
marker:interactInPlayMode()→ collect interactable elements - If interactable elements found: open activity accept dialogue via
ui_missionInfo - Render all collected decals via
Engine.Render.DynamicDecalMgr.addDecals
Navigation
When navigating to a mission (onNavigateToMission), ground markers guide the player. When path length < 7m, reachedTarget() fires and clears navigation.
Activity Accept Dialogue
When multiple activities overlap, onActivityAcceptGatherData hook collects data from all systems, sorted by type/order. Displayed via ui_missionInfo.openActivityAcceptDialogue().
How It Works
- Markers are provided by
gameplay_playmodeMarkersas clusters with type-specific marker objects - Each frame, visible markers are updated with vehicle/camera data
- Speed determines interaction mode: cruising (icons visible) vs parking (prompts appear)
- Walking mode triggers on area enter/exit rather than speed
Hooks / Lifecycle
| Function | Description |
|---|---|
onPreRender | Main render/update loop: marker visibility, interaction, decals |
onSettingsChanged | Updates screen dimensions for marker rendering |
onAnyMissionChanged | Refreshes POI data on mission start/stop |
onClientEndMission | Clears navigation target |
onUIPlayStateChanged | Forces prompt re-evaluation when entering play state |
Usage Example
-- Navigate to a specific POI
gameplay_markerInteraction.onNavigateToMission("missionMarker#myMission")
-- Force prompt refresh
gameplay_markerInteraction.setForceReevaluateOpenPrompt()See Also
- Gameplay Achievement - Related reference
- Gameplay City - Related reference
- discover - Discover / Experience System - Related reference
- Gameplay Systems Guide - Guide
Garage Mode
Manages the garage environment for vehicle inspection/customization. Handles camera orbit setup, vehicle freezing, ceiling/pillar auto-hide, lighting groups, input blocking, and garage-to-test-drive t
Parking System
Reference for `gameplay_parking`, which manages spawning, positioning, and recycling of AI parked vehicles using parking spot site data and vehicle active pooling.