# Zombie hordes (enemy.horde)

## What it is for

Slow, numerous enemies driven by data on top of `enemy.ai`: zombie types (walker, runner, brute), ambient shamblers kept around the players and replaced as they fall, waves that grow (at night with `world.daynight`, on a timer without it, or on demand), attraction by noise (gunshots, explosions, running players, any event of the game), an optional infection on a bite, and the end of the game after a number of waves or at the death of the players. Zombie shooters, horde survival, a house to hold at night. Shared concepts of the family are in the [Enemies in your game](guide:enemies) guide.

## Turn it on

```text
gripforge_gamekit_install   { project_id: "gkp_…", id: "enemy.horde" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "enemy.horde",
                              config: { "ambient": 6, "waveMode": "auto", "waveBase": 8, "waveGrowth": 3 } }
```

Needs `enemy.ai`, `npc.core`, `spawn.entities`, `game.engine`; installing the kit brings them along. Companions: `world.daynight` (waves at night) and `combat.core` (the infection deals its damage through it).

## First example

<!-- test: kits/game_engine/host/tests/parity.rs::rust_host_matches_the_typescript_traces (fixture enemy.horde.waves) -->
A timer-driven horde with no ambient crowd: the first wave comes after 1 second with 3 members arriving over 1 second, each wave adds 1, and the game is won once 2 waves are cleared.

```json
{ "config": { "ambient": 0, "waveMode": "timer", "waveFirst": 1, "waveEvery": 30, "waveBase": 3, "waveGrowth": 1,
              "waveMax": 5, "waveSeconds": 1, "winAfterWaves": 2, "spawnMin": 6, "spawnMax": 9, "aggro": 2 } }
```

## Settings and defaults

| Setting | Default | Meaning |
|---|---|---|
| `ambient`, `nightMultiplier` | 6, 2 | Shamblers kept around the players by day (0: none), and the multiplier of the ambient count and of the waves at night. |
| `spawnEvery`, `spawnMin`, `spawnMax` | 3, 18, 36 | Seconds between ambient spawns; a spawn appears at least `spawnMin` and at most `spawnMax` metres from the players. |
| `despawnBeyond`, `maxAlive` | 80, 40 | An ambient shambler farther than this from every player is removed (0: never; wave members stay); most members alive at once. |
| `aggro`, `hearing`, `wander`, `leash`, `shambleSpeed` | 12, 1, 8, 2.5, 0.7 | Distance at which a member notices a player and hunts; multiplier of every noise radius; how far a shambler wanders; a hunter farther than `aggro` x `leash` gives up; share of the walk speed while shambling. |
| `waveMode` | `auto` | `auto` (night with `world.daynight`, else timer), `night`, `timer` (every `waveEvery` seconds) or `manual` (only `wave()` and the action). |
| `waveFirst`, `waveEvery` | 60, 120 | Timer mode: seconds before the first wave and between two waves. |
| `waveBase`, `waveGrowth`, `waveMax`, `waveSeconds` | 8, 3, 60, 20 | Members of the first wave, members added per wave, most members in one wave (before `maxAlive`), and the seconds over which a wave arrives. |
| `winAfterWaves`, `loseOnDeath` | 0, `true` | The game is won once this many waves are cleared (0: endless); it is lost when every player is dead. |
| `finish`, `texts` | `true`, Dawn / Overrun | Without `game.endings`, the kit ends the game itself on an end screen whose texts are `winTitle`, `winText`, `loseTitle`, `loseText`; with it, endings read `horde.result`. |
| `noiseEvents`, `footsteps` | 4 rows, speed 5.5 | Bus events that make a noise where they happen (by default `combat.fired`, `vehicle.exploded`, `fps.bomb_explode`, `stealth.noise`; each row has `topic`, `radius`, `loudness`, `kind`); running players (faster than `speed`) make footstep noise (`radius`, `loudness`, `every`). |
| `infection` | off | `enabled` (false), `chance` (0.2), `seconds` (30), `damagePerSecond` (1): a bite may infect the player, who then takes damage until cured. |

Types are documents of `horde_types`: `id`, `name`, `enemy` (an `enemy.ai` document: speed, health and attacks), `weight` (share in a wave and among the ambient), `fromWave`, `aggro`, `hearing`, `infect`, `wander`, `tags`. A document `{ "id": "new", "extends": "walker" }` inherits an entry.

## Services, events, variables

- Service `enemy.horde`: `types()`, `members({ type?, wave? })`, `spawn(type, at?, { wave?, reason? })`, `wave(count?)`, `waveState()`, `noise(at, radius, { loudness?, kind?, source? })`, `infect(entity, { source?, seconds? })`, `cure(entity)`, `infected(entity)`, `pressure()`, `result()`, `clear()`.
- Verbs and conditions: `horde_wave`, `horde_noise`, `horde_cure`, `horde_clear`, `horde_wave_reached`, `horde_infected`. Component: `horde { "type": "walker" }`.
- Events: `horde.spawned`, `horde.wave`, `horde.wave_cleared`, `horde.noise`, `horde.hunting`, `horde.lost_track`, `horde.killed`, `horde.infected`, `horde.cured`, `horde.won`, `horde.lost`. It listens to `enemy.killed`, `entity.despawned`, `combat.damaged`, `player.died`, `world.phase`.
- Variables: `horde.wave`, `horde.alive`, `horde.remaining`, `horde.night`, `horde.result` (won, lost or empty), `horde.infected`, `horde.infection`.

## Hooks and modding

| Hook | Meaning |
|---|---|
| `horde.spawn` | A member is about to appear; `type` is mutable; cancelled, nothing appears (an ambient spawn is tried again later). |
| `horde.wave` | A wave is about to start with `count` members (night multiplier applied); `count` is mutable; cancelled, no wave. |
| `horde.noise` | A noise is about to attract the shamblers within `radius` x their hearing; `radius` and `loudness` are mutable; cancelled, nobody hears it. |
| `horde.aggro` | A shambler noticed a player and is about to hunt; cancelled, it keeps shambling and is asked again at its next brain tick. |
| `horde.infect` | A bite or a script is about to infect a player; `chance`, `seconds` and `damagePerSecond` are mutable; cancelled, no infection from this hit. |
| `horde.end` | The horde is about to end the game; `result` (won or lost) is mutable; cancelled, the game goes on. |

Every setting and the listed collections are moddable.

## Limits

Runs on the web player and the native player; Godot, Unity and Unreal have no native delivery of this kit. A member is a normal `enemy.ai` enemy: its speed, health and attacks come from the `enemy.ai` document named by the type.

## Versions

Kit 1.0.0; service `enemy.horde` 1.0.0. It relies on `enemy.behaviors` ^1 (from `enemy.ai`), `npc.behavior` ^1, `npc.locomotion` ^1, `spawn.entities` ^1 and `game.engine` ^1.