Rally Loop Penalties

Calculates time control penalties for rally loop events. Determines if a driver arrived early, on-time, or late at a checkpoint and computes penalty amounts (+10 per minute deviation).

Public API

Constants

Internals

getTimingStatus Return Table

{
  status = "early"|"on-time"|"late",
  totalPenalty = number,      -- sum of all penalty amounts
  hasPenalty = boolean,
  penalties = {               -- array of structured penalty objects
    {
      type = "time_control_early"|"time_control_late",
      amount = number,
      data = {
        minutesEarly/minutesLate = number,
        actualMinute = number,
        scheduledMinute = number
      }
    }
  }
}

Timing Logic

• Converts both times to integer minutes via math.floor(time / 60)
• Early: actualMinute < scheduledMinute → penalty = |diff| × 10
• On-time: actualMinute == scheduledMinute → no penalty
• Late: actualMinute > scheduledMinute → penalty = diff × 10
• If either time is nil, returns "on-time" with zero penalty

How It Works

1. Both actual and scheduled times are epoch seconds
2. Integer minute comparison determines early/on-time/late
3. Penalty is 10 seconds per minute of deviation (both early and late)
4. Structured penalty data includes i18n-friendly fields for UI display
5. Constants provide fixed penalties for reset (2 min) and flip (15s) events

Usage Example

local Penalties = require('gameplay/rally/loop/penalties')

-- Check arrival timing
local result = Penalties.getTimingStatus(actualEpochSecs, scheduledEpochSecs)
if result.hasPenalty then
  log('W', '', 'Penalty: ' .. result.totalPenalty .. ' (' .. result.status .. ')')
end

-- Access penalty constants
local resetPenalty = Penalties.resetPenaltySeconds  -- 120
local flipPenalty = Penalties.flipPenaltySeconds     -- 15

See Also

• Rally Attempts - Related reference
• Rally Event Log - Related reference
• Rally Loop Manager - Related reference
• Gameplay Systems Guide - Guide