zombs.io context for Claude

A self-contained knowledge pack so an AI assistant can do anything with zombs.io — from a 10-line userscript to a full self-hosted, multi-session localhost client with persistent headless bots.

Read the file that matches the task; each is standalone but they cross-link.

File	Use it for
01-game.md	How zombs.io is actually played — mechanics, waves, zombies, bosses, pets, buildings, weapons, parties, base strategy. Building/item costs are the live schema. Read first for any "smart" automation.
02-client-internals.md	The real client: window.game map, state paths, binary protocol, opcodes, the full 40-RPC catalogue and entity schemas — all verified against the live runtime. The hard reference.
03-userscripts.md	Writing browser userscripts (Tampermonkey/Violentmonkey) — boot, hooks, the ZOUI settings-panel library API, and a ctx-style scripting model. Start here for "write me a script".
04-localhost-client.md	Building a self-hosted client: headless Node bots that stay logged in, the MBF/WASM anti-bot solver, per-session protocol, SQLite persistence, attach bridge, A* pathfinding, and a multi-bot upgrade/farm coordinator. The big one.
05-recipes.md	Copy-paste building blocks: auto-farm, auto-heal, auto-aim, auto-respawn, chat spam, grant-sell-perms, clones/multibox, base saver, heal-spell. Each is a complete, live-tested pattern.
06-resources.md	External links, the scripting scene's history, how the pieces fit, and how to re-derive anything from the live game.
07-mbf-anti-bot.md	The MBF anti-bot reversed: the WASM proof-of-work (MT19937→Fisher-Yates→SHA-1→17-bit gate), the browser-attestation probes, the challenge/response opcodes, and how the server validates (it only rechecks the hash gate). Read for headless-client / anti-bot work.
08-authority-and-timing.md	The client↔server authority split reversed: pure server authority (no client prediction), the input scheduler (20 Hz, no field-merge, differential movement), the ~2-tick (~100 ms) interpolation/extrapolation model, and what's predicted vs. authoritative. Read to understand what your inputs/RPCs actually do and when you see results.
09-visibility-and-replication.md	What can you see — the server only streams entities within a measured ~±1300 u area-of-interest (the map is 24000²), via a per-tick delta. game.world.entities is a local window, not the world: no global ESP, entities stream in/out as you move. Read before any "nearest X" / radar / map-wide script.
10-bugs-quirks-and-limits.md	Deep client audit: bugs in the shipped client (canAfford, the broken input throttle, dead occupancy check), the exact placement/refund/pet/spell limits & constants, and behavioral quirks. Read for precise numbers (placement distances, pet evolve levels, 50% refund) and gotchas.
11-telemetry-and-spoofability.md	What the client sends & what's spoofable: client→server is unsigned (only MBF is bound), the real client sends only pings when idle and never sends Metrics, so headless bots shouldn't either. Also flags that banshee/app.js is a modded deob (injected pet-buys, fake Metrics, warm-up inputs).
12-multibot-orchestration.md	Battle-tested fleet cookbook (the operational layer 04 only sketches): range-gated upgrades, approach-tile pathing (never the 2×2 centre), economy-anchored saving (or bots ping-pong), pet-despawn to unjam corridors, ring-slot formation, reconnect/identity, and per-IP scaling. Read before running coordinated bots.
_research-findings-2026-06.md	Raw ground-truth dump (live runtime + deob + codec): full RPC indices/types, every entity schema, live cost tables, deob-vs-live divergences. The provenance; grep it for exact details.

⚠️ The one thing that bites every script

On the live game, game.world.entities is a plain object, and buildings have entityClass: "Prop" (same as trees/stones). So:

// ✅ live-correct
for (const e of Object.values(game.world.entities)) { … }   // not .values()
const b = game.world.entities[uid];                          // not .get(uid)
// buildings: match e.targetTick.model against the building names + check partyId

The older deob bundle (and pre-2026 notes) used a Map + an entityClass === "Building" filter — both throw / never match on the current client.

The 60-second model

• zombs.io is a co-op zombie tower-defense / base-builder. You gather wood + stone, place a GoldStash, ring it with GoldMines (passive gold) + Harvesters, wall it, and fill it with towers. Zombies attack at night, in escalating waves; a boss every 8.
• The browser client is a single global: window.game (a custom PIXI engine). It talks to the server over a binary WebSocket using a compact codec. Almost everything you do is either reading game.ui / game.world state or sending an RPC / input packet.
• Two ways to automate:
  1. Userscript — runs inside the real page, drives window.game directly. Simple, no infra. See 03 + 05.
  2. Self-hosted client — a Node server runs headless bots that solve the anti-bot handshake and stay connected with no browser open; a web dashboard spawns/attaches/coordinates them. See 04.

Provenance / accuracy notes

• The protocol, opcodes, RPC argument shapes, window.game paths, entity schemas, and building/item costs were dumped from the live running client (2026-06: game.network.codec + game.ui.*Schema) and cross-checked against the deob bundle (banshee/public/app.js) and the axiom codec. Raw capture: _research-findings-2026-06.md. Estimates (harvest reach, hitbox radius) are flagged.
• The deob app.js tracks an earlier build than live and has diverged (most importantly world.entities Map→object). Use it for names/architecture; trust the live runtime for shapes.
• Game mechanics/strategy come from the Official Zombs.io Wiki (Fandom) plus play knowledge. The ZOUI API is the upstream library's documented surface.
• zombs.io ships updates; if a path/RPC stops working, dump the live tables directly (see 02-client-internals.md §9).