Race Goals Manager

Central manager that initializes, validates, and dispatches race goal events to individual goal modules. Acts as the bridge between the scenario system and goal implementations.

Internal State

Public API

Goal Schema

Defines expected types for each goal's JSON fields:

Goal Loading

Goals are loaded as Lua modules with these search paths:

1. scenario/<goalName>.lua
2. scenario/<goalName>goal.lua

Each goal module must implement:

• init(scenario) - Parse and validate goal instances
• processState(scenario, state, stateData) - Handle events
• updateFinalStatus(scenario) - Report final results

How It Works

1. initialiseGoals iterates all scenario vehicles
2. For each vehicle with goals defined, creates goal instances with:
   • vehicleName, vId, id, value, status, startPos
3. Validates goal fields against goalSchema
4. Loads goal modules via require() and calls init() on each
5. Event hooks (onRaceTick, onRaceResult, etc.) dispatch to all loaded goals

Goal Instance Structure

{
  vehicleName = "scenario_player0",
  vId = 12345,              -- vehicle object ID
  id = "damage",            -- goal type name
  value = { damageLimit = 500, purpose = "fail" },
  status = {},              -- result tracking
  startPos = vec3(...)      -- vehicle position at init
}

Usage Examples

-- Goals are defined in scenario JSON under vehicles:
{
  "vehicles": {
    "scenario_player0": {
      "goal": {
        "damage": {"damageLimit": 500},
        "finishRace": {"mustWin": true}
      }
    },
    "*": {
      "goal": {
        "finishRace": {}
      }
    }
  }
}
-- The "*" wildcard applies goals to all vehicles without explicit goals

Key Notes

• Wildcard "*" vehicle goals apply to vehicles without explicit goal definitions
• Schema validation logs errors but doesn't prevent goal loading
• Supports localizedString type (either a string or {txt: "...", context: {...}})
• Goals can be arrays (unnamed) or objects (keyed by goal ID)
• Fires onRaceGoalsInitilised hook after all goals are loaded

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