Rally Utility
Central utility module for the rally system. Provides constants, file path helpers, mission detection, notebook loading, corner call classification, string utilities, vehicle geometry helpers, and tim
Central utility module for the rally system. Provides constants, file path helpers, mission detection, notebook loading, corner call classification, string utilities, vehicle geometry helpers, and time formatting.
Public API - Constants
| Constant | Value | Description |
|------
| M.activeState_countdown | any | activeState_countdown |
| M.activeState_stageActive | any | activeState_stageActive |
| M.activeState_vehicleProximity | any | activeState_vehicleProximity |
| M.activeState_inactive | any | activeState_inactive |
| M.rallyLoop_flowgraph_color | any | rallyLoop_flowgraph_color |
| M.rally_flowgraph_color | any | rally_flowgraph_color |
| M.customDir | any | customDir |
| M.systemDir | any | systemDir |
| M.structuredDir | any | structuredDir |
| M.freeformDir | any | freeformDir |
| M.generatedPacenotesDir | any | generatedPacenotesDir |
| M.var_da | any | var_da |
| M.var_db | any | var_db |
| M.validPunctuation | any | validPunctuation |
| M.unknown_transcript_str | any | unknown_transcript_str |
| M.transcriptsExt | any | transcriptsExt |
| M.pacenotesMetadataBasename | any | pacenotesMetadataBasename |
| M.notebooksPath | any | notebooksPath |
| M.recceRecordSubdir | any | recceRecordSubdir |
| M.missionSettingsFname | any | missionSettingsFname |
| M.default_waypoint_intersect_radius | any | default_waypoint_intersect_radius |
| M.default_codriver_language | any | default_codriver_language |
| M.rallySettingsRoot | any | rallySettingsRoot |---
| M.formatTimeFromSeconds | (timeSecs, includeSeconds, includeTenths) | any | formatTimeFromSeconds |
| M.drawVehBB | (vehId) | nil | drawVehBB |
| M.drawVehLeadingPoint | (vehId, inside) | nil | drawVehLeadingPoint |
| M.arePointsEqualWithinThreshold | (point1, point2, threshold) | any | arePointsEqualWithinThreshold |
| M.translatedMissionNameFromId | (missionId) | any | translatedMissionNameFromId |
| M.translatedMissionName | (missionName) | any | translatedMissionName |
| M.getMissionName | (missionId) | any | getMissionName |
| M.getMissionSettingsFile | (missionDir) | any | getMissionSettingsFile |
| M.makePacenoteAudioFilename | (pacenoteHash) | string | makePacenoteAudioFilename |
| M.getCompositorMetadataFile | (compositorVoice) | any | getCompositorMetadataFile |
| M.getCompositorPacenoteFile | (compositorVoice, pacenoteHash) | any | getCompositorPacenoteFile |
| M.getCompositorFile | (compositorVoice, basename) | any | getCompositorFile |
| M.customRound | (dist, round_to) | any | customRound |
| M.useNote | (text) | any | useNote |
| M.stripBasename | (thepath) | any | stripBasename |
| M.pacenoteHashSha1 | (s) | any | pacenoteHashSha1 |
| M.finalDrivelineFile | (missionDir) | any | finalDrivelineFile |
| M.getAppropriateTextColor | (clr) | any | getAppropriateTextColor |
| M.missionReccePath | (missionDir, basename) | any | missionReccePath |
| M.missionRecceRecordDir | (missionDir) | any | missionRecceRecordDir |
| M.matchSearchPattern | (searchPattern, stringToMatch) | nil | matchSearchPattern |
| M.hasPunctuation | (last_char) | boolean | hasPunctuation |
| M.getTime | () | any | getTime |
| M.detectMissionManagerMissionId | () | nil | detectMissionManagerMissionId |
| M.detectMissionEditorMissionId | () | nil | detectMissionEditorMissionId |-|-------|-------------|
| missionRallyDir | "rally" | Rally subdirectory name |
| notebooksDir | "notebooks" | Notebooks subdirectory |
| recceDir | "recce" | Recce recordings subdirectory |
| defaultNotebookFname | "primary.notebook.json" | Default notebook filename |
| defaultCodriverName | "Sophia" | Default co-driver name |
| default_codriver_voice | "british_female" | Default TTS voice |
| autofill_blocker | "#" | Blocks autofill for a pacenote |
| autodist_internal_level1 | "<none>" | Internal placeholder |
| extRally | "gameplay_rally" | Rally extension name |
| extRallyLoop | "gameplay_rallyLoop" | Rally loop extension name |
| activeState_* | various | Rally loop states: inactive, vehicleProximity, stageActive, countdown |
Public API - Functions
| Function | Signature | Returns | Description |
|---|---|---|---|
detectMissionIdHelper | () | id, dir, err | Detect active mission from manager/editor/rally editor |
missionDirHelper | (missionId) | string? | Returns /gameplay/missions/<id> path |
loadNotebook | (fname) | notebook? | Load notebook from file path |
loadNotebookForMissionDir | (missionDir, basename) | notebook? | Load notebook relative to mission dir |
createNotebook | (fname) | notebook? | Create and save new empty notebook |
loadRacePath | (missionDir) | racePath, err | Load race.race.json from mission dir |
determineCornerCall | (angles, steering) | angle, str, pct | Classify steering angle into corner call |
getNotebookFullPath | (missionDir, basename) | string | Full path to notebook file |
drivelineFile | (missionDir) | string | Path to driveline.json |
cutsFile | (missionDir) | string | Path to cuts.json |
transcriptsFile | (missionDir) | string | Path to transcripts.json |
loadCornerAnglesFile | () | json, err | Load corner angle definitions |
calculateForwardNormal | (snap_pos, next_pos) | vec3 | Unit direction vector between two points |
normalizeName | (name) | string | Replace non-alphanumeric chars with _ |
trimString | (txt) | string | Strip leading/trailing whitespace |
getVehFrontCenter | (vehId) | vec3? | Center of vehicle front face from OOBB |
getVehFrontBottom | (vehId) | vec3? | Bottom center of vehicle front edge |
formatTime24Hour | (secs, incSec, incTenth) | table | Format seconds-of-day as 24h time |
formatTime12Hour | (secs, incSec, incTenth) | table | Format seconds-of-day as 12h time |
randomId | () | string | 8-char random SHA1 hash |
M.detectMissionEditorMissionId | () | nil | detectMissionEditorMissionId |
M.detectMissionManagerMissionId | () | nil | detectMissionManagerMissionId |
M.getTime | () | nil | getTime |
M.hasPunctuation | (last_char) | nil | hasPunctuation |
M.matchSearchPattern | (searchPattern, stringToMatch) | nil | matchSearchPattern |
M.missionRecceRecordDir | (missionDir) | nil | missionRecceRecordDir |
M.missionReccePath | (missionDir, basename) | nil | missionReccePath |
M.getAppropriateTextColor | (clr) | nil | getAppropriateTextColor |
M.finalDrivelineFile | (missionDir) | nil | finalDrivelineFile |
M.pacenoteHashSha1 | (s) | nil | pacenoteHashSha1 |
M.stripBasename | (thepath) | nil | stripBasename |
M.useNote | (text) | nil | useNote |
M.customRound | (dist, round_to) | nil | customRound |
M.getCompositorFile | (compositorVoice, basename) | nil | getCompositorFile |
M.getCompositorPacenoteFile | (compositorVoice, pacenoteHash) | nil | getCompositorPacenoteFile |
M.getCompositorMetadataFile | (compositorVoice) | nil | getCompositorMetadataFile |
M.makePacenoteAudioFilename | (pacenoteHash) | nil | makePacenoteAudioFilename |
M.getMissionSettingsFile | (missionDir) | nil | getMissionSettingsFile |
M.getMissionName | (missionId) | nil | getMissionName |
M.translatedMissionName | (missionName) | nil | translatedMissionName |
M.translatedMissionNameFromId | (missionId) | nil | translatedMissionNameFromId |
M.arePointsEqualWithinThreshold | (point1, point2, threshold) | nil | arePointsEqualWithinThreshold |
M.drawVehLeadingPoint | (vehId, inside) | nil | drawVehLeadingPoint |
M.drawVehBB | (vehId) | nil | drawVehBB |
M.formatTimeFromSeconds | (timeSecs, includeSeconds, includeTenths) | nil | formatTimeFromSeconds |
How It Works
- Mission detection cascades through three sources: mission manager (running game), rally editor, then mission editor
- Corner call maps absolute steering angle to named ranges (e.g., "3L", "5R", "C" for center) using angle definition data
- File paths follow a consistent structure:
/gameplay/missions/<id>/rally/... - Notebook loading deserializes JSON into a
rally/notebook/pathobject and sets adjacent note references
local rallyUtil = require('gameplay/rally/util')
-- Detect current mission
local missionId, missionDir, err = rallyUtil.detectMissionIdHelper()
if not err then
local notebook = rallyUtil.loadNotebookForMissionDir(missionDir, 'primary.notebook.json')
end
-- Classify a steering angle
local angle, callStr, pct = rallyUtil.determineCornerCall(sortedAngles, -45.0)
-- callStr = "3R", pct = 0.6Dependencies
gameplay/rally/notebook/path- notebook data structuregameplay/race/path- race path datagameplay_missions_missionManager- mission detectioneditor_rallyEditor/editor_missionEditor- editor mission detection
Module Variables
| Variable | Type | Description |
|---|---|---|
M.rallySettingsRoot | any | rallySettingsRoot |
M.default_codriver_language | any | default_codriver_language |
M.default_waypoint_intersect_radius | any | default_waypoint_intersect_radius |
M.missionSettingsFname | any | missionSettingsFname |
M.recceRecordSubdir | any | recceRecordSubdir |
M.notebooksPath | any | notebooksPath |
M.pacenotesMetadataBasename | any | pacenotesMetadataBasename |
M.transcriptsExt | any | transcriptsExt |
M.unknown_transcript_str | any | unknown_transcript_str |
M.validPunctuation | any | validPunctuation |
M.var_db | any | var_db |
M.var_da | any | var_da |
M.generatedPacenotesDir | any | generatedPacenotesDir |
M.freeformDir | any | freeformDir |
M.structuredDir | any | structuredDir |
M.systemDir | any | systemDir |
M.customDir | any | customDir |
M.rally_flowgraph_color | any | rally_flowgraph_color |
M.rallyLoop_flowgraph_color | any | rallyLoop_flowgraph_color |
M.activeState_inactive | any | activeState_inactive |
M.activeState_vehicleProximity | any | activeState_vehicleProximity |
M.activeState_stageActive | any | activeState_stageActive |
M.activeState_countdown | any | activeState_countdown |
M.autodist_internal_level1 | value | - |
M.autofill_blocker | value | - |
M.calculateForwardNormal | (snap_pos, next_pos) | - |
M.createNotebook | (fname) | - |
M.cutsFile | (missionDir) | - |
M.defaultCodriverName | value | - |
M.defaultNotebookFname | value | - |
M.default_codriver_voice | value | - |
M.detectMissionIdHelper | () | - |
M.determineCornerCall | (angles, steering) | - |
M.drivelineFile | (missionDir) | - |
M.extRally | value | - |
M.extRallyLoop | value | - |
M.formatTime12Hour | (timeSecs, includeSeconds, includeTenths) | - |
M.formatTime24Hour | (timeSecs, includeSeconds, includeTenths) | - |
M.getNotebookFullPath | (missionDir, basename) | - |
M.getVehFrontBottom | (vehId) | - |
M.getVehFrontCenter | (vehId) | - |
M.loadCornerAnglesFile | () | - |
M.loadNotebook | (notebookFname) | - |
M.loadNotebookForMissionDir | (missionDir, basename) | - |
M.loadRacePath | (missionDir) | - |
M.missionDirHelper | (missionId) | - |
M.missionRallyDir | value | - |
M.normalizeName | (name) | - |
M.notebooksDir | value | - |
M.randomId | () | - |
M.recceDir | value | - |
M.transcriptsFile | (missionDir) | - |
M.trimString | (txt) | - |
See Also
- Rally Audio Manager - Related reference
- Rally Camera Path Player - Related reference
- Rally Client - Related reference
- Gameplay Systems Guide - Guide
Traffic Exclusion Zones
Creates traffic exclusion zones around rally stage infrastructure (start positions, pathnodes) to prevent AI traffic from interfering with rally routes. Zones are applied to the navgraph via `map.setT
Rally Vehicle Capture
Class that records vehicle position, rotation, and steering data at distance-based intervals during a recce drive. Writes data to a JSONL driveline file.