# corex-zombies

> Server coordinates spawns and macro behavior. Clients run the actual AI for peds near them. Eight distinct zombie types plus a fear/immersion system.

{% hint style="info" %}
**Required:** Core content · **Depends on:** `corex-core` · **Version:** `1.0.0`
{% endhint %}

## Quick Facts

| Dependencies | Server Exports | Client Exports | Built-in types |
| ------------ | -------------- | -------------- | -------------- |
| `corex-core` | 2              | 5              | 8              |

## Overview

Hybrid AI model. The **server** controls population budgets, shared hordes, and broadcasts shared batches. The **client** instantiates peds locally, runs their tasks, and reports back rarely. This keeps server CPU flat with player count while providing consistent behavior.

Ships with a rich config: 8 zombie types, population scaling by distance-from-safe-zone, horde mechanics, fear effects, loot tables, grab mechanic, and per-type animation profiles.

## Quick Start

```cfg
ensure corex-core
ensure corex-zombies
```

## Configuration — high-level groups

### Models & Fallbacks

| Key                           | Default                         | Description                           |
| ----------------------------- | ------------------------------- | ------------------------------------- |
| `Config.LocalClientZombies`   | `true`                          | Use client-local ped ownership        |
| `Config.ForceTrueZombieModel` | `false`                         | Always use `TrueZombieModel`          |
| `Config.TrueZombieModel`      | `'u_m_y_zombie_01'`             | Canonical zombie ped                  |
| `Config.FallbackModels`       | `{...}`                         | Used when a type's model can't stream |
| `Config.FallbackClipsets`     | `{...}`                         | Walk clipset fallbacks                |
| `Config.FallbackAttackDict`   | `'melee@unarmed@streamed_core'` | Attack dict fallback                  |

### RP-style spawning

`Config.RPSpawning`:

| Field                        | Description                                                                    |
| ---------------------------- | ------------------------------------------------------------------------------ |
| `enabled`                    | Master toggle                                                                  |
| `territories`                | Array of named zones with `maxZombies` caps                                    |
| `soundAttraction.categories` | Per-weapon-category attraction ranges (pistol=45m, rifle=70m, explosive=120m…) |
| `environmentalSpawn`         | Cars/dumpsters/buildings spawn points                                          |
| `hordeMigration.interval`    | Ms between migration ticks                                                     |

### Population & Sync

| Key                                           | Default          | Description                                  |
| --------------------------------------------- | ---------------- | -------------------------------------------- |
| `Config.PopulationBudget`                     | `18`             | Baseline zombies in active area              |
| `Config.Sync.MaxGlobalZombies`                | `150`            | Hard ceiling across the map                  |
| `Config.Sync.MaxZombiesPerZone`               | `25`             | Per-zone cap                                 |
| `Config.Sync.ZombieSyncRadius`                | `200.0`          | Sync distance from players (meters)          |
| `Config.Sync.SharedEventHordes`               | `true`           | Enable shared event hordes                   |
| `Config.Spawning.minDistance` / `maxDistance` | `35.0` / `110.0` | Spawn distance band from player              |
| `Config.SafeZoneBuffer`                       | `30.0`           | Meters of no-spawn padding around safe zones |
| `Config.DespawnDistance`                      | `120.0`          | Range beyond which zombies despawn           |

### Population scaling (the fear ramp)

`Config.PopulationScaling.bands` scales spawns by distance from the nearest safe zone:

| Distance | Multiplier |
| -------- | ---------- |
| ≤ 60 m   | 0.25       |
| ≤ 150 m  | 0.55       |
| ≤ 400 m  | 0.80       |
| > 400 m  | 1.00       |

Plus `nightMult = 1.15` and `weatherMult = 1.10`. And `absoluteMax = 24`.

### AI & Combat

`Config.AI` and `Config.ZombieCombat` hold tick rates, ranges, and force values — tune only if you know what they do.

### Zombie types

`Config.ZombieTypes` is the array of 8 profiles. See the [**Zombie Variants guide**](https://github.com/ABUGIZA/corex-docs/blob/main/content/guides/zombie-variants.md) for the full field reference and how to add your own.

### Horde mechanics

`Config.Horde`:

| Field              | Default | Description                             |
| ------------------ | ------- | --------------------------------------- |
| `attractionRadius` | `30.0`  | Meters — sighting broadcast reach       |
| `attractionTTL`    | `8000`  | Ms — how long a sighting pulse persists |
| `swarmRadius`      | `3.0`   | Meters — clustering threshold           |
| `swarmCountMin`    | `3`     | Zombies on player = swarm active        |
| `swarmDamageMult`  | `1.25`  | Damage multiplier while swarming        |
| `knockdownChance`  | `0.25`  | Brute-only chance to ragdoll on hit     |

### Fear & immersion

`Config.Fear` controls: the red screen vignette, heartbeat SFX, eye glow at night, dynamic light casting for specials (electric/burning/toxic), and the safe-zone exit cue. All tunable; most default off for `fearVignetteEnabled`.

### Grab mechanic

`Config.GrabMechanic`:

| Field                | Default | Description                         |
| -------------------- | ------- | ----------------------------------- |
| `enabled`            | `true`  | Master toggle                       |
| `grabDistance`       | `1.7`   | Meters to initiate a grab           |
| `grabChance`         | `0.35`  | Probability on close-range attack   |
| `grabDamage`         | `14`    | Damage per tick while grabbed       |
| `grabDamageInterval` | `900`   | Ms between damage ticks             |
| `escapeRequired`     | `10`    | Button presses to escape            |
| `grabCooldownTime`   | `6000`  | Ms between grab attempts per zombie |

### Loot system

`Config.LootSystem` — rarity tiers (common, uncommon, rare, epic, legendary), each with items and chance. `dropChance = 0.6` is the overall drop rate on a kill.

### Elite-only contexts

`Config.EliteOnlyContexts = { night = true, redzone = true }` — prevents `walker` from spawning at night or in red zones.

### Cleanup

`Config.Cleanup.corpseLifetime = 30000` — Ms before corpses despawn.

### Animation & audio configuration

These blocks drive zombie animations, movement clipsets, and audio cues. Most servers don't need to change them — tune only if you're adding custom animations or debugging AI.

| Key                             | Description                                                                                                                                                     |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Config.Debug`                  | Debug logging master toggle                                                                                                                                     |
| `Config.DebugAnimations`        | Verbose animation state logging                                                                                                                                 |
| `Config.Animations`             | Per-type animation profiles (attack, lunge, movement). Keyed by type id: `walker`, `runner`, `brute`, `grabber`, `electric`, `burning`, `toxic`, `stormbringer` |
| `Config.ZombieMovement.primary` | Per-type walk clipset overrides                                                                                                                                 |
| `Config.ZombieSpawn`            | Spawn animation dict/anim/duration (`anim@scripted@surv@ig2_zombie_spawn@shambler@ / action_02 / 2800ms`)                                                       |
| `Config.ZombieIdle`             | Idle animation pool (array of `{dict, anim, duration}`)                                                                                                         |
| `Config.IdleScenarios`          | GTA world scenarios used for distant zombies (`WORLD_HUMAN_STUPOR`, `WORLD_HUMAN_BUM_STANDING`, etc.)                                                           |
| `Config.AudioBindings`          | Sound cues: `snarl` (sight gained), `grabShriek` (on grab), `heartbeat` (close-range pulse), `distantMoan` (safe-zone exit)                                     |
| `Config.ToxicEffect`            | Cough animation dict/anim, duration, and green screen fade color when a toxic zombie hits you                                                                   |

## Server Exports

### `CreateSharedBatch(spec)`

Internal shared-batch creator. Exposed for cross-resource use.

### `ClearSharedBatch(batchId)`

Removes a shared batch.

## Client Exports

### `GetActiveZombies()`

Returns a list of local zombie peds currently managed by this client.

### `GetZombieCount()`

Integer count of client-local zombies.

### `SpawnZombie(spec)`

Direct client-local spawn.

### `IsPlayerGrabbed()`

Returns `true` if the local player is in a grab state.

### `ForceEndGrab()`

Releases the local player from any grab.

## Events

Server-side (net → server):

* `corex-zombies:server:dropLoot(coords, itemName, amount, rarity, zombieId)` — kill loot drop
* `corex-zombies:server:sharedBatchSpawned(batchId, spawnedZombies)` — client confirms batch spawn
* `corex-zombies:server:sharedZombieDied(batchId, zombieId)` — client reports death
* `corex-zombies:server:requestSharedZoneSync` — client wants current snapshot

Client-side (server → client):

* `corex-zombies:client:spawnSharedBatch(batchId, payload)` — spawn these peds locally
* `corex-zombies:client:adoptSharedBatch(batchId, payload)` — ownership transfer
* `corex-zombies:client:sharedZoneStarted(batchId, data)`
* `corex-zombies:client:sharedZoneStopped(batchId)`
* `corex-zombies:client:sharedZoneSnapshot(snapshot)`
* `corex-zombies:client:forceSpawn(count, typeId)` — admin command path

### Integration hooks with other resources

* `corex-survival:client:zombieHit` — fired on bite to trigger infection flow in corex-survival
* `corex:client:zombieKill` — one-shot announcement of a kill (used by `corex-hud` and your custom UI)

## Troubleshooting

**Zombies slide across the ground after being shot in the leg.** → Speed multiplier ignores ragdoll state. Fix in the speed-control loop to check `IsPedRagdoll(ped)` before applying velocity. Tracked as P0-5.

**Zombies flee or scream like civilians.** → Civilian AI hasn't been disabled on the ped. Apply `SetBlockingOfNonTemporaryEvents(ped, true)` and `SetPedCombatAttributes(...)` after spawn. Tracked as P0-6.

**Population collapses under heavy fire.** → Client batch cleanup is firing faster than spawns. Check `Config.Sync.MaxGlobalZombies` and `Config.PopulationBudget` against your play pattern.

**Peds T-pose for a second after spawn.** → Animation dict not streamed. Custom dicts need `RequestAnimDict` + `HasAnimDictLoaded` before applying.

**Unknown `type` silently spawns walkers.** → The `id` you passed to `CreateSharedBatch` isn't in `Config.ZombieTypes`. Double-check spelling.

## Further reading

* [Guides → Creating Zombie Variants](https://github.com/ABUGIZA/corex-docs/blob/main/content/guides/zombie-variants.md) — full walkthrough for adding types
* [Resources → corex-zones](https://corex-zombies.gitbook.io/corex-docs/resources/world/corex-zones) and [corex-redzones](https://corex-zombies.gitbook.io/corex-docs/resources/world/corex-redzones) — spawn context sources


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://corex-zombies.gitbook.io/corex-docs/resources/world/corex-zombies.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.