Speeding Detector

Class-based speed monitoring system for rally road sections. Samples vehicle speed into a ring buffer, computes a rolling average, and applies stochastic speeding penalties with configurable probabili

Constructor

local SpeedingDetector = require('gameplay/rally/loop/speedingDetector')
local detector = SpeedingDetector(manager)

Public API

Method	Signature	Returns	Description
`init`	`(manager)`	`nil`	Initializes ring buffer, timers, and thresholds
`update`	`(dtSim, limitKph, strictMode?)`	`nil`	Main tick: samples speed, checks for penalties
`getCurrentSpeedKph`	`()`	`number\|nil`	Returns player vehicle speed in km/h
`addSample`	`(sample)`	`nil`	Writes speed sample to ring buffer
`getAverageSpeed`	`()`	`number\|nil`	Returns average of buffered samples
`stochasticPenalty`	`(maxSpeedOver, maxProbability)`	`triggered, probability`	Rolls for penalty based on speed over limit

Internals

Configuration

Parameter	Normal Mode	Strict Mode	Description
`maxSpeedOver`	30 kph	3 kph	Speed over limit for max probability
`maxProbability`	0.2 (20%)	0.7 (70%)	Max penalty probability
`bufferSize`	5	5	Ring buffer sample count
`sampleRate`	1.0s	1.0s	Seconds between samples
`penaltyRateLimit`	60.0s	60.0s	Minimum seconds between penalties

Stochastic Penalty Model

probability = min(speedOver / maxSpeedOver * maxProbability, maxProbability)
triggered = math.random() < probability

Linear scaling from 0% at the limit to maxProbability at maxSpeedOver km/h over. In normal mode: 15 km/h over → 10% chance. In strict mode: 1.5 km/h over → 35% chance.

Ring Buffer

Pre-allocated array with wrapping write index. No memory allocations during sampling:

self.data[self.writeIndex] = sample
self.writeIndex = (self.writeIndex % self.bufferSize) + 1

Penalty Data Structure

{
  averageSpeed = number,
  instantSpeed = number,
  speedLimit = number,
  speedOver = number,
  probability = number,
  strictMode = boolean
}

Debug ImGui Window

drawDebug() renders a full debug panel showing: current/average speed, penalty probability, rate limit timer, sample buffer contents, and strict mode indicator. Called optionally from update().

How It Works

update() is called each frame by the loop manager (only during road sections)
Every sampleRate seconds, reads vehicle speed and adds to ring buffer
After adding a sample, if rate limit has elapsed, runs stochastic penalty check
If penalty triggers, records penalty data and notifies manager via manager:recordSpeedingPenalty()
Strict mode (service parks) uses much tighter thresholds (3 kph over, 70% max probability)

Usage Example

local SpeedingDetector = require('gameplay/rally/loop/speedingDetector')
local detector = SpeedingDetector(loopManager)

-- Each frame during road sections
local strictMode = isInServicePark
detector:update(dtSim, speedLimitKph, strictMode)

Constructor

local SpeedingDetector = require('gameplay/rally/loop/speedingDetector')
local detector = SpeedingDetector(manager)

Public API

Method	Signature	Returns	Description
`init`	`(manager)`	`nil`	Initializes ring buffer, timers, and thresholds
`update`	`(dtSim, limitKph, strictMode?)`	`nil`	Main tick: samples speed, checks for penalties
`getCurrentSpeedKph`	`()`	`number\|nil`	Returns player vehicle speed in km/h
`addSample`	`(sample)`	`nil`	Writes speed sample to ring buffer
`getAverageSpeed`	`()`	`number\|nil`	Returns average of buffered samples
`stochasticPenalty`	`(maxSpeedOver, maxProbability)`	`triggered, probability`	Rolls for penalty based on speed over limit

Internals

Configuration

Parameter	Normal Mode	Strict Mode	Description
`maxSpeedOver`	30 kph	3 kph	Speed over limit for max probability
`maxProbability`	0.2 (20%)	0.7 (70%)	Max penalty probability
`bufferSize`	5	5	Ring buffer sample count
`sampleRate`	1.0s	1.0s	Seconds between samples
`penaltyRateLimit`	60.0s	60.0s	Minimum seconds between penalties

Stochastic Penalty Model

probability = min(speedOver / maxSpeedOver * maxProbability, maxProbability)
triggered = math.random() < probability

Linear scaling from 0% at the limit to maxProbability at maxSpeedOver km/h over. In normal mode: 15 km/h over → 10% chance. In strict mode: 1.5 km/h over → 35% chance.

Ring Buffer

Pre-allocated array with wrapping write index. No memory allocations during sampling:

self.data[self.writeIndex] = sample
self.writeIndex = (self.writeIndex % self.bufferSize) + 1

Penalty Data Structure

{
  averageSpeed = number,
  instantSpeed = number,
  speedLimit = number,
  speedOver = number,
  probability = number,
  strictMode = boolean
}

Debug ImGui Window

drawDebug() renders a full debug panel showing: current/average speed, penalty probability, rate limit timer, sample buffer contents, and strict mode indicator. Called optionally from update().

How It Works

update() is called each frame by the loop manager (only during road sections)
Every sampleRate seconds, reads vehicle speed and adds to ring buffer
After adding a sample, if rate limit has elapsed, runs stochastic penalty check
If penalty triggers, records penalty data and notifies manager via manager:recordSpeedingPenalty()
Strict mode (service parks) uses much tighter thresholds (3 kph over, 70% max probability)

Usage Example

local SpeedingDetector = require('gameplay/rally/loop/speedingDetector')
local detector = SpeedingDetector(loopManager)

-- Each frame during road sections
local strictMode = isInServicePark
detector:update(dtSim, speedLimitKph, strictMode)

Speeding Detector

Constructor

Public API

Internals

Configuration

Stochastic Penalty Model

Ring Buffer

Penalty Data Structure

Debug ImGui Window

How It Works

Usage Example

See Also

On this page

Speeding Detector

Constructor

Public API

Internals

Configuration

Stochastic Penalty Model

Ring Buffer

Penalty Data Structure

Debug ImGui Window

How It Works

Usage Example

See Also

On this page