API ReferenceGE Extensionsfreeroam
Freeroam Crash Cam Mode
Detects imminent vehicle crashes and triggers cinematic slow-motion camera modes. Supports vehicle-vehicle collisions, static wall impacts, and velocity-based crash detection.
Detects imminent vehicle crashes and triggers cinematic slow-motion camera modes. Supports vehicle-vehicle collisions, static wall impacts, and velocity-based crash detection.
Internal State
| Field | Type | Description |
|---|---|---|
M.onSettingsChanged | varies | Assigned as onSettingsChanged |
Public API
| Function | Signature | Returns | Description |
|---|---|---|---|
M.setTrackingMode | (mode) | nil | Sets tracking mode (1=traffic+static, 2=all vehicles+static) |
M.getTrackingMode | () | number | Returns current tracking mode |
M.setForcedEnabled | (enabled) | nil | Force-enables crash cam outside freeroam |
M.trackCamMode | () | nil | Cancels crash cam on manual camera change |
M.trackVehReset | () | nil | Cancels crash cam on vehicle reset |
M.onUpdate | (dtReal, dtSim) | Per-frame crash detection and camera management | |
M.onReplayStateChanged | (state) | - | |
M.onSerialize | () | - | |
M.onClientStartMission | () | - | |
M.onClientEndMission | (levelPath) | - | |
M.onExtensionUnloaded | () | - |
Camera Modes
| Mode | Probability | Description |
|---|---|---|
| 1 | 45% | Close overhead static camera focused on crash point |
| 2 | 45% | Ground-level camera that rotates to track crash |
| 3 | 10% | Time-freeze orbit around crash point (5s cooldown) |
Detection Methods
OBB-based Vehicle Collision
- Projects player + traffic vehicle bounding boxes forward by
lookAheadTime(0.2s) - Checks OBB-OBB overlap with
bbSizeFactor(0.85) shrink - Requires velocity difference ≥
crashSpeedCutoff(13 m/s)
Static Wall Raycast
- Casts rays from bottom-edge points in the velocity direction
- Checks incline angle > 45° and edge angle for head-on detection
- Verifies velocity component toward wall exceeds speed cutoff
Velocity-Based Fallback
- Samples player velocity every 0.1s
- Triggers if velocity change exceeds
crashSpeedCutoff + 3m/s
How It Works
- Detection (
onUpdate): If cooldown passed and no active crash cam, checks collisions in order: traffic vehicles → walls → velocity delta - Activation (
toggleActionCam(true)): Saves sim speed/camera/UI state, sets sim to 0.15x, switches to crash camera - Active Phase: Tracks crash intersection, monitors vehicle visibility in frustum, mode 3 builds orbit camera path
- Deactivation: Restores sim speed, UI visibility, previous camera mode after
crashCamDuration(4s) or if vehicle leaves frame
Lifecycle Hooks
| Hook | Purpose |
|---|---|
onVehicleResetted | Cancels crash cam for player vehicle |
onVehicleSwitched | Cancels and restores previous camera |
onAnyMissionChanged | Disables during missions, re-enables after |
onBeforeBigMapActivated | Cancels crash cam |
onTogglePause | Cancels crash cam |
onExtensionLoaded | Returns false if setting disabled |
Notes
- Only active in freeroam game state unless
forcedEnabled - Requires
enableCrashCamsetting to be true - Mode 3 (orbit) uses
core_paths.playPath()with pause-smooth for dramatic freeze - Teleport detection prevents false triggers during vehicle repositioning
- Loaded conditionally by
freeroam_crashCamModeLoader
Additional Exports
M.onAnyMissionChanged- (undocumented)M.onBeforeBigMapActivated- (undocumented)M.onExtensionLoaded- (undocumented)M.onTogglePause- (undocumented)M.onVehicleResetted- (undocumented)M.onVehicleSwitched- (undocumented)
See Also
- Freeroam Big Map Markers - Related reference
- Freeroam Big Map Mode - Related reference
- Freeroam Big Map POI Provider - Related reference
- Freeroam Guide - Guide
Freeroam Big Map POI Provider
M.dependencies = {'gameplay_missions_missions','freeroam_bigMapMode', 'gameplay_rawPois', 'gameplay_playmodeMarkers'}
Freeroam Crash Cam Mode Loader
Conditionally loads/unloads the crash cam extension based on the `enableCrashCam` user setting. Acts as a lightweight settings-reactive loader.