What the new brain does

One hook

How the takeover works

The entire replacement is a single Harmony prefix on Zombie.Update. Each frame, for each zombie, it decides one thing: does the new brain drive this one, or does the stock code run?

Nothing is injected into the zombies themselves. Each brain is a plain managed object keyed by instance id, living alongside the game rather than inside it — so the game’s pooling, networking and death handling never see anything unusual.

Before and after

What actually changes in a round

Two movesets

The six abilities

Straight out of Emerald’s Type 1 / Type 2 weapon system. Every module of every ability — cooldown, condition, damage, crit, damage-over-time, knockback, slow, area-of-effect — is a live config entry with its own tab in the panel.

Type 1 — Claws

The close-in brawling kit.

Type 2 — Frenzy

The mobile pressure kit.

Emerald ActionsClass

The six combat actions

Abilities are what a zombie does to you. Actions are what it does about you — running on Emerald’s ActionsClass loop, each with its own enable switch, odds and cooldown.

Why hits feel consistent

Deterministic melee

The mod opens and closes the game’s damage hitbox itself, at configured fractions of the swing — HitWindowStart and HitWindowEnd — rather than relying on animation events. Each ability sets its own damage on the game’s DamageTrigger immediately before the window opens.

The practical result: armour, downing, kill credit and co-op sync all behave exactly like a stock hit, just with per-ability numbers. And the gap between the two window fractions is literally your dodge window.

Not laziness

What deliberately stays with the game

These are delegated on purpose, because the game already executes them perfectly and replacing them would risk breaking things for no gain.

• Death — ragdoll, drops, endless-mode reset. The brain raises OnDeath and steps aside.
• Barricade climb traversal — the stock mover owns the walk-through. The no-teleport guarantee lives here.
• The grave-rise spawn animation and the entrance choreography before a barricade is assigned.
• Electrocution and fire status ticking — HandleZapStatus keeps the stock stun-and-tick running unmodified, so electric traps work exactly as designed.
• Special and boss zombies, unless you turn on DriveSpecials. Off by default so scripted set-piece rounds play as the developers tuned them.

The one boundary

Online co-op, honestly

Everyone in the lobby can keep the mod installed. It does nothing harmful on machines where it is not driving.

Degrading gracefully

Two safety behaviours worth knowing

For people who know Emerald

How it maps to Emerald AI

Optional

For modders: events and control API

Reference UngodlyEmeraldZombieAI.dll from your own BepInEx plugin and you get the full Emerald events roster, keyed by the game’s own Zombie. Events always fire — the [Events] config section only controls console printing — and a subscriber that throws can never take the AI down.

using UngodlyEmeraldZombieAI.Events;

UngodlyEvents.OnKilledTarget += (zombie, victim) =>
    myLog.LogInfo("Zombie " + zombie.GetZombieId() + " downed a player!");

UngodlyEvents.OnWaveStart += wave => { if (wave == 10) SpawnMyBossEncounter(); };

The control API is a set of safe calls that return false or null when a given zombie has no brain, so you never have to guard them:

EventsManager.SetCombatTarget(zombie, playerData);   // point it at someone
EventsManager.OverrideCombatTarget(zombie, pd);      // lock on, scoring suspended
EventsManager.ClearTargetOverride(zombie);
EventsManager.SetIgnoredPlayer(zombie, pd, true);    // detection skips this player
EventsManager.StopMovement(zombie);                  // freeze pathing in place
EventsManager.ResumeMovement(zombie);
EventsManager.SetDestinationPosition(zombie, pos);   // send it somewhere
EventsManager.KillAI(zombie);                        // via the game's networked damage
bool driven = EventsManager.IsDriven(zombie);

The full roster covers lifecycle, detection, combat, damage, movement, abilities and match events. README.md inside the mod archive lists every signature.

Built for 150+ zombies

Performance model

Brains do a tiny per-frame update. The expensive decision pass is scheduled by distance tier and rationed by a shared budget, so a huge endless wave costs a predictable amount rather than scaling linearly into a stutter.

• Three think tiers — near, mid and far zombies each get their own decision rate. Distant zombies are mostly just walking somewhere, so their rate can be generous. This is the single biggest CPU saver on 100+ zombie waves.
• Two shared budgets — MaxBrainThinksPerFrame caps expensive decision passes per frame; MaxRaycastsPerFrame is one pool every line-of-sight check in the system draws from. Anything that misses its budget simply retries next frame.
• Throttled destinations — path requests are among the most expensive things an agent does, so they are rate-limited and thresholded by how far the target actually moved.
• No allocation on hot paths — no LINQ, cached animator writes, target lookups on a cache timer.

The debug overlay shows both budget pools live, so if you are tuning for framerate you can watch the effect rather than guess at it.

Settings and tuning