Vehicle Performance

Reference for `gameplay_vehiclePerformance`, which calculates a Performance Index (PI) from drag test data and assigns vehicles to performance classes (D through X).

Reference for gameplay_vehiclePerformance, which calculates a Performance Index (PI) from drag test data and assigns vehicles to performance classes (D through X).

Module Exports (M)

Function	Signature	Description
`getClassFromData`	`(testData)` → table\|nil	Classifies from raw drag test data
`getClassFromVehId`	`(vehId)` → table\|nil	Classifies a spawned vehicle by ID
`getClassFromConfig`	`(model, configName)` → table\|nil	Classifies from model/config without spawning
`getAggregateScores`	`(testData)` → table\|nil	Returns detailed scoring breakdown

Vehicle Classes

Class	Min PI	Description
X	101	Modified
S	86	Super Sports
A	66	High Performance
B	41	Sports
C	21	Standard
D	0	Economy/Utility

Internals

Performance Index Calculation

The PI is a weighted sum of drag test metrics, each transformed through a linear formula:

weightedValue = max(0, bias + testValue × multiplier)

Metric	Bias	Multiplier	Description
`time_60`	19.61	-8.29	0–60 ft time
`time_330`	9.68	-0.97	0–330 ft time
`time_1000`	15.00	-0.50	0–1000 ft time
`time_1_8`	22.41	-2.04	1/8 mile time
`time_1_4`	29.14	-1.62	1/4 mile time
`time_0_60`	21.43	-1.43	0–60 mph time
`velAt_1_8`	-8.00	0.53	Speed at 1/8 mile
`velAt_1_4`	-6.00	0.40	Speed at 1/4 mile
`brakingG`	-3.57	7.14	Braking G-force

Negative multipliers mean faster times → higher scores. Positive multipliers mean higher speeds/G → higher scores.

Aggregate Scores

getAggregateScores() returns percentage-based scores normalized to a reference vehicle (Scintilla drag configuration):

Score	Formula
`powerScore`	`(power / basePower) × 100`
`powerToWeightScore`	`(P/W ratio / base P/W) × 100`
`timeTo60Score`	`(baseTime / testTime) × 100`
`quarterMileScore`	`(baseTime / testTime) × 100`
`speedProgressionScore`	`(deltaSpeed / baseDeltaSpeed) × 100`
`brakingGForceScore`	`(testG / baseG) × 100`
`time0To60Score`	`(baseTime / testTime) × 100`
`M.getAggregateScores`	`(testData)`
`M.getClassFromConfig`	`(model, configName)`
`M.getClassFromData`	`(testData)`
`M.getClassFromVehId`	`(vehId)`

Base Reference Data (Scintilla)

{
  time_60 = 1.833, time_330 = 4.067, time_1_8 = 5.667,
  time_1_4 = 8.134, velAt_1_4 = 90.25, velAt_1_8 = 70.95,
  time_0_60 = 2.367, brakingG = 1.417,
  power = 1395241,  -- watts (~1870 hp)
  torque = 1740, weight = 1280
}

How It Works

Extract drag test data from core_vehicles.getVehicleDetails() or raw data
Apply linear weight to each metric using bias/multiplier pairs
Sum all weighted values to get the Performance Index
Match PI against class thresholds (descending) to find the class

Usage Example

-- Classify the player's current vehicle
local result = gameplay_vehiclePerformance.getClassFromVehId(be:getPlayerVehicleID(0))
if result then
  log("I", "", string.format("Class %s (PI: %0.1f) - %s",
    result.class.name, result.performanceIndex, result.class.description))
end

-- Classify without spawning
local result = gameplay_vehiclePerformance.getClassFromConfig("vivace", "Sport_S")
if result then
  log("I", "", "Class: " .. result.class.name)
end

-- Get detailed scores
local scores = gameplay_vehiclePerformance.getAggregateScores(testData)
log("I", "", "Power score: " .. scores.powerScore)

Module Exports (M)

Function	Signature	Description
`getClassFromData`	`(testData)` → table\|nil	Classifies from raw drag test data
`getClassFromVehId`	`(vehId)` → table\|nil	Classifies a spawned vehicle by ID
`getClassFromConfig`	`(model, configName)` → table\|nil	Classifies from model/config without spawning
`getAggregateScores`	`(testData)` → table\|nil	Returns detailed scoring breakdown

Vehicle Classes

Class	Min PI	Description
X	101	Modified
S	86	Super Sports
A	66	High Performance
B	41	Sports
C	21	Standard
D	0	Economy/Utility

Internals

Performance Index Calculation

The PI is a weighted sum of drag test metrics, each transformed through a linear formula:

weightedValue = max(0, bias + testValue × multiplier)

Metric	Bias	Multiplier	Description
`time_60`	19.61	-8.29	0–60 ft time
`time_330`	9.68	-0.97	0–330 ft time
`time_1000`	15.00	-0.50	0–1000 ft time
`time_1_8`	22.41	-2.04	1/8 mile time
`time_1_4`	29.14	-1.62	1/4 mile time
`time_0_60`	21.43	-1.43	0–60 mph time
`velAt_1_8`	-8.00	0.53	Speed at 1/8 mile
`velAt_1_4`	-6.00	0.40	Speed at 1/4 mile
`brakingG`	-3.57	7.14	Braking G-force

Negative multipliers mean faster times → higher scores. Positive multipliers mean higher speeds/G → higher scores.

Aggregate Scores

getAggregateScores() returns percentage-based scores normalized to a reference vehicle (Scintilla drag configuration):

Score	Formula
`powerScore`	`(power / basePower) × 100`
`powerToWeightScore`	`(P/W ratio / base P/W) × 100`
`timeTo60Score`	`(baseTime / testTime) × 100`
`quarterMileScore`	`(baseTime / testTime) × 100`
`speedProgressionScore`	`(deltaSpeed / baseDeltaSpeed) × 100`
`brakingGForceScore`	`(testG / baseG) × 100`
`time0To60Score`	`(baseTime / testTime) × 100`
`M.getAggregateScores`	`(testData)`
`M.getClassFromConfig`	`(model, configName)`
`M.getClassFromData`	`(testData)`
`M.getClassFromVehId`	`(vehId)`

Base Reference Data (Scintilla)

{
  time_60 = 1.833, time_330 = 4.067, time_1_8 = 5.667,
  time_1_4 = 8.134, velAt_1_4 = 90.25, velAt_1_8 = 70.95,
  time_0_60 = 2.367, brakingG = 1.417,
  power = 1395241,  -- watts (~1870 hp)
  torque = 1740, weight = 1280
}

How It Works

Extract drag test data from core_vehicles.getVehicleDetails() or raw data
Apply linear weight to each metric using bias/multiplier pairs
Sum all weighted values to get the Performance Index
Match PI against class thresholds (descending) to find the class

Usage Example

-- Classify the player's current vehicle
local result = gameplay_vehiclePerformance.getClassFromVehId(be:getPlayerVehicleID(0))
if result then
  log("I", "", string.format("Class %s (PI: %0.1f) - %s",
    result.class.name, result.performanceIndex, result.class.description))
end

-- Classify without spawning
local result = gameplay_vehiclePerformance.getClassFromConfig("vivace", "Sport_S")
if result then
  log("I", "", "Class: " .. result.class.name)
end

-- Get detailed scores
local scores = gameplay_vehiclePerformance.getAggregateScores(testData)
log("I", "", "Power score: " .. scores.powerScore)

Vehicle Performance

Module Exports (M)

Vehicle Classes

Internals

Performance Index Calculation

Aggregate Scores

Base Reference Data (Scintilla)

How It Works

Usage Example

See Also

On this page

Vehicle Performance

Module Exports (M)

Vehicle Classes

Internals

Performance Index Calculation

Aggregate Scores

Base Reference Data (Scintilla)

How It Works

Usage Example

See Also

On this page