Appearance
Vehicle definitions
A vehicle is plain JSON described by a published JSON Schema (@skidpad/core/schema). It has a formatVersion, and migrateDefinition() brings older files forward. Every field has a default and SI units; the only non-SI fields end in Deg.
Components
| Component | What it holds |
|---|---|
chassis | Mass, yaw, roll and pitch inertia, wheelbase, centre-of-mass position and height, track width |
axles | Front then rear. Each has a tire, a suspension (with its kind, roll-centre height and anti-dive and anti-squat), wheel inertia, driven, steered, brake torque, static camber and toe, lateral-force compliance steer, and an optional own track width |
steering | Maximum road-wheel angle, steering ratio, Ackermann fraction, aligning-torque compliance |
brakes | Handbrake torque |
drivetrain | Power unit (direct, combustion or electric), transmission, axle and centre differentials (ADR-0011) |
aero | Drag coefficient, frontal area, air density, lift coefficient per axle, height of the drag line above the centre of mass (ADR-0015) |
simulation | Internal substep rate and model: "fourWheel" (default) or "singleTrack" |
dataSheet | Sources for reference vehicles |
Tire and suspension parameters are quoted per wheel. The single-track model evaluates one tire at half the axle load and doubles the result, so the same definition drives either model.
Suspension
Each axle's suspension holds the per-wheel spring rate, bump and rebound damping, bump and droop travel from the static ride height, the anti-roll bar stiffness, and the bump-stop stiffness. Ride height is chassis.cgHeight; the spring is preloaded to hold it, so changing the spring rate changes stiffness, not height. See suspension for what each does and the tuning guide for which to touch.
Two fields describe the geometry rather than the springs, and only the four-wheel model reads them. kind is "independent" (default) or "solid": a solid axle keeps both wheels upright to the line through their contacts instead of leaning with the body. rollCenterHeight (m, default 0) is the axle's roll-centre height above the ground; the share rollCenterHeight / cgHeight of that axle's lateral load transfer then goes through the links to the tires instead of rolling the body (roll centres). It is accepted within ±1 m.
An optional kinematics block makes the geometry change with travel: curves of toe, camber, roll-centre height and the two anti fractions against each wheel's travel, as [travel, value] points with travel in metres, positive in bump. Each curve is an offset from its static field and must be zero at zero travel; it describes the left wheel and the right mirrors it. Toe and camber curves are rejected on a solid axle. Leave the block out to keep the geometry fixed at ride height (geometry that changes with travel).
Aero
aero has the drag coefficient, the frontal area every coefficient is referenced to, and the air density. liftCoefficientFront and liftCoefficientRear (default 0, accepted within ±10) give a lift force at each axle from the forward speed squared; negative is downforce. dragHeightAboveCg (m, default 0) is how far above the centre of mass the drag acts, which pitches the nose up at speed. See aerodynamics.
validateDefinition() warns when the static load would compress a spring beyond its bump travel, which means the car rests on its bump stops.
When you specify an axle, set driven and steered explicitly. The core default for both is the front-axle setting, and validateDefinition() warns when either is missing.
Tires
tire.model is "feel" or "magicFormula".
The feel model is parameterised by things you can reason about: peak friction, where the peaks occur, stiffness, falloff after the peak, load sensitivity, camber stiffness, pneumatic trail. See the slip explainer to see what each does.
The Magic Formula model takes lower-cased .tir coefficient names. Build one with importTir(text), which returns the parameters and a list of warnings for every coefficient outside the supported subset. Sign convention is ISO 8855, the same as .tir files: positive slip angle gives negative lateral force, and PKY1 is negative.
Validation
validateDefinition() explains problems in plain language ("chassis.cgToFrontAxle must be less than the wheelbase") rather than a schema path dump, and runs before anything reaches the core.