Rally Event Log

Class-based event logger for rally loop gameplay. Records all events (timecards, penalties, recoveries, flips) and maintains aggregated totals. Events are grouped by `eventGroup` for per-stage queryin

Class-based event logger for rally loop gameplay. Records all events (timecards, penalties, recoveries, flips) and maintains aggregated totals. Events are grouped by eventGroup for per-stage querying.

Constructor

local RallyEventLog = require('gameplay/rally/loop/rallyEventLog')
local log = RallyEventLog()

Public API

Method	Signature	Returns	Description
`addItem`	`(event, timestamp, type, data)`	`nil`	Logs an event item; recalculates aggregates
`getItemsByEventGroup`	`(eventGroup)`	`table`	Returns items for a specific event group
`getAllItems`	`()`	`table`	Returns all logged items
`getItemsByType`	`(type)`	`table`	Filters items by type string
`getStageTimes`	`()`	`table`	Returns items that have `stageTimeSecs` in their data
`getTotalPenalty`	`()`	`number`	Sum of all penalties (time_control + recovery + flip)
`getTotalStageTime`	`()`	`number`	Sum of all stage times
`getTotalTime`	`()`	`number`	Stage time + penalty total
`getPenaltySummary`	`()`	`table`	Grouped penalty breakdown by eventGroup and penaltyType
`clear`	`()`	`nil`	Removes all logged items

Internals

Item Structure

{
  timestamp = number,       -- rally epoch time
  eventId = string,         -- e.g., "TC1", "SS1_start"
  eventGroup = string,      -- e.g., "SS1", "TC1", "SERVICE"
  type = string,            -- "timecard", "penalty", "recovery", "flip"
  data = table              -- type-specific payload
}

Aggregation

On every addItem, the log recalculates:

totalPenalty: sums penalty.data.amount + recovery.data.penaltyAmount + flip.data.penaltyAmount
totalStageTime: sums data.stageTimeSecs from any item type
totalTime: stageTime + penalty

Penalty Summary

getPenaltySummary() returns a structured breakdown:

{
  totalPenalty = number,
  groups = {                -- ordered by first occurrence
    {
      eventGroup = "TC1",
      totalPenalty = number,
      penalties = {         -- sorted alphabetically by type
        { type = "time_control_late", count = 1, amount = 30 },
        { type = "recovery", count = 2, amount = 240 }
      }
    }
  }
}

How It Works

Events are added via addItem(event, timestamp, type, data)
Each item is stored in a flat array and indexed by eventGroup
Aggregates are recalculated on every insert (denormalized for performance)
Penalty types recognized: penalty (with amount), recovery (with penaltyAmount), flip (with penaltyAmount)
Stage times come from any item with data.stageTimeSecs

Usage Example

local RallyEventLog = require('gameplay/rally/loop/rallyEventLog')
local eventLog = RallyEventLog()

-- Log a time control penalty
eventLog:addItem(event, epochTime, 'penalty', {
  penaltyType = 'time_control_late',
  amount = 30,
  checkpointLabel = 'TC2'
})

-- Query totals
local totalTime = eventLog:getTotalTime()
local summary = eventLog:getPenaltySummary()

Constructor

local RallyEventLog = require('gameplay/rally/loop/rallyEventLog')
local log = RallyEventLog()

Public API

Method	Signature	Returns	Description
`addItem`	`(event, timestamp, type, data)`	`nil`	Logs an event item; recalculates aggregates
`getItemsByEventGroup`	`(eventGroup)`	`table`	Returns items for a specific event group
`getAllItems`	`()`	`table`	Returns all logged items
`getItemsByType`	`(type)`	`table`	Filters items by type string
`getStageTimes`	`()`	`table`	Returns items that have `stageTimeSecs` in their data
`getTotalPenalty`	`()`	`number`	Sum of all penalties (time_control + recovery + flip)
`getTotalStageTime`	`()`	`number`	Sum of all stage times
`getTotalTime`	`()`	`number`	Stage time + penalty total
`getPenaltySummary`	`()`	`table`	Grouped penalty breakdown by eventGroup and penaltyType
`clear`	`()`	`nil`	Removes all logged items

Internals

Item Structure

{
  timestamp = number,       -- rally epoch time
  eventId = string,         -- e.g., "TC1", "SS1_start"
  eventGroup = string,      -- e.g., "SS1", "TC1", "SERVICE"
  type = string,            -- "timecard", "penalty", "recovery", "flip"
  data = table              -- type-specific payload
}

Aggregation

On every addItem, the log recalculates:

totalPenalty: sums penalty.data.amount + recovery.data.penaltyAmount + flip.data.penaltyAmount
totalStageTime: sums data.stageTimeSecs from any item type
totalTime: stageTime + penalty

Penalty Summary

getPenaltySummary() returns a structured breakdown:

{
  totalPenalty = number,
  groups = {                -- ordered by first occurrence
    {
      eventGroup = "TC1",
      totalPenalty = number,
      penalties = {         -- sorted alphabetically by type
        { type = "time_control_late", count = 1, amount = 30 },
        { type = "recovery", count = 2, amount = 240 }
      }
    }
  }
}

How It Works

Events are added via addItem(event, timestamp, type, data)
Each item is stored in a flat array and indexed by eventGroup
Aggregates are recalculated on every insert (denormalized for performance)
Penalty types recognized: penalty (with amount), recovery (with penaltyAmount), flip (with penaltyAmount)
Stage times come from any item with data.stageTimeSecs

Usage Example

local RallyEventLog = require('gameplay/rally/loop/rallyEventLog')
local eventLog = RallyEventLog()

-- Log a time control penalty
eventLog:addItem(event, epochTime, 'penalty', {
  penaltyType = 'time_control_late',
  amount = 30,
  checkpointLabel = 'TC2'
})

-- Query totals
local totalTime = eventLog:getTotalTime()
local summary = eventLog:getPenaltySummary()

Rally Event Log

Constructor

Public API

Internals

Item Structure

Aggregation

Penalty Summary

How It Works

Usage Example

See Also

On this page

Rally Event Log

Constructor

Public API

Internals

Item Structure

Aggregation

Penalty Summary

How It Works

Usage Example

See Also

On this page