Distance Goal

A scenario goal that monitors the distance between two vehicles and triggers win or fail when distance thresholds are exceeded.

Internal State

Public API

Goal JSON Schema

{
  "goal": {
    "distance": {
      "target": "ai_vehicle_1",
      "maxDistance": 50,
      "minDistance": 5,
      "distanceEnable": 30,
      "purpose": "fail",
      "msg": "scenarios.myScenario.tooFar"
    }
  }
}

How It Works

1. init filters goals for id == "distance", validates numeric types
2. Each onRaceTick, calculates distance between the goal vehicle and target
3. If distanceEnable is set, waits until player is within that range before checking
4. Once enabled, checks maxDistance and minDistance thresholds
5. If exceeded, calls showMsg which finishes the scenario as win or fail
6. Also supports scenario.targetName for scene-object distance checks (legacy)

Usage Examples

-- In scenario JSON: fail if player gets more than 50m from escort target
{
  "vehicles": {
    "scenario_player0": {
      "goal": {
        "distance": {
          "target": "escort_vehicle",
          "maxDistance": 50,
          "purpose": "fail",
          "msg": "scenarios.escort.tooFar"
        }
      }
    }
  }
}

-- Chase scenario: enable distance check only after getting close
{
  "distance": {
    "target": "chase_target",
    "distanceEnable": 30,
    "maxDistance": 100,
    "purpose": "fail"
  }
}

Key Notes

• Uses helper.getVehicleByName to find the target vehicle object
• distanceEnable creates a "proximity activation" - goal inactive until close enough
• Both maxDistance and minDistance can be used together for a distance band
• Falls back to helper.getDistanceBetweenSceneObjects for legacy scene object tracking

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