Crawl Marker

A feature-rich race checkpoint marker with a floating arrow, two roadside flags, and a distant visibility column. Supports multiple color modes, fade distances, line-of-sight occlusion avoidance, and minimap drawing.

Class API (OOP via metatable)

Visual Modes

Components

Arrow Behavior

• Height: Uses TemporalSpring to smoothly animate; starts low, rises after delay
• LOS avoidance: Raycasts upward in 2-unit increments (up to 100) to avoid occlusion
• Scale: Shrinks to 0.3 within 15m, normal at 2.0; finished/inactive markers 40% smaller
• Bobbing: sin(clock * 1.9 + offset) * 0.4 for natural movement

Flag Behavior

• Positioned ±2.5 units perpendicular to path direction
• Snaps to terrain height with smooth normal alignment
• Falls back to be:getSurfaceHeightBelow if core_terrain unavailable

Column Behavior

• Fade in: 200–300m distance (linear alpha ramp)
• Height scale: 50–200 units, scaling with distance (200–1200m)
• Full opacity at 300m+, hidden below 200m

How It Works

1. Constructor creates instance with spring smoothers for height, scale, and alpha
2. createMarkers() spawns arrow, two flags, and column TSStatic objects
3. setToCheckpoint(wp) positions everything, captures path direction for flag placement
4. update() each frame handles:
   • Color lerping between mode transitions (0.5s duration)
   • Alpha fade based on 2D distance from camera
   • Arrow LOS checks and height animation
   • Flag terrain snapping and rotation
   • Column distance-based visibility

Usage Examples

local marker = require('scenario/raceMarkers/crawlMarker')(1)
marker:createMarkers()
marker:setToCheckpoint({
  pos = vec3(100, 200, 50),
  radius = 5,
  dir = vec3(0, 1, 0),    -- path direction
  delay = 0.5,            -- delay before arrow rises
  fadeNear = 5,
  fadeFar = 25,
})
marker:setMode('current')

-- Each frame
marker:update(dt, dtSim)

-- Cleanup
marker:clearMarkers()

Key Notes

• Most complex race marker with 4 sub-objects and multiple animation systems
• Uses castRayStatic for arrow LOS avoidance - ensures arrow is always visible
• Path direction (wp.dir or wp.nextPos) determines flag placement sides
• Column provides long-range visibility when arrow would be too small to see
• All objects added to ScenarioObjectsGroup with canSave = false

See Also

• Race Marker: Attention - Floating Arrow Checkpoint Marker - Related reference
• Race Marker: Cylinder - Base + Cylinder Checkpoint Marker - Related reference
• None Marker - Invisible Race Checkpoint Marker - Related reference
• Scenario System Guide - Guide