Rival drivers

Usage guide of vehicle.rivals: the player's car and bot drivers on a circle, bots that pick a target, ram with boost and stay inside the ring, with settings, the ai.duelist service, events and hook.

Source: module-kits:kits/vehicle_rivals/usage/en.mdView Markdown source

Also read offline — CLI: grip-forge docs vehicle-rivalsMCP tool: gripforge_docs { "topic": "vehicle-rivals" }

Rival drivers for car arenas (vehicle.rivals) #

Part of the vehicle family: see the vehicles guide for the cars themselves.

What it is for #

Provides the cars of an arena match for car sumo, demolition derby or car soccer: the player's car and bot drivers, placed on a circle around the arena centre and facing it. Bots drive through vehicle.drive like any driver: every think seconds each one picks a target (the nearest rival, the player weighed by playerWeight), rams it with boost, and swings back towards the centre near the edge of the ring (the running zone.storm, else ringRadius). Elimination, scoring and the countdown belong to other kits such as objective.knockout, which watches the cars tagged contestant.

Turn it on #

gripforge_gamekit_install   { project_id: "gkp_…", id: "vehicle.rivals" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "vehicle.rivals",
                              config: { "cars": 4, "names": ["You", "Blaze", "Rook", "Vex"], "aggression": 0.7 } }

It requires vehicle.drive (installed with vehicle.driveable), spawn.entities and game.engine. Without vehicle.drive no car is spawned.

First example #

With the default settings the match has three cars. cars() on ai.duelist lists the player's car first (name: "You", bot: false), then Rival 1 and Rival 2 as bots. The player's car carries the tags contestant and player_car, the bots carry rival, and each car has the component rivals.car, for example { seat: 0, name: "You", bot: false }. playerCar() returns the entity of the first one.

Settings and defaults #

Setting	Default	Meaning
`cars`	3	Cars in the match, the player's included (1 to 16)
`player`	`true`	The first car is the player's, seated with a hidden driver; off: bots only
`names`	none	Names by seat (default: `You`, then `Rival 1`...)
`tags`	`["contestant"]`	Tags every car carries
`center`	`[0, 0]`	`[x, z]` of the arena
`spawnRadius`	13.6	Radius of the circle the cars start on
`ringRadius`	22	Radius bots keep inside when no `zone.storm` is running
`aggression`	0.6	From 0 (careful near the edge) to 1 (always rams)
`think`	0.25	Seconds between two choices of target
`playerWeight`	0.8	Bots see the player this many times as close as it is (below 1: they prefer the player)
`spareSeconds`	2	Seconds bots leave a car alone after it came back (`knockout.respawned`)
`cameraDistance`	8.5	Follow camera distance behind the player's car, written to `camera.distance`
`cameraHeight`	3.4	Follow camera height, written to `camera.height`

Services, events, hooks #

ai.duelist (service): cars() lists [{ entity, seat, name, bot, target }]; playerCar() returns the entity of the player's car or null; target(bot) returns the car a bot goes for or null; setTarget(bot, entity) forces a target (null clears it).
rivals.ready (event): the cars are on their marks, once, payload { cars, player }.
rivals.targeted (event): a bot changed its target, payload { bot, target } (empty: back to the centre).
Listens to knockout.respawned.
rivals.target (hook): payload { bot, target, distance }; target is mutable (any contestant still in play; anything else is ignored) and the hook is cancellable: the bot keeps no target and drives back to the centre until its next choice.

Bots are held while objective.knockout counts down, and left alone once eliminated.

Hooks and modding #

{ "id": "hunt_leader", "hook": "rivals.target", "match": { "bot": "e5" }, "set": { "target": "e3" } }

A mod can override cars, names, spawnRadius, ringRadius, aggression, think, playerWeight, spareSeconds, cameraDistance and cameraHeight.

Engines #

The kit runs as the same Rust logic on the web and in the native player. It has no presentation module: the cars are those of vehicle.driveable.

When it does not do what you expect #

Symptom	Cause and fix
No car appears	`vehicle.drive` is not installed
Bots do not move at the start	`objective.knockout` is holding the countdown
Bots ignore the player	`playerWeight` is high; below 1 they prefer the player
Bots drive off the arena	`ringRadius` is larger than the arena, and no `zone.storm` is running

Limits #

Bots only ram and return to the centre: no racing lines and no use of items. They need vehicle.drive cars.

Versions #

Kit 1.0.0 (2026-10-10): cars on a circle, ramming bots, the service ai.duelist and the hook rivals.target.