Library
Zoen — index for agents
Generated by
tools/build-docs-index.mjs. Read this, then load only the files your task needs. Authority: owner instruction → Decisions →packages/game-data/data/*.json→ these docs.
◆Docs (45)
| Doc | What it answers | Words |
|---|---|---|
| Vision & pillars | What Zoen is, who it is for, the five pillars, the MVP scope (levels 1–40) and the bar for "AAA-level" combat in a browser and phone game. | 742 |
| Decisions (ADRs) | Every direction decision with context, choice and consequences. This wiki is the only source; the owner can veto any line. | 8157 |
| Game development guide (read first) | Accepted battle preparation — mana-consuming instant movement priority, researched per-skill locomotion, combo/refund rules, two cameras, mannequin and animation/VFX/world gates, entry-level hardware references, boss music and the first battle slice. Runtime and balance validation remain future work. | 4892 |
| How AI builds Zoen | The exact loop every agent follows — small tasks, tests, logs, token accounting, evidence, reviews — and how the owner stays in control. | 1570 |
| Task card template | Copy this card when splitting milestone work into ≤ 60-minute tasks. Every field is required. | 302 |
| Testing & evidence | The test pyramid for Zoen, exact commands, performance and feel tests, video capture, and what counts as proof at each gate. | 765 |
| Setup before development | Everything to install and verify on the owner's machine before the first game task, with the verification command for each step and what Claude can do alone. | 551 |
| Speed and token efficiency | Where the tokens went in the first three days (measured from the transcripts), the rules and tools that cut the cost of every later task, and the changes that would make game development itself faster — work that can start before Unity is installed, one simulation instead of two, a skill factory, and numeric checks before visual review. Accepted by the owner on 2026-10-06 (ADR-029). | 2292 |
| Development review, round 2 | Second review (2026-10-07) of speed, token use and the AAA bar. Measured — the token rules are written but not enforced (the session that wrote them ran at a 425k median context) and the token ledger is losing its history. Proposed — guards that enforce the rules, twelve direction findings (the largest — confirmed hits arrive a round trip late), and 90 new AAA details in four new areas (network feel, input feel, look and rendering, session flow). Decided by the owner on 2026-10-07 (ADR-031). | 2915 |
| Architecture | Client, servers, shared simulation, protocol and persistence — how the pieces of Zoen fit, which repo folder owns each, and the rules that keep it fair and fast. | 935 |
| Engine & platforms (review) | The engine decision — Unity 6 LTS + URP client for Windows, Android, iOS and Web (browser capped at Low–Mid), Rust servers kept; Unity vs Babylon vs Godot compared. Accepted by the owner in round 6 (ADR-024). | 1065 |
| 1,000 players per map | How one Rust zone process serves 1,000 players and ~4,000 monsters at 20 Hz — spatial hashing, interest management, bandwidth math, prediction, channels, crowd rendering and the load-test plan. | 1705 |
| Performance budgets | Frame, memory, draw-call, triangle, texture, particle, audio, download and network budgets per quality tier, plus the techniques that keep Zoen smooth on browsers and phones. | 1594 |
| Unity development toolkit | Everything that helps agents build the Unity client — batchmode build/test commands, the project skills in zoen/.claude/skills, and the reviewed GitHub tools (Unity MCP, GameCI, Unity samples, Sentry, OpenTelemetry, audio and asset validators) with licence, use and adoption gate. | 3163 |
| Accounts and sign-in | One account for the website and the game — one-tap "Sign in with Google" on the web, the same Google account in the Windows, Android, iOS and Web clients (plus Sign in with Apple on iOS), server-side token verification, Zoen sessions, linking, recovery and the owner's setup steps. | 768 |
| Security, anti-cheat and auto-ban | Security from day one — the server-authoritative base, the security event log, detection rules in three confidence tiers, automatic bans only for certain evidence, the action ladder, rollback, the "Contact us" ban review (review only when a player appeals), rule-quality limits and the red-team tests. | 1003 |
| Updates and auto-patching | How every platform stays up to date — the Windows launcher/patcher (signed manifest, delta downloads, verify, atomic swap, rollback), content updates through Unity Addressables, store updates and the "update required" gate on Android/iOS, and why the browser still needs a version check. | 854 |
| Web platform (site + admin) | How the player site and the staff console run — ports and commands, the local Supabase database, where each kind of data lives, caching and instant publishing, the security model, the AI bug-fix pipeline (Mac first, cloud when the Mac is off), remote access from a phone, the test commands and the known limits. | 1523 |
| Staff console (admin) | Caravan Command, the compact staff console — its 15 modules and which ones use real or demo data, the nine roles and what each can do, approvals and the two-person rule, the automatic anti-cheat with review only on appeal, the GM panel, the rule-based "needs attention" list, and how it works on a phone. | 1067 |
| Combat & controls | Console-style ARPG controls (WASD, the 8-slot Mouse1 chain, Q E Z X C skills or buffs, Shift+Mouse1 attack in place, Mouse1 click-to-walk, tactical ↔ close camera, Mouse2 movement gem), finishers, cast phases, targeting, damage model, the AAA hit-feel stack and the hit-reaction system. | 2059 |
| Skills & builds | The Passive Atlas (paths → weapon masteries), the Codex (8 skill picks, ranks, facets, finishers), self vs team buffs, the 18 builds, combos and payoffs, and the recipe for designing a new skill. | 1937 |
| Leveling to 40 & pacing | Pace (a 24/7 player needs at least 7 days, a typical player about a month), the XP curve, the 5-chapter main story with Auto-Quest, daily loops, catch-up rules and the alpha fast ruleset. | 816 |
| Auto-Hunt & Auto-Quest | Settings, behaviour and safety rules for online Auto-Hunt, 4-hour offline Auto-Hunt (visible actor), Auto-Quest and click-to-travel (auto-walk + auto-mount from the map) — all using the same validated commands as manual play. | 1071 |
| World & map progression | Zoen's world, the 4×4 km Amber Basin with 12 areas, the progression route on the map, waypoints and mounts, monster placement and how the world map shows progress. | 847 |
| Items, crafting & economy | 11 equipment slots incl. jewelry, rarity by affix count with Alt-revealed tiers, the 12 orbs (999 stacks), gems and sockets, refinement to +15, consumables, two materials per monster, vendors, mounts, gold and the Zoe top-up currency. | 1866 |
| Online, social & events | Channels, parties, chat, inspection privacy, duels and the Sand Arena, world boss rewards, the Kiln Depths dungeon and leaderboard, the monthly 16-player Lantern Convoy, stalls and accounts. | 667 |
| Tripo → Blender → Unity (3D pipeline) | How monsters, props and gear get from concept art to game-ready Unity assets — Tripo generates the raw mesh (by API, hands-free), Blender polishes it headless (clean, retopo, UV, rig, LOD), Unity imports it — what the two Tripo bridge add-ons actually do, the API/MCP options, credit and licence guardrails, and the roadmap tasks. | 1221 |
| HUD & interface | The game-like HUD (desktop + mobile) built from the bronze/leather sprite kit, every widget's position and states, the Mouse1 chain bar, the window system (ornate headers, 11-slot equipment), and how the HUD art is produced and tested. | 2772 |
| Alpha test & rulesets | How the closed alpha works — one-time access keys, the live game × multipliers (XP ×140/×70, drops ×10 chance and ×10 quantity, gold ×10; ≈ 1.6 h to 40, verified under 2 h), the drop calculator, versions, and how beta/live switch with one config value. | 635 |
| Public website plan | The player-facing website (apps/site), one of the game's main marketing surfaces — one-tap Google sign-in, showcase, public roadmap, event times, skill and inventory playgrounds, guide, rankings, armory, Caravan Ledger — what it must never show, the data pipeline, a premium design brief for the AI designer, and the build order. | 2237 |
| Character pipeline | Step-by-step, AI-executable pipeline for player characters (5 lineages × 2 genders, 4 origins) — turnaround, base mesh, cleanup, rig, modular armour, textures, LODs, crowd versions, customization — with tests and logs at every stage. | 917 |
| Animation pipeline | Rig contract, clip inventory, how each skill animation is authored from its timing contract (previz → base motion → polish → events), hit-reaction sets per monster family, retargeting, runtime blending, and the tests that keep animation in sync with the server. | 1219 |
| VFX pipeline | How every skill effect is built — layers, techniques (slash meshes, GPU particles, flipbooks, trails, decals), palettes per build, budgets per tier, the Low→Ultra feel stack (debris, shockwaves, camera kick, screen vibrate, haptics), pooling, readability rules, data format and tests. | 1402 |
| Wukong rig, texture and browser demo (test asset) | How the owner's Tripo Wukong model was rigged (Tripo body skeleton + 83 spring bones for antenna feathers, scarf and sashes; feet, scarf and antenna reworked against the owner's walk/run reference videos), coloured from the owner's four turnaround views, animated and shown in a browser demo — commands, rig contract, spring configuration, tests, budget status and next steps. | 2056 |
| Audio & SFX pipeline | Sound design recipe for weighty hits (4-layer SFX), free and legal sources (no ripping), 320 ready prompts (effects, UI, area environment beds and landmark emitters, classic town/GM music and planned special boss themes), processing and loudness targets, buses and ducking, voice limits for 1,000-player crowds, and tests. | 1969 |
| Local Stable Audio SFX | Generate game sound effects locally with Stable Audio 3 Small SFX on Apple Silicon using MLX, including WAV masters, MP3 takes and processed ambience loops. | 1644 |
| Environment pipeline | How the 4×4 km Amber Basin is generated and dressed — deterministic heightmap from world.json, roads and zone masks, splat materials, modular kits, vegetation, lighting per area, streaming, walkability for server + client, and tests. | 1041 |
| NPCs & monsters pipeline | How monsters (20 + elites + 2 bosses) and the 24 NPCs are produced end to end — design data, turnaround, mesh, family rigs, ability + reaction animation sets, AI behaviour trees, telegraphs, tests. | 580 |
| One-skill production gate | The definition of done for a single skill — contract, server, animation, VFX, SFX, reactions, feel, performance, tests and review — with the evidence each item needs. | 467 |
| Art pipeline & requests | How 2D art is requested (Codex-ready briefs), delivered, optimised and tracked; how 2D becomes 3D; naming, provenance and budgets. | 479 |
| AAA detail catalog (polish standards) | The small details that make Zoen feel finished — hit feel, camera, animation, effects, sound, world, enemies, loot, interface, optimisation, comfort and, since round 2, network feel, input feel, look and rendering and session flow — each with a starting standard, the stage it is due in and its proof. Rendered from polish-standards.json. 127 accepted on 2026-10-06 (ADR-028) and 90 more on 2026-10-07 (ADR-031); none implemented. | 1554 |
| GM room (manual testing) | The owner's test space — spawn any monster, elite or boss, static targets with DPS meters, an item forge with exact affixes and tiers, one-click preset builds (level 40, full gear, full Atlas, Codex, hotbar), resets, debug toggles and a network lab. Replaces any custom alpha kit. | 414 |
| Roadmap | Milestones M0–M11 from toolchain to closed alpha, with small tasks, tests, evidence, gates, art dependencies and token estimates. | 258 |
| Changelog (status history, rounds 4–9) | The status notes and round-by-round change lists that used to sit in CONTINUE_HERE.md, moved here on 2026-10-06 so the status file stays short. History only; the current status and next actions are in CONTINUE_HERE.md. | 10443 |
| Licences & third-party assets | Every third-party library, asset, font, sound and clip used by Zoen with its source and licence. Agents append a row whenever they add one. | 1007 |
◆Canonical data (46 files in packages/game-data/data)
| File | Contents |
|---|---|
art-delivered.json | Generated by tools/art-sync.mjs |
art-library.json | Generated by tools/optimize-art.py |
art-requests.json | Generated by scripts/gen-art-requests.mjs |
art-requests.manual.json | Hand-authored art requests (HUD kit, branding, maps, key art, VFX textures, production sheets) |
atlas.json | Generated by scripts/gen-atlas.mjs (deterministic) |
attributes.json | Proposed tuning |
audio-requests.json | Generated by scripts/gen-audio-requests.mjs |
bestiary.json | Region-1 bestiary from data/v4 (IDs/numbers preserved; two bandits renamed per v4 world chapter) |
builds.json | 18 builds = 3 per Atlas path (Iron, Steel, Wind, Storm, Lantern, Jade) |
combat-states.json | Authoritative reaction + state contract |
consumables.json | Potions, elixirs, cleanses, food, scrolls and utility items |
controls.json | Default bindings |
cosmetics.json | Cosmetics catalog (costumes, weapon effects, auras) and the long side questlines that unlock them |
development-standards.json | Pre-development standards, ADR-027 and owner decisions 2026-10-05 |
drop-quantity.json | Every stackable drop rolls a RANDOM quantity (owner, round 7, amends ADR-017): an integer drawn uniformly from min..max when the drop succeeds |
events.json | Team events where every player picks a POSITION when signing up (the classic trade-run job idea: one side carries goods, one escorts, one robs) |
feel-quality.json | Game-feel and VFX quality tiers (presentation only) |
glossary.json | Zoen dictionary |
gm-room.json | GM room: the owner's manual-test space (and the closed-alpha QA kit) |
hud.json | HUD layout contract |
items.json | Items, affixes, orbs, gems and examples |
market.json | The Caravan Market (owner, round 7: amends ADR-018) |
materials.json | Two materials per monster (ADR-017) |
model-delivered.json | Delivery records of the 3D model request log (ADR-033) |
model-requests.json | Generated by scripts/gen-model-requests.mjs (ADR-033) |
model-requests.manual.json | Hand-authored inputs for scripts/gen-model-requests.mjs (ADR-033): polygon budgets, size ranges, Tripo settings, the turnaround sheet layouts and the roadmap need of each kind |
mounts.json | Permanent per-character mounts (ADR-009), bought from Stablemaster Kerem |
netcode.json | Zone server netcode numbers (ADR-003, M1-03): tick budget, fixed-rate scheduler, spatial hash, interest (AOI) sets and channel caps, moved here from docs/tech/NETCODE_1000.md so the zone server (services/zone) reads them from data; the doc explains them |
polish-standards.json | AAA detail catalog: the small presentation and optimisation details that make combat, sound, effects, world and interface feel finished |
progression.json | Generated by scripts/gen-progression.mjs |
quests.json | Main storyline 1→40 (47 quests) |
reference-devices.json | Owner delegated a low-end baseline appropriate to 2026-10-05 |
release.json | Release versioning shown to players (loading screen, login screen, Options → About, bug reports) and on this wiki |
roadmap.json | Single game roadmap |
rulesets.json | Per-phase tunables (ADR-019) |
security.json | Security rules (docs/tech/SECURITY_ANTICHEAT.md) |
sim.json | Shared simulation contract for the zoen-sim crate (M0-03, ADR-024 and ADR-029): fixed tick, integer units, determinism rules and the golden-vector files the C# prediction subset or the client plugin (M0-09, M0-11) must match |
skills.json | Canonical skill list: 18 weapon codices × 7 skills (6 + 1 finisher) + 3 pole codices × 6 buffs (3 self, 3 team) |
stack.json | Technology decisions (ADR-003 servers and protocol, ADR-004 monorepo, ADR-024 Unity client accepted 2026-10-04; written up in docs/vision/DECISIONS.md by M0-06) and the machine setup checklist |
time-weather.json | Day/night cycle and weather contract (ADR-030: accepted by the owner on 2026-10-06, built from day one, with toggles in the GM arena) |
ui-kit.json | Generated by tools/build-ui-sprites.py from accepted UI originals |
ui-windows.json | Layout contract for in-game windows (engine + wiki) |
vendors.json | What each town NPC buys and sells |
weapons.json | Zoen weapon families (18, three per Atlas path) and region-1 bases (levels 1–40) |
web-account.json | Account pages on the official website (apps/site) |
world.json | Region 1 (Amber Basin) world contract |
◆Other entry points
- ../KICKOFF.md — kickoff/resume prompts · ../CLAUDE.md — rules · ../CONTINUE_HERE.md — status
- ../art-requests/MISSING_ART.md — image briefs ·
../logs/tasks.json— task/test/token history
Source: zoen/docs/INDEX.md · 2,813 words · edit the Markdown, not this page.