Crawl System

Reference for gameplay_crawl_general, the main manager for rock crawling trails. Handles trail setup, crawl lifecycle, POI registration, big map integration, activity dialogs, and score persistence.

Overview

This is the central coordinator for the crawl system. It manages the active trail state, delegates to crawl_utils for the actual crawl logic, registers POIs on the big map, handles activity acceptance dialogs, and saves scores through the save system.

Dependencies

gameplay_crawl_saveSystem, gameplay_crawl_utils, gameplay_crawl_boundary, gameplay_crawl_display

Exports

Module State

• M.activeTrail - Table with trail, boundary, path, startingPosition, prefabs, isFromMission
• M.crawlersData - Array of crawler data objects

Trail Setup

setupCrawl() performs:

1. Loads boundary, path, and starting position from save system
2. Handles path reversal (reverses nodes, flips rotations by 180°)
3. Sets up crawler data via utils.setupCrawlerData
4. Loads trail prefabs
5. Optionally teleports vehicle to starting position (mission mode)

How It Works

-- Freeroam crawl (from POI interaction)
local trail = gameplay_crawl_saveSystem.getTrailById(trailId)
gameplay_crawl_general.startCrawlFreeroam(trail, be:getPlayerVehicle(0))

-- Mission crawl (from flowgraph)
gameplay_crawl_general.setupCrawl(trail, veh, true)
gameplay_crawl_general.startCrawlFlowgraph(trail, veh)

-- Clear everything
gameplay_crawl_general.clear(true)

POI / Big Map Integration

onGetRawPoiListForLevel() registers crawl trails as POIs when:

• Career is active OR enableCrawlInFreeroam setting is on
• No crawl is currently active
• Trail has a valid starting position

POIs include:

• crawlMarker - In-world marker with position, rotation, radius
• bigmapMarker - Big map entry with icon, name, description, thumbnail, quick travel

Activity Accept Dialog

When a player approaches a crawl POI, onActivityAcceptGatherData() builds a dialog with:

• Trail name and "Freeroam Crawl" category
• Path stats (distance, elevation gain/loss)
• Player's best penalty points, best time, and attempt count
• A "Play" button that starts the freeroam crawl

Key Behaviors

• Path reversal uses arrayReverse and rotates each node by π around the Y axis
• Reversed trails can have a separate startingPositionIdReversed or derive position from the first reversed node
• Non-mission crawls are automatically cleared on vehicle switch or destroy
• Scores are saved via gameplay_crawl_saveSystem.addNewPlayerScore on results shown
• The onSerialize hook clears state to prevent stale data across saves

Public API

Module Variables

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