Scenario Waypoints

Dependencies

M.dependencies = {'scenario_scenarios'}

The core waypoint tracking system for scenario races. Manages waypoint progression, branching paths, lap counting, vehicle trigger detection via wheel-corner intersection, and marker mode updates.

Public API (Exports)

State Structure

M.state = {
  vehicleWaypointsData = {},   -- vid → {cur, next, lap, waypointConfig, nextWps, wheelOffsets, ...}
  nextWpForVehicle = {},       -- vid → next waypoint index
  waypointBranches = {},       -- branchName → list of waypoint names
  branchGraph = {},            -- branchName → {index → {cpName, successors, isFinalWaypoint, ...}}
  pathnodes = {},              -- wpName → pathnode object (for intersection tests)
}

How It Works

Initialization

1. Builds a successor graph from BranchLapConfig and lapConfigBranches
2. Each node in the graph stores its successors, branch info, and whether it's a final waypoint
3. Creates pathnode objects for each waypoint (used for intersection detection)
4. Calls race_marker.setupMarkers() with all waypoint positions
5. Initializes per-vehicle tracking data with wheel offsets for corner-based detection

Waypoint Detection (onPreRender)

1. Each frame, updates vehicle wheel corner positions using rotation and offset
2. For each vehicle, checks if any wheel corner line segment (previous→current) intersects a target waypoint's pathnode
3. Intersection uses the pathnode's intersectCorners method with time interpolation
4. On hit, triggers onScenarioVehicleTrigger which advances waypoint progress

Waypoint Progression

1. processWaypoint(vid) advances cur/next indices
2. Determines marker modes: default, next, branch, lap, final
3. Handles branching: when a waypoint has multiple successors, shows branch mode (yellow)
4. Handles laps: detects lap completion, fires onRaceLap hook
5. When final waypoint reached on final lap, calls scenario_scenarios.endRace()

Branching

1. BranchLapConfig can contain arrays (branch choices) instead of strings
2. activateWaypointBranch inserts a branch's waypoints into the vehicle's config at the current position
3. Successor graph pre-computes all possible paths through branches

Marker Mode Assignment

| M.addWaypointBranch | varies | Assigned as addWaypointBranch | | M.onUpdate | varies | Assigned as onUpdate |

Usage Example

-- Waypoints are initialized automatically by scenarios.lua during pre-running state
-- Get current progress for a vehicle:
local wpData = scenario_waypoints.getVehicleWaypointData(vehicleId)
if wpData then
  print("Current waypoint:", wpData.cur, "Lap:", wpData.lap)
end

-- Reset a vehicle to a specific waypoint:
scenario_waypoints.updateResetVehicleData(vehicleId, 3, 4)

Key Notes

• Uses wheel corner positions (not vehicle center) for precise checkpoint detection
• Time interpolation (tNorm) provides sub-frame accuracy for timing
• Branching is stored per-vehicle - different vehicles can take different branches
• disableWaypointTimes is auto-set when branches exist (comparisons become invalid)
• Rolling start uses a special initial state with cur = -2, next = -1
• The successor graph handles circular paths (last WP → first WP) for lap races
• Serialization converts vehicle ID keys to name keys for save/load

Additional Exports

• M.onDrawDebug - (undocumented)

See Also

• Scenario Bus Driver - Bus Route Scenario Logic - Related reference
• Scenario Damage Goal - Damage-Based Win/Fail Condition - Related reference
• Scenario Demolition Derby - Last Vehicle Moving Wins - Related reference
• Scenario System Guide - Guide