# Knockout match (match.knockout)

## What it is for

Runs a last-one-standing match on foot or in vehicles: contestants have lives, lose one by falling, leaving a radius, being expelled by a zone or dying, and come back on a circle until none are left.

It needs `game.engine`; installing it brings them in.

## Turn it on

Install the kit in a project, then change a setting (the values shown are its defaults):

```text
gripforge_gamekit_install   { project_id: "gkp_…", id: "match.knockout" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "match.knockout",
                              config: { "tag": "contestant", "players": false } }
```

## First example

The kit has no dedicated test yet; this installs it and sets two of its settings to their defaults.

```text
gripforge_gamekit_install   { project_id: "gkp_…", id: "match.knockout" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "match.knockout",
                              config: { "tag": "contestant", "players": false } }
```

## Settings and defaults

Descriptions come from the kit manifest and stay in English.

| Setting | Type | Default | Range or values | Meaning |
|---|---|---|---|---|
| `tag` | string | `"contestant"` |  | Tag of the entities that play the match. |
| `players` | boolean | `false` |  | Entities tagged player (not driving) are contestants too: the character of a battle royale. |
| `lives` | integer | `3` | 1–99 | Lives of each contestant (1: out at the first fall). |
| `center` | array | `[0, 0]` |  | [x, z] the contestants come back around. |
| `respawnRadius` | number | `8` | 0–500 | Radius of the circle a contestant comes back on (its seat sets where on it). |
| `respawnHeight` | number | `0` | -100–100 | Height a contestant on foot comes back at (a vehicle is put on the ground). |
| `fallY` | number | `-6` | -1000–1000 | Below this height a contestant has fallen. |
| `outRadius` | number | `0` | 0–5000 | Past this distance from the centre a contestant has fallen (0: no limit; a zone kit can do it instead). |
| `outOn` | array | `["zone.expelled", "combat.killed", "vehicle.d…` |  | Events that cost the entity they name (payload entity, target or vehicle) one life. |
| `countdown` | number | `3` | 0–30 | Seconds everybody is held before the match starts (and after restart()). |
| `koSeconds` | number | `1.4` | 0–10 | How long the knockout card shows after a contestant is out. |
| `endGame` | boolean | `true` |  | The end of the match ends the game: game.won when the player is the last one, game.lost when it is out. |
| `feed` | boolean | `false` |  | The HUD lists the last eliminations (who is out, and who or what put it out): a battle royale turns it on. |

## Services, events, variables

- Service `objective.knockout`: state(), contestants() → [{ entity, seat, lives, out, place }], alive(), lives(entity), eliminate(entity, cause?) (one life), knockOut(entity, cause?) (out at once), restart(), held() (true during the countdown).
- Events emitted:
  - `knockout.started` (`contestants`) — The countdown is over: the match is on.
  - `knockout.fell` (`entity`, `cause`, `lives`, `x`, `y`, `z`) — A contestant lost a life (cause: fall, edge, an event topic, script).
  - `knockout.respawned` (`entity`, `x`, `z`, `yaw`)
  - `knockout.eliminated` (`entity`, `cause`, `place`, `left`) — A contestant is out of the match (tagged eliminated).
  - `knockout.finished` (`winner`, `player`, `won`)
  - `game.won` — With endGame: the match ended and the player is the last one in.
  - `game.lost` — With endGame: the match ended with the player out.
- Events listened to: `zone.expelled`, `combat.killed`, `vehicle.destroyed`, `player.died`
- Variables:
  - `knockout.phase` (string) — countdown, play, ko, done
  - `knockout.timer` (number) — Seconds of the countdown or of the knockout card
  - `knockout.lives` (number) — Lives of the player
  - `knockout.rivals` (number) — Rivals still in
  - `knockout.rival_lives` (number) — Lives of the rivals still in
  - `knockout.left` (number) — Contestants still in
- Verbs of the scripting layer:
  - `knockout_eliminate` (action) — The entity loses a life now (a trap, a script).
  - `knockout_over` (condition) — The match has ended.

## Hooks and modding

- Hooks (a game or a mod can intercept them):
  - `knockout.fall` (fields a tap may change: `cost`; cancellable) — A contestant still in is about to lose cost lives (1) for cause (fall, edge, an event topic, script).
  - `knockout.respawn` (fields a tap may change: `x`, `z`, `yaw`) — A contestant with lives left is about to come back at x, z facing yaw (its seat on the respawn circle, facing the centre).
  - `knockout.end` (fields a tap may change: `won`; cancellable) — The match is about to end (the player is out, or one contestant or none is left): winner is the last one in, won whether the player is.
- Moddable settings: `lives`, `center`, `respawnRadius`, `respawnHeight`, `fallY`, `outRadius`, `outOn`, `countdown`, `koSeconds`, `feed`

## Engines

Declared targets: `web`, `rust`. `gripforge kit api match.knockout` lists the exact settings and services of your version.

## Versions

Kit version 1.2.0.