# Rival drivers for car arenas (vehicle.rivals)

Part of the vehicle family: see the [vehicles guide](guide:vehicles) 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

```text
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

<!-- test: kits/vehicle_rivals/tests/vehicle_rivals.rs::three_cars_with_the_player_first_by_default -->
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

```json
{ "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`.