helix vehicle

helix vehicle

Validate and preview a Universal Vehicle before Package publication

helix vehicle <command>

helix vehicle validate

Validate a vehicle package (and optionally its GLB) against the engine contract, the backend pin rules and the publish budgets. Exit 0 = no errors, 1 = errors, 2 = unreadable input

helix vehicle validate [options] <vehicle-package.json>

helix vehicle preview

Render a vehicle that is not published yet in the real HELIX runtime (headless) and measure it: ride height against groundToBodyOrigin, wheels on their hubs, arch clearance, rolling radius, steering, doors, seats. Run it BEFORE the first mint, which locks groundToBodyOrigin. Every car preview also writes the fixed appearance poses (poses/pose.front|side|rear|top|front34|rear34|cockpit.jpg and poses.jpg) to compare with reference photos, and the GAUNTLET INSPECTION SET as small contact sheets under <out>/inspection/ (8 angles day and night, each lamp lit, every wheel, every panel open, EVERY seat occupied from first person, side glass, over the shoulder and windscreen, the driver steering left/centre/right, and still-hands frames), with blocking occupant asserts (posture, hands on the rim while steering and following it, 9 and 3, still fingers and hands). Read every sheet. --item <id> with no car directory and no --addon inspects a PUBLISHED car as the runtime serves it (re-checking a listed car against the current gates). With --addon <dir> it previews unpublished vehicle ADD-ONS instead: each add-on directory (the layout vehicle addon check|publish reads) is fitted to the candidate car, or to a published car (--item <id>, no car directory) by the engine's own fold, and the DRAWN geometry is measured in world space against its anchor (wheels within 1 cm of each hub, socket-framed parts on their socket, host-framed parts at their authored position, inside the car, not at its origin; a tune-only add-on has its ops read back from the live tuning). Nothing is uploaded or recorded. Exit 0 = every blocking check passed, 1 = a check failed, 2 = could not measure

helix vehicle preview [options] [dir-or-package.json]

helix vehicle recheck-listed

Re-judge LISTED vehicles against today's gates. A listed car is never re-judged when a gate is added, so its visual-QA record can predate the gate that would fail it (the F40 was listed before the posture and hands-while-steering asserts existed). For each car this reads the passing record of its current version and names every current blocking gate it never ran (STALE) or failed (FAIL). With --rerun it renders each car again now (vehicle preview --item: every seat occupied, the full inspection set and its contact sheets) and reports that verdict. Agents updating a car must run this on it. Exit 0 = every car current and (with --rerun) passing, 1 = a car needs action, 2 = could not run

helix vehicle recheck-listed [options] [itemIds...]

helix vehicle simulate

Drive a vehicle package offline with the platform's OWN engine instrument (the runtime ^0.3 serves today: Rapier, land solver v2, the code players run) and judge it: 0-100 km/h, 0-60 mph, quarter mile, top speed (converged or not), 100-0 km/h and 60-0 mph braking, skidpad lateral g, turbo lag, gears used and the rest pose. Every figure is compared with the package's own targets (and --spec): error = (simulated - target) / target, PASS iff |error| <= tolerance. The runtime is fetched once per version and cached by sha under ~/.helix/cache/engine-runtime; offline, the last cached runtime is used and labelled. TURBO LAG: with boostTorqueCoef 0 the solver adds no boost torque, so a turbo car whose curve is the full-boost dyno curve pulls with no lag; author lag by derating the torque curve below spool, then check turbo lag here (docs/vehicle-simulate.md). 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; the platform does not ramp a digital throttle, and a land-v2 car has traction control only if its package authors simulation.land.tractionControl — modelled here exactly as live) and nudges the yaw 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/heading/sideslip, lane offset. A nudge that grows into a spin FAILS "not drivable on a keyboard". 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

helix vehicle simulate [options] [dir-or-package.json]

helix vehicle cabin-check

Judge every seat of a car's cabin OFFLINE in seconds (no browser, no sign-in): the engine runtime's own cabin fit plus the canonical seated legs measured against every triangle of the body. Per declared seat, any seat count (2, 2+2, 4, 5, 7): the H-point above the floor, how far the runtime had to move the seat, head clearance to the roof's inner surface, knee clearance to the seat back ahead, shin and foot clearance, the legs against the seat ahead and against the tunnel / console, the rear footwell under the front seats (free height over the foot, depth ahead of the cushion), the driver's legs against the wheel, and any limb inside the body. Each row is PASS / WARN / FAIL with numbers. Iterate with this, then confirm with helix vehicle preview <dir> --occupants (which now boards and seats every seat). The runtime is fetched once per version and cached under ~/.helix/cache/engine-runtime; offline, the last cached runtime is used and labelled. Exit 0 = no FAIL, 1 = a FAIL, 2 = could not run

helix vehicle cabin-check [options] [dir-or-package.json]

helix vehicle audio-check

Prove every sound a vehicle declares will actually play: each engine-ladder rung and slot sample the runtime selects must resolve (a local WAV beside the package before publish, or HTTP 200 with the exact declared bytes and sha256 after), be PCM WAV, and be audible (not silence). It also measures what each sound is made of: clipping, DC offset, a resampled-copy ladder rung, one fixed formant stack or fixed tone shared by every rung, near-duplicate sounds across roles (shift up = shift down, an exhaust rung = an engine rung), a rev-limiter clip too long to stutter (the runtime re-fires it every 60 ms), and an exactly periodic synthetic horn (each reported with its measured value and a fix). Pass a package directory / package JSON for the pre-seal check, or a published vehicle item id for the read-back check. Exit 0 = every sample plays

helix vehicle audio-check [options] <dir|package.json|item-id>

helix vehicle audio-import

Take a car's sounds from the sim mod that carries them — never synthesised. Reads a BeamNG mod (folder or .zip: its own engine/exhaust sfxBlend2D ladders, every sound its selected parts name — starter, shutdown, afterfire, turbo whine and blow-off, gearbox whine, shift levers, door latches, horn and soundscape, beam sounds — and the recordings it ships), an Assetto Corsa / ACC car (folder or its sfx .bank: the FMOD engine event becomes the rpm ladder, row 0 off-throttle and row 1 on-throttle, exterior preferred; horn, doors, gears, turbo, backfire, limiter, skid, wheel and transmission events become slots) or a bare FMOD .bank. With --beamng-root the BeamNG install's stock FMOD banks resolve every stock event a mod names, and fill what the car does not name with what the game itself plays (tyres, impacts, doors, shift, suspension). Writes <out>/audio/*.wav (16-bit PCM; malformed WAV headers repaired, sample bytes untouched) and <out>/audio.json — the package audio block (bank + all 31 slots) with provenance { kind, sim, mod, modUrl?, sourceFile, sourceSha256, event?, extractor } on every slot, bank sample and blend — plus <out>/audio-import.json. A slot no source provides stays EMPTY with the reason (for a stock event: exactly which). --map merges several sources (one mod's ladder, another mod's horn, an AC car's doors). Exit 1 when a slot or the engine ladder is left without a recording

helix vehicle audio-import [options] <source>

helix vehicle addon

Check vehicle add-ons (wheels, kits, exhausts, tune parts)

helix vehicle addon <command>

helix vehicle addon check

Prove an add-on will fit and land where it should BEFORE paying for it: the local fits/ops contract, the model's helixMeshFrame anchoring (a socket-frame part centred on its mount), per host — a vehicle, wheel origins at the hubs, hide targets present, hide grants on the board — tunable paths the part requires exposed on the host surface, the backend's own fit dry run (POST /universal-items/validate-fit: how many hosts it actually fits), the web customizer's meshless guard on the exact definition publish would seal (a part with no model.glb must be a verified tune-only/sound-only definition, or the customizer refuses to equip it: ADDON_CUSTOMIZER_REFUSES), 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 roll, full- and part-pedal stops, handbrake), each op judged on a figure it can move; an op that changes nothing or cancels another is reported. Directory: addon.json { title, fits, ops, ... } + model.glb (none for a tune-only part: ECU, gearbox, brakes, sway bars, coilovers, tyre compound — every op a tune). Exit 0 = fits every named host and does something. PUBLISHED mode (no directory, public reads, no sign-in): --item <addOnItemId> (repeatable) reads the Item's exact Package pin, the public manifest and, for a meshless part, its root, and runs exactly what the web customizer runs; --host <vehicleItemId> does that for every add-on on the car's rail. Exit 1 = the customizer would refuse a part, with its message

helix vehicle addon check [options] [dir]

helix vehicle addon publish

Publish a vehicle add-on directory: the full vehicle addon check (drive effect measured), upload the model, seal a public addon Package (root: the helix.vehicle-addon-definition/1 JSON; a tune-only part seals no model), make the add-on Item from that exact Version, and read it back: pinned, the backend fit lists every host, every host's add-on rail lists it. No offer is opened. A CHANGED part is a new Version of the SAME Item: --package-version <semver> with --item <id> (or in the directory that first published it) seals a staged Version and moves the Item to it (the visual check is advisory and never gates the move; re-run the same command to retry one the server refused); sealing a version name that already holds different bytes is refused. --dry-run also runs the seal-side validation (provenance.source <= 256 chars, contentRating, Package shape, version clash). Resumable from <dir>/.helix-publish/ledger.json. Exit 0 = published and verified, 1 = a check or read-back failed, 2 = could not run

helix vehicle addon publish [options] <dir>

helix vehicle publish

Publish a vehicle package directory: validate (package, GLB, host manifest, audio), upload the model and samples, seal a public Vehicle Package whose root pins them, make the vehicle Item from that exact Version, and read it back (pin, package identity, mesh pin, every audio URL, and the host board: hostKind vehicle, sockets, tunable paths). Resumable from <dir>/.helix-publish/ledger.json. With --item: seal a STAGED new Version of that car and move it (the visual check is advisory and never gates the move). Directory: vehicle-package.json + model.glb (asset.extras.HELIX_vehicle with sockets) + WAVs; optional publish.json { title, description, tags, version, contentRating, provenance, hostGrantExtensions }. Exit 0 = published and verified, 1 = a check or read-back failed, 2 = could not run

helix vehicle publish [options] <dir>

helix vehicle pull

Rebuild a publishable COPY of a live vehicle: read the Item's sealed Vehicle Package Version and write vehicle-package.json (the exact sealed root), audio/<file> for every sound it pins, model.glb plus model-<renditionId>.glb for every served mesh rendition, a publish.json carrying the Item fields (the legacy "general" rating is written as "everyone"; a rating that is not one of everyone|teen|mature|adult needs --content-rating) and a pull.json recording where each byte came from. Nothing is uploaded and no ledger is written, so the copy mints a NEW Item instead of resuming against the live one: pull into a new directory, then helix vehicle publish <dir>. Exit 0 = pulled, 1 = nothing written, 2 = could not run

helix vehicle pull [options] <item-id> <dir>