Torque Valley: Driving, Drift and Crash Sandbox
README.md
driveProgress
Driver progression for driving games: XP and levels earned by how you drive,
plus challenges, in five styles switched by one setting. It reads only the
driving contract's shared values (car.kmh, car.impactCount,
car.impactSpeed, car.damage, see torqueCars.package/CONTRACT.md) and the
chassis' own motion, so it works with any car that writes them.
What scores:
- Top speed: milestones (every 10–40 km/h above a floor, per style).
- Drifts: the rear sliding out (slip angle between where the car points and where it travels) at speed. Slides close together chain into a combo that multiplies; a hard crash can wipe a running chain.
- Air time: seconds with no ground under the car, scored on landing.
- Crashes: closing speed of each hard hit.
- Distance: every few hundred metres driven.
- Challenges: speed / drift / air / crash / distance / level / combo targets,
or
customones your game completes, each with an XP reward.
On screen it draws an XP bar (and a body-damage bar from car.damage)
with barsKit, and announces awards, level-ups and challenges as
navUiKit toasts and objectives. Both are optional: without them it still
scores and writes values.
First example
In a world with torqueCars (for a car), navUiKit and barsKit
installed, paste this into your scene's entrypoint.luau:
local Assemble = require("torqueCars.assemble")
function onLoad()
Assemble.spawn({ kind = "rally", position = vector.create(0, 0.3, 6) }) -- your car (W/S/A/D)
local hud = entity.spawn("progress")
hud.component.add("driveProgress.DriverProgress", { style = "arcade" })
end
Press Play and drive: the XP bar sits at the bottom centre with your level and rank, a damage bar above it, toasts pop for speed, drifts, jumps and crashes, and the style's challenges appear in the objective tracker. Switch the style live, any time (XP is kept, the level follows the new curve):
entity.find("progress").component.get("driveProgress.DriverProgress").style = "career"
With car left empty the component follows the local player's own car
(torqueCars' registry, else the player's avatar, else what the camera follows).
The styles
| style | curve | what scores | feel |
|---|---|---|---|
arcade (default) | linear, 250 XP + 60 per level | everything, every time | big numbers, a toast for every trick, bubbly bar |
career | steep, 400 XP × 1.3 per level | personal bests only; crashes score nothing and break the drift chain | formal wording, ranks Novice → Hall of Fame, segmented bar |
stunt | quadratic, 120 × level² | air ×2 and crashes ×2, speed barely | "WRECKED at 92 km/h", hologram bar, blood damage bar |
drift | linear, 300 + 80 per level | drift chains only (multiplier up to ×9.4), a crash wipes the combo | combo-chasing, thin bar, no damage bar |
zen | flat, 500 per level | kilometres driven and smooth slides; no crash scoring | quiet: only level-ups and challenges are announced |
Each style is plain data in driveProgress.styles (S.get("stunt")): the
curve, the per-event tuning (thresholds, XP rates, chain window and bonus), the
rank names, toast wording with {value} {xp} {links} {level} {rank} {text}
tokens, toast spacing, the barsKit looks and its default challenges.
DriverProgress settings
| Setting | Default | What it does |
|---|---|---|
style | arcade | arcade, career, stunt, drift, zen. Switches live. |
car | empty | The car to score. Empty = the local player's own car. |
manual | false | Read no car; score only what you feed(sample, dt). |
xpBar | true | barsKit XP bar on screen. |
damageBar | auto | auto (the style decides), on, off. |
barAnchor | bottomCenter | barsKit anchor for both bars (clear of navUiKit's compass and minimap). |
barSize | 1 | Extra bar scale. |
toasts | true | navUiKit toasts for awards, level-ups, challenges. |
objectives | true | Challenges in navUiKit's objective tracker (personal to this player). |
defaultChallenges | true | Start with the style's challenges; off = only yours. |
writeValues | true | Write the driver.* values. |
Methods (colon calls): progress(), reset(), setStyle(id),
addChallenge(def), removeChallenge(id), completeChallenge(id),
challenges(), bonus(xp, why?), feed(sample, dt), recent(), target().
progress() answers { style, xp, level, into, need, frac, rank, best = { speed, drift, air, crash, links }, totals, live = { drift, combo, air, damage, distance }, challenges, car }.
A challenge: { id, text, kind, target, xp } with kind speed / crash
(km/h), drift / air (seconds), distance (metres), combo (links),
level, or custom (completes only through completeChallenge).
local dp = entity.find("progress").component.get("driveProgress.DriverProgress")
dp:addChallenge({ id = "ice", text = "Drift 3 s on the frozen lake", kind = "custom", xp = 300 })
-- later, from your own zone check:
dp:completeChallenge("ice")
Values it writes
On the component's entity and on the car being scored (the topics/values
guide): driver.xp, driver.level, driver.levelFrac (0..1 into the level),
driver.combo (links in the running drift chain), driver.drift (seconds in
it), driver.air (seconds airborne now), driver.distance (metres).
Without the component
driveProgress.score is the whole scoring core as pure functions, for a HUD of
your own, a server, or tests:
local Score = require("driveProgress.score")
local st = Score.new("career")
Score.addChallenge(st, { id = "fast", text = "Reach 150 km/h", kind = "speed", target = 150, xp = 250 })
local events = Score.step(st, { kmh = 152, speed = 42, slip = 3, airborne = false,
impactCount = 0, impactSpeed = 0, damage = 0 }, 1 / 60)
for _, ev in events do print(ev.kind, ev.xp, ev.text) end
print(Score.levelInfo(st).level)
driveProgress.reader turns a car into that sample (Reader.resolve(car),
Reader.sample(id)).
Gallery
gallery (a scene) shows all five styles side by side, each scoring the same
scripted drive (flat out to 170 km/h, a three-slide drift chain, a jump, a
75 km/h crash), with its level, rank, barsKit XP bar, event feed in its own
wording and its challenges:
layers.load(asset.ref("driveProgress.gallery", "scene"), { additive = true })
Or put driveProgress.ProgressGallery on any entity.
What is inside
| Part | What it is |
|---|---|
DriverProgress (component) | Scores a car, writes values, toasts, objectives, XP + damage bars. |
ProgressGallery (component) | All styles scoring one scripted drive, side by side. |
score (module) | The pure scoring core. |
styles (module) | The five styles as data. |
reader (module) | Car → sample (contract values, slip angle, airborne ray). |
gallery (scene) | The gallery, ready to load. |
tests/driveProgress (test suite) | Scoring, styles, challenges and the component API. |
Multiplayer
Progression is per player and local: each peer scores its own car and draws
its own bars and toasts; objectives are personal (player = "local"). Nothing
is synced. car.kmh, car.damage and slip are written on the car's owner, so
pointing car at someone else's car only gets the replicated values (crashes)
there.
Known limits
- Progress is not saved between sessions; persist
progress().xpyourself (for example with a save kit) and restore it withbonus(xp)on load. - Air time uses a 2.2 m ground ray under the chassis unless the car
publishes
car.airborne; a car over a deep gap counts as airborne, a very tall vehicle may not be detected airborne on small hops. - Slip angle is measured from the chassis velocity, not the tyres, unless
the car publishes
car.slip: a car sliding backwards past 110° does not count as a drift. - Crash scoring needs
car.impactCount/car.impactSpeed; a plainVehicleControllercar without them scores no crashes. - Toasts and objectives need navUiKit (the component starts its HUD in play if nothing has yet); bars need barsKit. Without them the component still scores and writes values.
- The XP and damage bars share one barsKit anchor (
barAnchor); move them if your game already has a bar there.