Vehicles in your game (vehicle.* kits) #

Driveable cars and ships, getting in and out, damage, upgrades, and the pieces of an arena match. Readable offline: gripforge docs vehicles, or the MCP tool gripforge_docs (topic vehicles).

What it is for #

Turn it on #

gripforge_gamekit_install   { project_id: "gkp_…", id: "vehicle.driveable" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "vehicle.driveable",
                              config: { "handling": "arcade", "maxSpeed": 42, "boost": { "enabled": true, "tank": 100 } } }
gripforge_gamekit_install   { project_id: "gkp_…", id: "vehicle.enter_exit" }
gripforge_gamekit_install   { project_id: "gkp_…", id: "vehicle.damage" }

vehicle.driveable requires input.actions, spawn.entities, world.ground and the host rigid-body physics. vehicle.enter_exit requires a character kit (character.control), vehicle.drive and interaction.use. vehicle.damage, vehicle.doors, vehicle.upgrades and vehicle.boostpads require vehicle.drive. Vehicles spawn from the spawns collection, from a scene instance or from a spawn.request event of kind vehicle. A vehicle needs a model in the slot vehicle_default (and optionally vehicle_variants); a box with four wheels is drawn otherwise.

Controls: vehicle.throttle and vehicle.steer (axes), vehicle.handbrake, vehicle.boost; the controls guide explains how a device maps to them.

Settings and defaults #

vehicle.driveable #

vehicle.enter_exit #

animatedTransitions true (with doors: approach, open, sit, close before driving), entryDuration 1.65 s, exitDuration 1.5 s, enterRadius 3 m, exitOffset (local exit position), ownedTag player_owned (a vehicle without this tag is reported stolen: true, which a wanted-level kit counts). Entry is refused above 1.25 m/s; driving input is locked during a transition and a save during it keeps the phase. The animated entry needs a humanoid rig and the model's Entry_* / Seat_* sockets; without doors or with animatedTransitions: false the seat is taken at once.

vehicle.doors, vehicle.damage #

vehicle.doors: duration (seconds per full travel), hold, autoOnEnterExit, driverDoor; hinges are the gf_door parts of the model (without them the state still runs and nothing moves). vehicle.damage: health 100, collisionScale 1 (damage per m/s of impact), explode true, explosionRadius 6, and on the web deformation true (bounded cosmetic dents), maxDent 0.18 m, effects true (smoke, fire, glow). Stages: smoking at 50 % health or less, burning at 25 % or less (the car loses 5 % of its maximum health per second), wrecked at 0; every other car within the explosion radius takes damage that falls with distance.

vehicle.upgrades, boostpads, rivals #

vehicle.upgrades: stations (kinds of crafting station where modules are fitted, empty: anywhere), reach 8 m, cargoLabel; modules are documents of vehicle_modules: { id, name, slot, stats: { topSpeed, acceleration, grip, ... }, cost: [{ item, count }], requires?, storage?, needs?, unlocked? }. A module must be unlocked, its required modules fitted, a station in reach and its cost in the bag; refusals are unknown, vehicle, locked, requires, station, cost, fitted. vehicle.boostpads: count 6 on a circle (radius, center, big), bigAmount 100, smallAmount 25, bigCooldown 8 s, smallCooldown 4 s, reach 2.4 m; or documents of boost_pads ({ id, at: [x, z], big }). vehicle.rivals: cars 3, player true, spawnRadius, ringRadius, aggression 0.6, think 0.25 s, playerWeight 0.8, tags contestant.

vehicle.spaceship #

A ship is a document of spaceships: { id, name, thrust, maxSpeed, boostSpeed, pitchRate, yawRate, rollRate, hull, shield, shieldRegen, shieldDelay, guns: [{ offset, damage, speed, rate }], size }. Settings: playerShip (the id of a ship the player starts in), cameraDistance 14, cameraHeight 5, minAltitude 0.5, maxAltitude 0 (no ceiling), autoLevel 0.8, collisionSpeed 6, collisionDamage 4, boardReach 4, enemyRange 90, enemyStandOff 14, enemyFireRange 45. Guns fire through combat.projectiles, else combat.ranged; hull and shield are those of combat.core.

Services, events, variables #

• vehicle.drive: vehicles(), speed(entity), setDriver(entity, driver | null), drive(entity, { throttle, steer, handbrake, boost }), refill(entity, units), setModifiers(...). vehicle.damage: health, damage, destroyed, repair, wreck. vehicle.enter / vehicle.exit: enter(vehicle, entity?), current(), exit(). vehicle.doors: set(vehicle, door, open), cycle, state (doors Door_FL, Door_FR, Door_RL, Door_RR).
• Events: vehicle.spawned, vehicle.damaged, vehicle.destroyed, vehicle.collided, vehicle.speed (10 Hz, in km/h and m/s), vehicle.entry.started, vehicle.entered, vehicle.exited, vehicle.exploded, vehicle.stage, vehicle.repaired, vehicle.module_fitted, boostpad.taken, rivals.ready, spaceship.boarded, spaceship.destroyed...
• Variables vehicle.speed (km/h) and vehicle.health. Verbs set_door, unlock_vehicle_module, spawn_spaceship, board_spaceship, leave_spaceship. In engine content an archetype of kind vehicle takes the component vehicle { health?, boost? } and doors { open: [...] }.

Hooks and modding #

{ "id": "locked", "hook": "vehicle.door", "match": { "vehicle": "e12", "open": true }, "cancel": true, "reason": "locked" }

The force model of each tick is not a hook: tune it with the settings and the modifiers. Moddable: the settings above (not size) and the collections vehicle_modules, boost_pads, spaceships.

Engines #

The vehicles run as the same Rust logic on the web and in the native player. vehicle.driveable, vehicle.enter_exit, vehicle.damage and vehicle.doors are also delivered to Godot and Unity as files (a vehicle body with four wheels, the animated entry, the door hinges) and to Unreal through the shared kit library. vehicle.upgrades, vehicle.boostpads, vehicle.rivals and vehicle.spaceship run on the web and in the native player. The dents, smoke and fire are web presentation options; the hooks run in the web and Rust players.

When it does not do what you expect #