Crawl Boundaries

Reference for gameplay_crawl_boundary, which manages spatial boundaries for rock crawling trails. Spawns animated flag markers along boundaries, checks crawler positions against boundary zones, and applies penalties/DNF for violations.

Overview

This extension handles three core responsibilities for crawl boundaries:

1. Marker spawning - Places flag markers along boundary perimeters with proximity-based show/hide animations
2. Boundary checking - Determines if crawler vehicle corners are inside the boundary zone
3. Penalty enforcement - Tracks exit points and applies DNF if a crawler strays 10+ meters outside

Uses a quadtree for efficient proximity queries of boundary markers.

Exports

Boundary Checking Logic

checkBoundary() evaluates all corners of the crawler vehicle:

1. If all corners inside - crawler is within bounds, exit tracking is cleared
2. If some corners outside - boundary violation penalty applied (with cooldown)
3. If all corners outside AND 10+ meters from exit point - DNF penalty applied once

Exit points are tracked per crawler: the first position where the vehicle leaves the boundary is saved, and distance from that point determines DNF.

Marker Animation System

Markers use a proximity-based animation with four states:

• "hidden" - Object is hidden, scale at minimum
• "appearing" - Fading in + scaling up over animationDuration
• "visible" - Fully shown at max scale
• "disappearing" - Fading out over fadeOutDuration

Default animation timing:

How It Works

-- Spawn markers along a boundary with 5m spacing
gameplay_crawl_boundary.spawnBoundaryMarkers(boundary, 5.0)

-- Per-frame animation update
gameplay_crawl_boundary.updateBoundaryAnimations(dtSim)

-- Check if crawler is in bounds
local inBounds = gameplay_crawl_boundary.checkBoundary(site, crawlerData, crawlStates)

-- Cleanup
gameplay_crawl_boundary.cleanupBoundaryMarkers()

Key Behaviors

• Markers use TSStatic objects with the /art/shapes/race/flagMarker.dae mesh
• Markers are grouped under a SimGroup named "BoundaryMarkers"
• Terrain height and normal are used for proper marker placement
• Markers on steep terrain (normal dot < 0.5 with world up) are skipped
• Uses smootherstep interpolation for smooth animations
• instanceColor alpha channel controls visibility during animations

See Also

• crawl/crawlFlowgraphBridge - Crawl Flowgraph Bridge (Legacy) - Related reference
• crawl/debug - Crawl Debug Window - Related reference
• crawl/display - Crawl UI Messages - Related reference
• Gameplay Systems Guide - Guide