Rally Loop Manager

Core manager class for rally loop gameplay. Orchestrates the entire rally event: mission sequencing, schedule calculation, wall clock / epoch time management, time control penalties, timecard recording, speeding detection, and UI data streaming. This is the largest and most central rally loop module.

Constructor

local C = require('gameplay/rally/loop/rallyLoopManager')
-- Instantiated internally; receives (missionId, missionDir)

Public API (Key Methods)

Lifecycle & State

Method	Signature	Returns	Description
`init`	`(missionId, missionDir)`	`nil`	Full initialization: settings, schedule, events, clock
`onUpdate`	`(dtReal, dtSim, dtRaw)`	`nil`	Per-frame tick: advances clock, updates penalty keepers, speeding detector
`onGuiUpdate`	`(dtReal, dtSim, dtRaw)`	`nil`	GUI update tick (lightweight)

Mission Sequencing

Method	Signature	Returns	Description
`getCurrentMissionId`	`()`	`string\|nil`	Current mission in the sequence
`getNextMissionId`	`()`	`string\|nil`	Advances index, returns next mission ID
`startNextMission`	`()`	`boolean`	Transfers execution to next mission via `startFromWithinMission`
`restartRallyLoop`	`()`	`nil`	Restarts the entire rally loop from the beginning
`getRallyLoopMissionId`	`()`	`string`	Returns the parent loop mission ID

Clock & Time

Method	Signature	Returns	Description
`getEpochTime`	`()`	`number`	Rally epoch time (0 = rally start, negative = before start)
`getWallClockTimeSecs`	`()`	`number`	Absolute time of day in seconds
`getWallClockDay`	`()`	`number`	Current day number (1-based)
`setClockPaused`	`(paused)`	`nil`	Pauses/resumes rally clock
`adjustClock`	`(seconds)`	`nil`	Manually offsets clock

Schedule & Events

Method	Signature	Returns	Description
`calculateSchedule`	`(includeDebugData?)`	`nil`	Builds full schedule from mission sequence
`getSchedule`	`()`	`table`	Returns schedule array
`getEvents`	`()`	`table`	Returns events array
`recordTimeCardEntry`	`(entryName, stageTimeSecs?)`	`boolean`	Records a checkpoint arrival with penalty calculation
`advanceToNextEvent`	`()`	`nil`	Moves to next event in sequence
`calculateStartLineTime`	`(tcArrivalTime)`	`number`	Smart rescheduling of SS start based on TC arrival

Penalties & Speeding

Method	Signature	Returns	Description
`getTotalPenalty`	`()`	`number`	Total penalty seconds from event log
`getTotalTime`	`()`	`number`	Total rally time (stage + penalty)
`shouldPenalizeSpeeding`	`()`	`boolean`	True when NOT in a special stage
`isInRoadSection`	`()`	`boolean`	True if current mission is a liaison road section
`isInSpecialStage`	`()`	`boolean`	True if current mission is a competitive SS

Formatting

Method	Signature	Returns	Description
`formatStageTime`	`(seconds)`	`string`	Dynamic format: `S.T`, `M:SS.T`, or `H:MM:SS.T`
`formatDuration`	`(seconds)`	`string`	`M:SS` format
`formatTimeFromSecondsString`	`(secs, incSec, incTenth)`	`string`	Wall clock formatted string (12h or 24h)

Internals

Mission Sequence

Built from flowgraph variables in this order:

serviceOut (leaving service park)
For each stage 1-4: stage{n}_rallyRoadSection → stage{n}_rallyStage
return_rallyRoadSection (return liaison)
serviceIn (arriving at service park)

Schedule Calculation

Rally start time: environment time rounded to next minute + configurable delay
Road sections: time allocation × 2.0 buffer, rounded to next minute
Special stages: TC→start line delay (1 min planned), stage time × 1.0 buffer
All times stored in rally epoch (0 = rally start)

Event Types

Type	Description
`tc`	Time control checkpoint (penalizable)
`ss_start`	Special stage start line
`ss_stop`	Special stage stop control
`service_in`	Service park arrival

Data Streaming

Updates in-place tables (streamData, rallyClockData, scheduleData, timecardData) for GC-efficient UI streaming via guihooks.trigger.

Key Dependencies

RallyEventLog - event logging
Penalties - time control penalty calculation
RoadSectionPenaltyKeeper - route deviation penalties
SpeedingDetector - speed limit enforcement
ScheduleUtils - time rounding utilities
RallySettings - NGRC mode detection

How It Works

Init: Reads flowgraph variables → builds mission sequence → calculates full schedule with times → initializes clock in rally epoch
Runtime: Clock advances each frame; penalty keepers and speeding detector update; UI data tables refreshed in-place
Checkpoint: recordTimeCardEntry validates event match → calculates timing penalty → logs to event log → checks for start line rescheduling → updates timecard UI
Mission transfer: startNextMission advances sequence index and calls startFromWithinMission for seamless transitions

Usage Example

-- Accessed via the rally loop flowgraph; not typically called directly
local mgr = rallyLoopManager  -- class instance

-- Check current state
if mgr:isInSpecialStage() then
  -- competitive stage, no speed limits
end

-- Record checkpoint arrival
mgr:recordTimeCardEntry("tc_waypoint_name", stageTimeSecs)

-- Get formatted rally time
local totalTime = mgr:formatStageTime(mgr:getTotalTime())

Constructor

local C = require('gameplay/rally/loop/rallyLoopManager')
-- Instantiated internally; receives (missionId, missionDir)

Public API (Key Methods)

Lifecycle & State

Method	Signature	Returns	Description
`init`	`(missionId, missionDir)`	`nil`	Full initialization: settings, schedule, events, clock
`onUpdate`	`(dtReal, dtSim, dtRaw)`	`nil`	Per-frame tick: advances clock, updates penalty keepers, speeding detector
`onGuiUpdate`	`(dtReal, dtSim, dtRaw)`	`nil`	GUI update tick (lightweight)

Mission Sequencing

Method	Signature	Returns	Description
`getCurrentMissionId`	`()`	`string\|nil`	Current mission in the sequence
`getNextMissionId`	`()`	`string\|nil`	Advances index, returns next mission ID
`startNextMission`	`()`	`boolean`	Transfers execution to next mission via `startFromWithinMission`
`restartRallyLoop`	`()`	`nil`	Restarts the entire rally loop from the beginning
`getRallyLoopMissionId`	`()`	`string`	Returns the parent loop mission ID

Clock & Time

Method	Signature	Returns	Description
`getEpochTime`	`()`	`number`	Rally epoch time (0 = rally start, negative = before start)
`getWallClockTimeSecs`	`()`	`number`	Absolute time of day in seconds
`getWallClockDay`	`()`	`number`	Current day number (1-based)
`setClockPaused`	`(paused)`	`nil`	Pauses/resumes rally clock
`adjustClock`	`(seconds)`	`nil`	Manually offsets clock

Schedule & Events

Method	Signature	Returns	Description
`calculateSchedule`	`(includeDebugData?)`	`nil`	Builds full schedule from mission sequence
`getSchedule`	`()`	`table`	Returns schedule array
`getEvents`	`()`	`table`	Returns events array
`recordTimeCardEntry`	`(entryName, stageTimeSecs?)`	`boolean`	Records a checkpoint arrival with penalty calculation
`advanceToNextEvent`	`()`	`nil`	Moves to next event in sequence
`calculateStartLineTime`	`(tcArrivalTime)`	`number`	Smart rescheduling of SS start based on TC arrival

Penalties & Speeding

Method	Signature	Returns	Description
`getTotalPenalty`	`()`	`number`	Total penalty seconds from event log
`getTotalTime`	`()`	`number`	Total rally time (stage + penalty)
`shouldPenalizeSpeeding`	`()`	`boolean`	True when NOT in a special stage
`isInRoadSection`	`()`	`boolean`	True if current mission is a liaison road section
`isInSpecialStage`	`()`	`boolean`	True if current mission is a competitive SS

Formatting

Method	Signature	Returns	Description
`formatStageTime`	`(seconds)`	`string`	Dynamic format: `S.T`, `M:SS.T`, or `H:MM:SS.T`
`formatDuration`	`(seconds)`	`string`	`M:SS` format
`formatTimeFromSecondsString`	`(secs, incSec, incTenth)`	`string`	Wall clock formatted string (12h or 24h)

Internals

Mission Sequence

Built from flowgraph variables in this order:

serviceOut (leaving service park)
For each stage 1-4: stage{n}_rallyRoadSection → stage{n}_rallyStage
return_rallyRoadSection (return liaison)
serviceIn (arriving at service park)

Schedule Calculation

Rally start time: environment time rounded to next minute + configurable delay
Road sections: time allocation × 2.0 buffer, rounded to next minute
Special stages: TC→start line delay (1 min planned), stage time × 1.0 buffer
All times stored in rally epoch (0 = rally start)

Event Types

Type	Description
`tc`	Time control checkpoint (penalizable)
`ss_start`	Special stage start line
`ss_stop`	Special stage stop control
`service_in`	Service park arrival

Data Streaming

Updates in-place tables (streamData, rallyClockData, scheduleData, timecardData) for GC-efficient UI streaming via guihooks.trigger.

Key Dependencies

RallyEventLog - event logging
Penalties - time control penalty calculation
RoadSectionPenaltyKeeper - route deviation penalties
SpeedingDetector - speed limit enforcement
ScheduleUtils - time rounding utilities
RallySettings - NGRC mode detection

How It Works

Init: Reads flowgraph variables → builds mission sequence → calculates full schedule with times → initializes clock in rally epoch
Runtime: Clock advances each frame; penalty keepers and speeding detector update; UI data tables refreshed in-place
Checkpoint: recordTimeCardEntry validates event match → calculates timing penalty → logs to event log → checks for start line rescheduling → updates timecard UI
Mission transfer: startNextMission advances sequence index and calls startFromWithinMission for seamless transitions

Usage Example

-- Accessed via the rally loop flowgraph; not typically called directly
local mgr = rallyLoopManager  -- class instance

-- Check current state
if mgr:isInSpecialStage() then
  -- competitive stage, no speed limits
end

-- Record checkpoint arrival
mgr:recordTimeCardEntry("tc_waypoint_name", stageTimeSecs)

-- Get formatted rally time
local totalTime = mgr:formatStageTime(mgr:getTotalTime())

Rally Loop Manager

Constructor

Public API (Key Methods)

Lifecycle & State

Mission Sequencing

Clock & Time

Schedule & Events

Penalties & Speeding

Formatting

Internals

Mission Sequence

Schedule Calculation

Event Types

Data Streaming

Key Dependencies

How It Works

Usage Example

See Also

On this page

Rally Loop Manager

Constructor

Public API (Key Methods)

Lifecycle & State

Mission Sequencing

Clock & Time

Schedule & Events

Penalties & Speeding

Formatting

Internals

Mission Sequence

Schedule Calculation

Event Types

Data Streaming

Key Dependencies

How It Works

Usage Example

See Also

On this page