Speed Goal

A scenario goal that monitors vehicle speed and triggers win or fail if the vehicle stays outside a speed range for too long. Supports min/max speed, timeout countdown, waypoint-specific checks, and delayed activation.

Internal State

Public API (Exports)

Goal JSON Schema

{
  "goal": {
    "speed": {
      "minSpeed": 10,
      "maxSpeed": 50,
      "maxTimeout": 5,
      "delay": 3,
      "purpose": "fail",
      "wayPointNum": [3, 5, 8],
      "msg": "scenarios.myScenario.tooSlow"
    }
  }
}

How It Works

1. init filters goals for id == "speed", validates types, defaults purpose to "fail"
2. Each onRaceTick (0.25s interval):
   • If delay is set and timer hasn't passed it, skips check
   • If wayPointNum is set, only checks at those specific waypoint indices
   • Reads vehicle velocity from map.objects via fobjData.vel:length()
3. If speed is outside [minSpeed, maxSpeed] range:
   • Increments instance.Timeout by tick time
   • Shows countdown flash messages each second
4. If speed returns to valid range, resets timeout to 0
5. When timeout exceeds maxTimeout, calls showMsg which:
   • Sets result to "failed" or "passed" based on purpose
   • Calls scenario_scenarios.finish() with formatted time string

Usage Examples

-- In scenario JSON: fail if speed drops below 15 m/s for 5 seconds
{
  "vehicles": {
    "scenario_player0": {
      "goal": {
        "speed": {
          "minSpeed": 15,
          "maxTimeout": 5,
          "purpose": "fail"
        }
      }
    }
  }
}

-- Check speed only at waypoints 2 and 4:
{
  "speed": {
    "maxSpeed": 30,
    "maxTimeout": 3,
    "wayPointNum": [2, 4],
    "purpose": "fail"
  }
}

Key Notes

• maxSpeed of 0 is explicitly rejected (logged as error)
• Speed is measured in m/s from the map object tracker
• If map tracking is missing, re-enables it via mapmgr.enableTracking
• Countdown messages use helper.flashUiMessage with 0.5s duration
• The win purpose is useful for speed challenge scenarios
• Timeout resets completely when speed returns to valid range

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