Crawl Engine
Reference for `gameplay_crawl_utils`, the core runtime engine for rock crawling gameplay. Handles crawl state management, pathnode detection, penalty/infraction system, marker rendering, vehicle track
Reference for gameplay_crawl_utils, the core runtime engine for rock crawling gameplay. Handles crawl state management, pathnode detection, penalty/infraction system, marker rendering, vehicle tracking, prefab management, and lap times integration.
Overview
This is the largest and most critical module in the crawl system. It manages all active crawl states, detects pathnode completion with directional validation, enforces the infraction/penalty system, renders trail markers, handles vehicle resets, and integrates with the lap times app.
Exports - State Management
| Function | Signature | Description |
|---|---|---|
startCrawl | (crawlerId, trail, crawlerData, isFromMission) | Initialize a new crawl state |
stopCrawl | (force) | Stop all active crawls |
resetCrawlData | (crawlerId, force) | Reset a crawler's state |
resumeCrawlTimer | (crawlerId) | Resume a paused crawl timer |
updateCrawl | (dtSim) | Main per-frame update loop |
clear | (force) | Clear all states and markers |
clearCrawler | (crawlerId) | Remove a specific crawler |
getCrawlState | (crawlerId) | Get state for a crawler |
setCrawlState | (crawlerId, state) | Set state for a crawler |
getAllCrawlStates | () | Get all active crawl states |
getActiveCrawlerId | () | Get the first active crawler ID |
Exports - Crawler Data
| Function | Signature | Description |
|---|---|---|
setupCrawlerData | (veh) | Create crawler tracking data (position, wheels, velocity) |
getCrawlerPosition | (crawlerId) | Get crawler vehicle position |
getCrawlerDirection | (crawlerId) | Get crawler yaw as quaternion |
Exports - Markers & Display
| Function | Signature | Description |
|---|---|---|
setupCrawlMarkers | (path) | Create path markers for a trail |
activateCrawlMarkers | () | Activate marker modes for gameplay |
clearMarkers | () | Remove all markers |
onPreRender | (dtReal, dtSim, dtRaw) | Render markers and preview path |
onDrawOnMinimap | (td) | Draw markers on minimap |
Exports - Penalties & Infractions
| Function | Signature | Description |
|---|---|---|
applyPenalty | (crawlerId, penaltyType, points) | Apply a penalty |
onVehicleFlippedUpright | (crawlerId) | Handle flip-upright event |
onVehicleReset | (crawlerId) | Handle vehicle reset event |
onBoundaryViolation | (crawlerId) | Handle boundary violation |
Infraction Points
| Type | Points | Description |
|---|---|---|
drivingBackwards | +1 | Driving in reverse |
vehicleFlippedUpright | +5 | Vehicle flip recovery |
gateTouch | +10 | Touching a dynamic gate object |
vehicleReset | +10 | Vehicle position reset |
boundaryViolation | +10 | Leaving boundary area |
wrongDirection | +10 | Going wrong way |
skippedCheckpoint | +10 | Per skipped checkpoint |
dnf | +50 | Did Not Finish penalty |
gateCleared | -2 | Bonus for clearing a gate |
bonusGateCleared | -15 | Bonus for clearing a bonus gate |
Points accumulate. At 50 points, the crawler is disqualified (DNF).
Pathnode Detection
checkPathnodeReached() uses optimized proximity checks:
- Only checks pathnodes near the current index (current-1 to current+3)
- Uses squared distance against vehicle wheel corners (avoids sqrt)
- Direction validation - If a pathnode has a rotation:
- Approach direction must align with pathnode forward
- Vehicle facing must match pathnode direction
- Vehicle velocity must match (if moving)
- Skipped nodes between current and reached are auto-completed with penalties
How It Works
-- Setup crawler data for a vehicle
local crawlerData = gameplay_crawl_utils.setupCrawlerData(veh)
-- Start a crawl
gameplay_crawl_utils.startCrawl(vehId, trail, crawlerData, true)
-- Per-frame update (called from general.onUpdate)
gameplay_crawl_utils.updateCrawl(dtSim)
-- Apply a penalty
gameplay_crawl_utils.applyPenalty(crawlerId, 'boundaryViolation')Vehicle Reset Detection
The module monkey-patches commands.dropPlayerAtCameraNoReset and recovery.startRecovering to detect vehicle resets during crawls. A pendingTeleportCheck flag is set before the teleport, and the next frame checks if the vehicle actually moved (>1m threshold) to confirm the reset.
Key Behaviors
- Marker modes:
hidden,current,final,inactive,finished,recovery,bonus,skipped - Dotted preview path with animated sine-wave sphere radius for preview mode
- Lap times integration via
core_lapTimes- creates race-like data structures - Completion triggers a 3-second delay before auto-stopping (freeroam only)
- Dynamic objects (gates) from prefabs are tracked for collision detection via
map.objects[id].objectCollisions - Driving backwards detection uses velocity dot product with forward direction, with distance accumulation threshold
Additional Exports
| Function | Signature | Description |
|---|---|---|
isPreviewMode | () → bool | Whether crawl is in preview/spectator mode |
getDottedPath | () → table | Returns the dotted preview path data |
drawMarkers | (dtReal, dtSim, dtRaw) | Renders trail markers (called from onPreRender) |
loadPrefabs | (prefabFileList) | Loads crawl prefabs (gates, dynamic objects) |
unloadPrefabs | () | Unloads all crawl prefabs |
calculatePathStats | (pathId, pathReversed) | Computes path statistics (distance, elevation) |
getDynamicObjectsFromPrefab | (prefabId, dynamicName) → table | Finds named dynamic objects in a prefab |
getLastRecoveryCheckpoint | (crawlerId) → table | Returns the last recovery checkpoint data |
getLastRecoveryCheckpointIndex | (crawlerId) → number | Returns index of last recovery checkpoint |
setRecoveryCheckpoint | (crawlerId, checkpoint) | Sets a manual recovery checkpoint |
trackVehReset | () | Monkey-patches vehicle reset functions to detect resets during crawls |
Module Variables
| Variable | Type | Description |
|---|---|---|
infractionPoints | table | Maps penalty type → point values |
infractionCooldowns | table | Maps penalty type → cooldown durations |
drivingBackwardsSettings | table | Settings for backwards-driving detection thresholds |
M.activateCrawlMarkers | () | - |
M.applyPenalty | (crawlerId, penaltyType, points) | - |
M.calculatePathStats | (pathId, pathReversed) | - |
M.clear | (force) | - |
M.clearCrawler | (crawlerId) | - |
M.clearMarkers | () | - |
M.drawMarkers | (dtReal, dtSim, dtRaw) | - |
M.drivingBackwardsSettings | value | - |
M.getActiveCrawlerId | () | - |
M.getAllCrawlStates | () | - |
M.getCrawlState | (crawlerId) | - |
M.getCrawlerDirection | (crawlerId) | - |
M.getCrawlerPosition | (crawlerId) | - |
M.getDottedPath | () | - |
M.getDynamicObjectsFromPrefab | (prefabId, dynamicName) | - |
M.getLastRecoveryCheckpoint | (crawlerId) | - |
M.getLastRecoveryCheckpointIndex | (crawlerId) | - |
M.infractionCooldowns | value | - |
M.infractionPoints | value | - |
M.isPreviewMode | () | - |
M.loadPrefabs | (prefabFileList) | - |
M.onBoundaryViolation | (crawlerId) | - |
M.onDrawOnMinimap | (td) | - |
M.onPreRender | (dtReal, dtSim, dtRaw) | - |
M.onVehicleFlippedUpright | (crawlerId) | - |
M.onVehicleReset | (crawlerId) | - |
M.resetCrawlData | (crawlerId, force) | - |
M.resumeCrawlTimer | (crawlerId) | - |
M.setCrawlState | (crawlerId, state) | - |
M.setRecoveryCheckpoint | (crawlerId, checkpoint) | - |
M.setupCrawlMarkers | (path) | - |
M.setupCrawlerData | (veh) | - |
M.startCrawl | (crawlerId, trail, crawlerData, isFromMission) | - |
M.stopCrawl | (force) | - |
M.trackVehReset | () | - |
M.unloadPrefabs | () | - |
M.updateCrawl | (dtSim) | - |
See Also
- crawl/boundary - Crawl Boundary System - Related reference
- crawl/crawlFlowgraphBridge - Crawl Flowgraph Bridge (Legacy) - Related reference
- crawl/debug - Crawl Debug Window - Related reference
- Gameplay Systems Guide - Guide
Crawl Save System
Reference for `gameplay_crawl_saveSystem`, which handles loading, saving, serialization, and caching of crawl trail data (trails, boundaries, paths, starting positions) as well as player score persist
Delivery Missions
Reference for `gameplay_delivery_delivery`, a class-based module providing delivery mission logic. Manages location selection, route calculation, timing, damage checking, and delivery progression.