# Boost pads (vehicle.boostpads)

Part of the vehicle family: see the [vehicles guide](guide:vehicles) for the cars themselves.

## What it is for

Glowing pads on the ground of an arena or a track. A car that drives over a ready pad with room left in its tank gets boost units, big pads give more than small ones, and the pad is hidden until its cooldown ends. It is a resource to fight for in car-ball, car-sumo and racing games. The kit only places pads and decides who takes them; the boost tank itself belongs to `vehicle.driveable`.

## Turn it on

```text
gripforge_gamekit_install   { project_id: "gkp_…", id: "vehicle.boostpads" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "vehicle.boostpads",
                              config: { "count": 8, "radius": 20, "big": [0, 2, 4, 6], "bigAmount": 100, "smallAmount": 20 } }
```

It requires `vehicle.drive` (installed with `vehicle.driveable`) and `game.engine`. Give the model of a pad in the asset slot `boost_pad`; a ring and a beam are drawn when it is unbound.

## First example

<!-- test: kits/vehicle_boostpads/tests/vehicle_boostpads.rs::pads_are_laid_on_a_circle_with_the_big_ones_marked -->
With `{ "count": 4, "radius": 10, "center": [2, 3], "big": [1] }` the kit lays four pads on a circle of 10 m around `[2, 3]`. The first one (`pad_0`) is straight ahead at `[2, 13]`, the second (`pad_1`, a quarter turn on) is a big pad at `[12, 3]`. Reading `pads()` lists them all as ready.

## Settings and defaults

| Setting | Default | Meaning |
|---|---|---|
| `count` | 6 | Pads laid on the circle, 0 to 64 (ignored when a `boost_pads` collection exists) |
| `center` | `[0, 0]` | Centre of the circle, `[x, z]` in metres |
| `radius` | 15.84 | Radius of the circle in metres |
| `big` | `[0, 3]` | Indexes (from 0) of the circle pads that are big |
| `bigAmount` | 100 | Boost units a big pad gives, 0 to 500 |
| `smallAmount` | 25 | Boost units a small pad gives, 0 to 500 |
| `bigCooldown` | 8 | Seconds before a big pad comes back |
| `smallCooldown` | 4 | Seconds before a small pad comes back |
| `reach` | 2.4 | A car on the ground this close (m) takes the pad |
| `maxHeight` | 2 | A car higher than this above the pad (a jump) passes over |
| `below` | 99 | A car takes a pad only with fewer boost units than this |

Pads can also be documents of the collection `boost_pads`: `{ id, at: [x, z], big }`. When there is at least one valid document (a pair of coordinates), they replace the circle; a document without a pair is dropped.

## Services, events, hooks

- `vehicle.boostpads` (service): `pads()` returns `[{ entity, id, big, ready, cooldown }]`, the cooldown being the seconds left. Use it for a HUD, a minimap or a bot looking for boost.
- `boostpad.taken` (event): a car took a pad, payload `{ pad, vehicle, amount, big }` where `amount` is the units really added.
- `boostpad.ready` (event): a pad is back, payload `{ pad }`.
- `boostpad.take` (hook): asked before a car takes a pad, payload `{ pad, vehicle, amount, big }`; `amount` is mutable and the hook is cancellable (the car passes over and the pad stays).

A pad is an entity of kind `boost_pad` with the component `boostpad` (`{ id, big }`); it carries the tag `hidden` during its cooldown. Only one car takes a pad per tick, the first in the list of `vehicle.drive`. A wrecked car takes nothing. The cooldowns are saved.

## Hooks and modding

A mod can change every setting and the `boost_pads` collection, and tap `boostpad.take`:

```json
{ "id": "rich", "hook": "boostpad.take", "match": { "big": false }, "mul": { "amount": 2 } }
```

## Engines

The kit runs as the same Rust logic on the web and in the native player. It has no presentation module of its own: the pad is drawn from the `boost_pad` slot.

## When it does not do what you expect

| Symptom | Cause and fix |
|---|---|
| A pad does nothing | the car is above `maxHeight`, farther than `reach`, wrecked, or already holds `below` units or more |
| No pad on the ground | `count` is 0, or a `boost_pads` collection without valid `at` replaces the circle |
| The tank does not fill | `vehicle.driveable` is too old: refilling needs `vehicle.drive.refill` (1.10 or later) |

## Limits

Pads only refill the boost of cars; they give no other bonus. The kit does not move pads at run time.

## Versions

Kit 1.0.0 (2026-10-10): pads on a circle or as data, cooldowns, the hook `boostpad.take`.