Vehicles

check_vehicle_addon

[Experimental] Prove a vehicle add-on will fit and LAND WHERE IT SHOULD before it is published (executes the bundled helix vehicle addon check). Directory: addon.json { title, fits, ops, description?, tags?, version?, provenance? } + model.glb (tune-only parts ship none). Checks: the fits/ops contract (at most 32 ops; 64 for a clip-set), the model's scene.extras.helixMeshFrame (a socket-frame part must be centred on its mount — the hub for wheels), and per host: it is a vehicle, its drawn wheel origins are AT THE HUBS, every hide glob matches a host node, the host board GRANTS the hide (the standard board grants only stock globs, so a wheel hiding rim_* fits ZERO hosts until the host grants it) and EXPOSES every tunable path the part requires; then the backend's own fit dry run reports how many hosts it really fits; and for tune ops the DRIVE EFFECT on each host, measured with the live runtime's own physics and add-on fold (0-100, top speed, quarter mile, skidpad g and body roll, 60-0 at full and 30% pedal, handbrake), each op judged on a figure it can move — a part that changes nothing is an error, an op that cancels another a warning. A performance-slot part (engine, ECU, gearbox, exhaust, brakes, suspension, anti-roll bars, intake) with NO tune op and no sound mount is refused up front (round 5's "competition exhaust" did nothing). It also runs the web customizer's own meshless guard on the exact add-on definition publish would seal: a part with no model.glb must be a verified tune-only (or sound-only) definition, otherwise the customizer refuses to equip or save it and the check reports ADDON_CUSTOMIZER_REFUSES with the customizer's exact message (round 8 sold four tune-only parts that every older check called fit). The drive effect is measured ungoverned (speedLimiterKph is ignored; no add-on can add or remove a speed limiter). Exit 0 = fits every named host and does something.

check_vehicle_audio

[Experimental] Prove every sound a vehicle declares will actually play, is SOURCED (real recordings with provenance, never synthesised) AND sounds like an engine — the silent-car check visual QA never makes (executes the bundled helix vehicle audio-check). PROVENANCE: it prints, for every slot and bank, its source — sim, mod, url, source file, sha256, extractor — and REFUSES synthesised or generated audio (AUDIO_SYNTHESISED), FAILS a car without sourced engine audio, i.e. one that would fall back to the engine's built-in synthesised engine (AUDIO_ENGINE_UNSOURCED), and FAILS any EMPTY slot and any slot that would fall back to a platform default (the generated default sound pack, synthetic starter, runtime tyre/skid/handbrake noise) — all 31 slots must be sourced (AUDIO_SLOT_UNSOURCED); the only permitted empty slots are a component the real car physically lacks (turbo slots on an NA car, reverseBeep, clutch on an automatic/CVT, EV combustion slots and, on a single-speed drive, shiftUp/shiftDown; transmissionWhine stays required; an EV is detected from physics, its motor ladder is a recording, and audio.drivetrain:"electric" FAILS as AUDIO_SYNTHESISED), declared consumed:false, absent:"not-fitted" plus a reason, and exhaustLadder absent:"combined-with-engine" beside a sourced engine ladder. Also refused: AUDIO_MIX_FIELDS_MISSING (engineGainDb/exhaustGainDb missing or non-finite, or minLoadMix/maxLoadMix/muffling outside 0..1 — a car shipped without them froze in Try Now), AUDIO_PROVENANCE_MISSING (a recording that says nothing about its origin) and AUDIO_SLOT_FITMENT_MISMATCH (a not-fitted claim the physics contradicts, or turbo sounds on a non-turbo car). The fix is import_vehicle_audio from the most accurate simulator mod (then the BeamNG base game, another sim, real recordings), never synthesis. It selects samples exactly as the engine does (every rung of the engineBlend/exhaustBlend ladders, and each slot asset named by its buffers) and requires each to resolve (pre-publish: a WAV beside the package; published: HTTP 200 with the exact declared bytes and sha256), to be PCM WAV, and to be audible rather than digital silence. A cid-only row, a 404, a re-encoded file or an MP3 each fail. Three further gates: every ladder rung's measured fundamental must match its rpm label against the firing fundamental for the declared sampleCylinderCount/strokes/crankLayout (a rung an octave or more off is refused — the round-7 octave-low ladders), engine and exhaust must be separate sourced recordings (a mod with ONE combined recording omits exhaustBlend and declares exhaustLadder absent:"combined-with-engine"; both blends on one sourced recording is only a warning, AUDIO_ENGINE_EXHAUST_SHARED_RECORDING), and each rung must be a real broadband engine sound, not a near-pure synthetic tone (measured by autocorrelation and spectral noise floor; a beep passes pitch but fails this). CONTENT GATES (thresholds calibrated so the 993, recorded horns and field recordings pass): AUDIO_CLIPPED (flat-topped runs at full scale or at the file's own peak), AUDIO_DC_OFFSET, AUDIO_LADDER_FIXED_FORMANTS (one resonator stack stamped on every rung), AUDIO_LADDER_FIXED_TONE (a fixed-frequency line in most rungs), AUDIO_LADDER_RUNG_COPY (a rung resampled from its neighbour) and AUDIO_HORN_SYNTHETIC (an exactly periodic horn, warn) — read_skill helix-vehicles reference "audio", "Content gates". Also refused: two roles that are one recording (shift up = shift down, horn = an engine rung, an exhaust rung = an engine rung resampled), and a rev-limiter sample longer than 0.35 s (the runtime re-fires it every 60 ms, so a long clip plays as a held tone). Pass reference (a recording of the real car idling) to compare your idle voice with it. Pass a package directory/JSON before publishing, or a published vehicle item id to read back what the runtime gets. Exit 0 = every sample plays, is sourced and is a real engine sound; 1 = a sample will not play, a slot is empty or unsourced, audio is synthesised, or a gate fails.

check_vehicle_cabin

[Experimental] Judge every declared seat of an UNPUBLISHED (or published) car's cabin OFFLINE, in about a second, with no browser and no sign-in (executes the bundled helix vehicle cabin-check). It fits the cabin with the platform runtime's own fitCabinToBody and seats the runtime's canonical legs at the fitted pose, measured against every triangle of the model, then reports per seat — any seat count (2, 2+2, 4, 5, 7) — H-point height over the floor, how far the runtime had to move the seat, head clearance to the roof's inner surface, knee, shin and foot clearance, the legs against the seat ahead and the tunnel/console, the rear footwell under the front seats (free height over the foot) and the driver's legs against the wheel, each PASS / WARN / FAIL with millimetres and what it is against. Iterate rear seats with this (seconds), then confirm once with preview_vehicle({ occupants: true }), which boards every seat. A WARN within a few millimetres of the seat ahead is a likely live clip (a real avatar's legs run longer than the canonical ones): clear it. Exit 0 = no FAIL (warnings may remain), 1 = a seat FAILs, 2 = could not run. validate_vehicle with cabin: true runs the same check.

check_vehicle_host

[Experimental] Read a published vehicle's add-on surface the way the customizer sees it (public reads, no sign-in): its slot board (host kind, measured sockets / nodes / tunable paths, hide grants) and every add-on that FITS it, grouped by slot type with price, against the required minimum parts set (wheels, exhaust, ECU, gearbox, suspension, brakes, anti-roll bars; spoiler where the real car has one). Also runs the web customizer's own add-on guard on EVERY fitting add-on's exact Package pin (the CLI's vendored copy of the customizer's meshless guard, public reads): a part the customizer would refuse to equip or save ("Add-on definition declares visual geometry but has no public web GLB.", a visual mount with no GLB, a wrong root) is named with the customizer's message. Also fails when the car's GLB lacks the nodes a host-frame add-on binds to (HOST_BIND_ROOT_MISSING: no vehicle_root node; HOST_BIND_MOUNT_NODE_MISSING: an offered boot/bonnet socket with no node; HOST_BIND_ROOT_NOT_OWNER: the lid is outside vehicle_root), and when any published add-on's bind root is absent from the car: the message names the node, the slot and the add-on and says to add an empty node of that name over the car's top-level nodes. Fails when the car is not a host (its GLB had no asset.extras.HELIX_vehicle at mint), when the board has no sockets or no tunable paths, when a required part is missing or not for sale, or when any fitting add-on would be refused by the customizer. Run it after the car is published and after each of its add-ons.

get_vehicle_reference_package

[Experimental] Copy the reference vehicle package — the complete helix.vehicle-package/2 of the live Porsche 911 (993), which passes visual QA and drives live — to a path you name, and return a short summary of its blocks. It is about 75k characters of JSON, too large for any tool output, so it is never returned inline: read the copied file block by block. Its notes are stripped of the 993's own provenance; replace EVERY number, citation and slot note with your car's. Its AUDIO block is shape only: the 993's sounds are not your car's, so replace the whole block with your car's sound from its most accurate simulator mod (import_vehicle_audio, never synthesised) and give every slot its provenance. What to keep, change or delete: read_skill({ name: "helix-vehicles", reference: "reference-package" }).

import_vehicle_audio

[Experimental] AUDIO STEP ONE for every vehicle, whatever its mesh source: extract the car's real recorded sound from the most accurate simulator mod (executes the bundled helix vehicle audio-import; minutes, FMOD bank decoding). HARD RULE: NEVER generate or synthesise vehicle sound (no resynthesis, no generate_audio, not even for a slot nothing provides, and never rely on the platform's default sounds: the synthesised fallback engine, the generated default sound pack, runtime noise); ALWAYS source real recordings, from BeamNG mods as much as possible, and a car ships a sourced recording for EVERY one of the 31 runtime slots (the only empty slots are a component the real car physically lacks, declared consumed:false, absent:"not-fitted" plus a reason, and exhaustLadder absent:"combined-with-engine" beside a sourced engine ladder; doors are required). Audio step one, whatever the mesh source: find the most accurate simulator mod of that exact car (BeamNG first; Assetto Corsa/ACC, rFactor 2, Automobilista 2 where theirs is more accurate), choose it by MEASURING candidates against real recordings of the car (firing-fundamental pitch track vs rpm, spectral centroid, roughness, idle character, limiter cadence), and extract it with import_vehicle_audio. Source: a BeamNG mod directory or .zip, an Assetto Corsa car directory or .bank, or a single .bank. It decodes the mod's engine and exhaust rpm ladders (row 0 = off-throttle/low load, row 1 = on-throttle) and its one-shots (startup, shutdown, idle, revLimiter, shiftUp/shiftDown, turboSpool, blowOff, backfire, tyreSqueal, doorOpen/doorClose, horn, intake, transmissionWhine, clutch, impacts, suspension, reverseBeep) to 16-bit PCM WAV under <out>/audio/ and writes <out>/audio.json — an audio block (bank + slots) to merge into vehicle-package.json — where EVERY consumed slot and bank carries provenance { kind: "sim-mod" | "sim-official" | "recording", sim, mod, modUrl?, sourceFile, sourceSha256, event?, extractor }. map is a slot-map JSON that builds one car from several sources (one mod's ladder, another mod's horn; stock events by exact take, trim, concat, real recordings, absent:"not-fitted") — read_skill helix-vehicles reference "audio-import". EVERY one of the 31 slots must come out sourced (engineLadder, exhaustLadder, idle, startup, shutdown, shiftUp, shiftDown, clutch, transmissionWhine, turboSpool, blowOff, intake, revLimiter, backfire, suspension, impactLight, impactMedium, impactHeavy, tyreSqueal, tyreScrub, tyreSpin, tyreRollSlow, tyreRollFast, indicatorTick, skid, brakeSqueal, handbrake, reverseBeep, horn, doorOpen, doorClose); a slot the best mod lacks is filled, in order, from another BeamNG mod of the same engine or car family, the BeamNG base game's stock banks and vehicles/common sounds, another simulator's mod, real recordings of the car — never another car's sound, never synthesised, never a platform default. The only permitted empty slots are a component the real car physically lacks (turboSpool/blowOff without a turbo, reverseBeep, clutch on an automatic/CVT, EV combustion slots), declared consumed:false, absent:"not-fitted" plus a reason, and exhaustLadder absent:"combined-with-engine" beside a sourced engine ladder when the mod records one combined set. Doors are required. HOW TO PICK THE MOST ACCURATE MOD: measure every candidate against real recordings of the car — firing-fundamental pitch track vs rpm, spectral centroid, roughness/harmonic balance, idle character, limiter cadence — with the commands in read_skill({ name: "helix-vehicles", reference: "audio" }), never by reputation. Writes <out>/audio.json (all 31 slots, plus the five mix fields the runtime reads: from the map, basePackage, the mod's soundConfig, else engine defaults) and <out>/audio-import.json (the report: every slot's decision, source, alternatives and reason, and the unmapped source sounds). Then run check_vehicle_audio. Exit 0 = every slot written with provenance; 1 = the source could not be read, yielded no engine audio, or left slots unfilled (the output lists them). Answers NOT AVAILABLE when the bundled CLI has no audio-import command (it never improvises a synthesised substitute).

preview_vehicle

[Experimental] Render an UNPUBLISHED vehicle (a package directory, or vehicle-package.json + GLB, that exists only on disk) headless in the REAL HELIX runtime and measure it (executes the bundled helix vehicle preview; several minutes), before the first mint locks groundToBodyOrigin forever. Nothing is uploaded or recorded. Returns a per-wheel stance table and PASS/FAIL per check — ride height vs your declared groundToBodyOrigin (with the value to declare instead), wheels at hubs, arch clearance, spin, steering, panels, seats, rolling radius vs wheelRadius — and writes fixed appearance poses (front, side, rear, top, front34, rear34, cockpit under <out>/poses/, plus poses.jpg) and a contact sheet you must LOOK at beside your reference photos. Pass referencePaint (the median body-paint colour of the reference photos, #rrggbb) to also gate the RENDERED paint as Try Now daylight draws it: the body paint alone from six cameras with the world's own sun, exposure, tone mapping and local lights, judged on hue, saturation, lightness and highlight wash (vehicle.paint.; a red that renders salmon or a bonnet that blows to white fails; white/silver/grey/black are judged on tint and lightness). Pass referenceWheel (a face-on close-up photo of the real wheel; optional spokeCount, finish, centreCap, crop) to also render the candidate's wheel square-on and fail vehicle.wheels.design. on spoke count, finish or missing centre cap. It also presses every lamp key and fails vehicle.lamps.each_function_lights naming a lens that stays dark. occupants: true seats an avatar in EVERY declared seat, rear rows included (a seat the stand-in room has none of is granted in the preview's own page, so a preview is single-client), prints the CABIN FIT (where the runtime actually put each seat, and fails when it moved one more than 30 mm or refused it) and measures the cabin the way visual QA will (head clearance, hips, feet, hands on the rim, penetration). It never runs the vision critic: only a submitted or hosted visual QA is a gate result. Seats board through the candidate's OWN seat ids. OCCUPANTS AND THE GAUNTLET INSPECTION SET ARE ON BY DEFAULT: every seat is occupied and the hands are measured over time (blocking: hands_on_wheel_steering — both driver hands on the rim at centre, left lock and right lock; hands_follow_wheel — they travel round with the wheel; hands_at_nine_and_three; fingers_still and hands_still — no twitching or grasping; plus posture torso_angle, knees_up, head_in_wings), and <out>/inspection/ gets small contact sheets, one LOOK question each: exterior 8 angles day and night, each lamp lit at night, wheels, panels open, every seat from first person / side glass / over the shoulder / windscreen, the driver steering left/centre/right, and still-hands frames (preview.inspection.complete fails a set with a hole). OPEN EVERY SHEET beside the reference photos (read_skill helix-gauntlet). With item and no target and no addon it inspects a PUBLISHED car exactly as the runtime serves it. With addon: [<dir>...] it previews UNPUBLISHED add-ons instead, fitted by the engine's own fold to the candidate car or to a published car (item), and measures the DRAWN part in world space against its anchor: wheels within 1 cm of each hub, socket-framed parts on their socket, host-framed parts inside the car and not at its origin (the classic part-at-the-car-centre bug); a tune-only add-on has its ops read back from the live tuning and the v2 driveline. A host-frame add-on whose bind root/socket the car's GLB lacks is refused in under a second, before any browser (HOST_BIND_*); a runtime composition failure ('[helix-vehicle] composition failed') or page error before the car appears fails immediately with its message instead of a 120 s timeout. Needs a helix login (a QA account). Exit 0 pass, 1 fail, 2 could not measure.

publish_vehicle

[Experimental] Publish a vehicle end to end from a package directory, Package-first (executes the bundled helix vehicle publish; minutes, not seconds) and return its output and exit code. Directory: vehicle-package.json, model.glb carrying asset.extras.HELIX_vehicle, the WAVs beside it or in audio/, and publish.json { title, description, tags, version, contentRating, provenance: { kind: "authored"|"imported"|"generated", source }, hostGrantExtensions: { "whl.wheel": { "hide": ["rim_*"] }, … } }. It validates (package, GLB, host manifest, the drive against targets, every audio sample and its provenance), REFUSES synthesised or generated audio (AUDIO_SYNTHESISED) a car without sourced engine audio (AUDIO_ENGINE_UNSOURCED — the engine's built-in synthesised fallback engine is not an engine sound for a published car; run import_vehicle_audio first) and any empty or default-falling-back slot (AUDIO_SLOT_UNSOURCED — every one of the 31 slots needs a sourced recording; platform defaults are never an answer), uploads the GLB and WAVs as public objects, builds the root (mesh.visual pinned to the uploaded GLB, audio rows pinned, the hide grants sealed in), seals a public vehicle Package, makes the Item from that exact Version, and reads everything back (pin, package identity, mesh, audio, the add-on host board). It opens no offer. With itemId + version + reason it seals a STAGED version into the same car's Package and moves the item (or stops at staged-awaiting-visual-qa on a listed car) — the only way to change a car that exists; never mint a second copy. ACTIVATE a new version of a LISTED car only by re-running this same call after visual QA passes (pin and properties.vehiclePackage move together); NEVER helix item set-version for a vehicle (it moves the pin but not properties.vehiclePackage, so the car keeps serving its old package). Resumable: re-run the same call after any failure (ledger in <dir>/.helix-publish). Exit 0 = published and verified (or staged awaiting visual QA); 1 = a check failed; 2 = could not run. Run dryRun first. Answers NOT AVAILABLE when the bundled CLI has no vehicle mint.

publish_vehicle_addon

[Experimental] Publish a vehicle add-on end to end from its directory, Package-first (executes the bundled helix vehicle addon publish; minutes): the full check_vehicle_addon (including the drive-effect measurement) → upload the model (none for a tune-only part) → seal a public addon Package → make the Item from that exact Version (pinned at birth, unlisted, no offer) → read back (pinned, the backend lists every host as a fit, it appears on each host's add-on rail). A hide the host has not granted stops it: the host car must seal the grant (hostGrantExtensions in its publish.json). Sell it with create_item_distribution once visual QA passes. Resumable. Exit 0 = published and verified. itemId + version publishes a changed part as a NEW VERSION of the same item (staged, then moved; a listed meshed part is held by visual QA: stage, run visual QA on that version, repeat the same call to finish). dryRun also runs the seal's refusals (provenance.source <= 256 chars, contentRating, title/tag limits, Package shape, version clash). Answers NOT AVAILABLE when the bundled CLI has no add-on mint.

simulate_vehicle

[Experimental] Drive an UNPUBLISHED vehicle package offline on the platform's own vehicle runtime (executes the bundled helix vehicle simulate; it fetches and caches the live humanoid-character runtime) and return 0–100 km/h, 0–60 mph, quarter mile, top speed, ungoverned top speed, 100–0 km/h and 60–0 mph braking, skidpad lateral g, turbo lag, the gears used and the rest pose (grounded, pitch and roll ≤ 3°), each compared with the package's targets (a row passes when |simulated − target| / target ≤ its tolerance fraction). KEYBOARD LAUNCH: it also launches the car the way a keyboard player does (W 0→1 in one tick, A/D taps with 100 ms reactions holding a lane; W+A/D is normalised to 0.707 throttle; a land-v2 car has traction control only when its package authors simulation.land.tractionControl, which this models exactly as live and reports on a traction control: line) and nudges the yaw 0.2 rad/s hands-off at 20/40/60/100 km/h and as each upshift re-engages: keyboard 0–100 vs the instrument, wheelspin per gear, post-shift yaw, lane offset. A nudge that grows into a spin FAILS "not drivable on a keyboard" (validate_vehicle reports it as the warning SIMULATED_KEYBOARD_LAUNCH_UNDRIVABLE; tune only with sourced levers, or author traction control (the real system, or a declared playability aid) — physics-from-specs "Drivable on a keyboard" and "Traction control"). Exit 0 = every compared figure passes and the keyboard launch does not FAIL; 1 = a figure is out of tolerance, the rest pose is wrong or the car is not drivable on a keyboard; 2 = could not simulate. validate_vehicle runs the same check. It also reports the SHIFT SCHEME: a gearbox with auto.enabled false cannot shift itself, so the figures cannot be reached and the live car will pin 1st gear unless the player uses the manual keys — and a manual-kind box with auto enabled is reported as "simulated with auto-shift; live manual-shift unverified". Run it after every physics edit and before the first mint: it is the only way to know a car is too quick or stops too short without publishing it. Only grip.peak and suspension.* (and, for a turbo car, the derated low end of the curve) are yours to tune toward the targets (read_skill helix-vehicles reference "physics-from-specs"). Also prints the engine-policy warnings SPEED_LIMITER_IS_A_MARKET_GOVERNOR (speedLimiterKph below 0.9 × the ungoverned top speed: the platform car runs ungoverned and the live solver never applies a limiter; null it and set targets.topSpeedKph to the ungoverned figure), TORQUE_CURVE_EXCEEDS_DECLARED_CRANK_FIGURES (a torque curve or peak field more than 5 % above the maker's declared crank figures: put losses in drivetrainEfficiency and drag, never inflate the curve) and AWD_DRIVE_BIAS_* (driveBiasFront must be strictly between 0 and 1 and equal centre.torqueSplit on an AWD car) — see physics-from-specs.

validate_vehicle

[Experimental] Run the HELIX vehicle validator (executes the bundled helix vehicle validate) on a vehicle package (helix.vehicle-package/2) and, with glb, its model — BEFORE any publish — and return its report and exit code. It checks the engine's own package validator (a package with an error never spawns, and publish does not catch it), the publish gate (distributable provenance, wheelVisuals, required fields), groundToBodyOrigin = wheelRadius + staticRideHeight (locked after first publish), the GLB host manifest in asset.extras.HELIX_vehicle (without it the car is no add-on host), the host-frame bind nodes (a car offering a boot/bonnet socket needs the lid's mount node and a vehicle_root node owning it, or a bound add-on throws in the runtime and the car is never presented: HOST_BIND_), all four wheel nodes with their origins AT THE HUB, frame orientation, the platform budgets (24 draws, 90k triangles, 48 materials, 2048 px), articulation panel nodes and their controls, the specialty componentBuild digest (prints the computed value), and the drive figures against targets (simulate_vehicle; skip with noSimulate). Exit 0 = no errors. It also prints, as warnings, SPEED_LIMITER_IS_A_MARKET_GOVERNOR, TORQUE_CURVE_EXCEEDS_DECLARED_CRANK_FIGURES and AWD_DRIVE_BIAS_ (the platform car runs ungoverned on the maker's declared crank figures; physics-from-specs). With cabin: true it also runs check_vehicle_cabin's per-seat fit (errors CABIN_CHECK_FAIL, warnings CABIN_CHECK_WARN); a car that declares more than two seats is pointed at it. read_doc({name:"vehicles"}) is the contract it enforces.