Time Limit Goal

A scenario goal that fails the scenario if the player exceeds a maximum time. Supports countdown warnings and wait time after the limit.

Internal State

Public API (Exports)

Goal JSON Schema

{
  "goal": {
    "timeLimit": {
      "maxTime": 60,
      "waitTime": 0,
      "countdown": 10,
      "msg": "scenarios.myScenario.timeFail"
    }
  }
}

How It Works

1. init filters goals for id == "timeLimit", validates that maxTime and waitTime are numbers
2. Processing states:
   • onRaceTick: If countdown is set and time remaining < countdown seconds, shows decreasing flash messages ("3", "2", "1")
   • After maxTime + waitTime has passed, calls failedGoal() which sets status to "failed" and calls scenario_scenarios.finish()
   • onRaceResult: If finalTime > maxTime, also triggers failure
3. Countdown tracking uses instance.wait to prevent duplicate messages per second

Usage Examples

-- In scenario JSON: fail if race takes longer than 120 seconds
{
  "vehicles": {
    "scenario_player0": {
      "goal": {
        "timeLimit": {
          "maxTime": 120,
          "waitTime": 0
        }
      }
    }
  }
}

-- With 10-second countdown warning:
{
  "timeLimit": {
    "maxTime": 60,
    "waitTime": 2,
    "countdown": 10,
    "msg": "Time's up!"
  }
}

Key Notes

• Both maxTime and waitTime must be numbers (validated in init)
• The actual fail triggers at maxTime + waitTime, not just maxTime
• countdown shows flash messages with helper.flashUiMessage at each second
• If countdown is not a number, the goal is rejected with an error log
• Also checks onRaceResult for post-race validation (e.g., if race finishes exactly at limit)
• The passed status is only set in onRaceResult when finalTime <= maxTime

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