Core Checkpoints

Manages vehicle checkpoint saving and restoration for scenario races. Tracks waypoint progress, saves vehicle position/direction at each checkpoint, and handles automated AI vehicle resets when stuck.

Overview

The checkpoint system saves vehicle state (position, direction, up vector) when waypoints are reached during races. Players and AI can be reset to their last checkpoint. AI vehicles are automatically reset if stationary for 4+ seconds after leaving the start. Integrates with scenario_waypoints for race progress tracking.

Module State

Public Functions

Checkpoint Data Structure

vehicleCheckpoints[vehicleId] = {
  vehicleName = "vehicle_name",
  checkTimer = 0,               -- AI stuck detection timer
  pos = vec3(),                  -- saved position
  dirVec = vec3(),               -- saved direction vector
  upVec = vec3(),                -- saved up vector
  currentWpName = "wp_name",    -- current waypoint name
  currentWpIndex = 3,           -- current waypoint index
  nextWpIndex = 4,              -- next waypoint index
  initialPos = vec3(),          -- spawn position (for AI stuck detection)
  raceOver = false,             -- vehicle finished the race
}

Vehicle Reset Flow

-- 1. Reset vehicle to saved checkpoint
vehicle:resetBrokenFlexMesh()
vehicle:setPositionRotation(pos.x, pos.y, pos.z, rot.x, rot.y, rot.z, rot.w)

-- 2. Queue autoplace + callback via round-trip through vehicle Lua
obj:queueGameEngineLua("getObjectByID(id):autoplace(false); core_checkpoints.completeReset(id, name)")

-- 3. completeReset restores AI path and updates waypoint tracking
helper.setAiPath(aiVehiclePath[vehicleId])
scenario_waypoints.updateResetVehicleData(vehicleId, currentWpIndex, nextWpIndex)

AI Stuck Detection

-- Every 4 seconds, check if AI vehicle has moved
if (vehPos - data.prevVehPos):squaredLength() < 0.0016 then
  -- Vehicle moved less than 4cm in 4 seconds → reset to checkpoint
  ResetToSavedCheckpoint(vehicle, data.vehicleName)
end

Key Notes

• Only active when scenario has enableCheckpoints and lapConfig with 2+ points
• Checkpoint direction uses waypoint direction (directional WP) or vehicle velocity
• Serialization converts vehicle ID keys ↔ vehicle name keys for save compatibility
• Uses convertVehicleIdKeysToVehicleNameKeys / convertVehicleNameKeysToVehicleIdKeys
• AI vehicles skip stuck detection until they've left their initial position
• Race completion sets raceOver = true to prevent AI resets after finishing
• M.state - Table. Checkpoint state ({vehicleCheckpoints = {}}).
• M.onVehicleSpawned(id) - Hook: vehicle spawned.
• M.onVehicleDestroyed(id) - Hook: vehicle destroyed.
• M.onClientPreStartMission() - Hook: before mission start.
• M.onClientEndMission() - Hook: mission ended.
• M.completeReset(vehicleId, vehicleName) - Fully resets checkpoint state for a vehicle.
• M.onRaceWaypointReached(data) - Hook: race waypoint reached.
• M.onSerialize() - Serializes checkpoint state for save.
• M.onDeserialized(data) - Restores checkpoint state from save.
• M.onScenarioRestarted() - Hook: scenario restarted.
• M.onPreRender(dtReal, dtSim, dtRaw) - Hook: pre-render update.
• M.onSaveCampaign() - Hook: campaign save.
• M.onResumeCampaign() - Hook: campaign resumed.
• M.saveCheckpoint(vehicleId, vehicleName, cpData) - Saves a checkpoint for the given vehicle.
• M.saveAIPath(vehicleName, arg) - Saves the AI path for a vehicle.