open-mmorpg
CLAUDE.md17 starsChanged 6 days agoMITView on GitHub
The best open-core MMORPG engine · Rust (server + client) · Bun/SolidJS operator web · original IP · MIT · AI-native. Server-authoritative, horizontally scaled, data-driven, moddable.
- Reads credentials
In this repositoryOne other file it gives its agents.
- merge-prSkill
The file
We split this CLAUDE.md into the rules it gives an agent
4 rules. About 0 are common, 1 is distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 19
Ownership writes → YugabyteDB directly, in a transaction: Never via cache/bus. #1 anti-dupe rule.
- Very specific: line 22
Original IP only: Never extract/rip any game asset, name, or table.
- Very specific: line 26
Core is compiled (
crates/), content is data (content/): If changing a faction needs cargo build, the split is wrong. - Distinctive: line 111
Do not use git worktrees — work directly in this checkout.
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Open-MMORPG
The best open-core MMORPG engine · Rust (server + client) · Bun/SolidJS operator web · original IP · MIT · AI-native. Server-authoritative, horizontally scaled, data-driven, moddable.
Response Rules
- Execute. No preamble, no "I'll start by…", no restating the task.
- Lead with the action or answer. Reasoning after, only if non-obvious.
- Parallel tool calls when independent. Read before speculating.
- Disagree when the user is wrong. State the correction.
- Terse. Fragments OK. Code/commands/paths stay exact.
- End: 1–2 sentence summary max.
<a name="standards"></a>Standards — read before non-trivial work
This repo follows developerz-ai gold standards: ../gold-standards-in-ai/docs/. Defaults from there apply unless a doc here overrides. Highest-value: 00-philosophy.md, stack/rust-apis.md, architecture/solid-srp.md, writing-for-agents/.
Binding decisions (do NOT re-litigate)
- Rust everywhere — server, client (Bevy target), tooling, MCP. The current
apps/clientis a headless prediction demo; the headful Bevy/wgpu client is not yet implemented (planned: C5/C8) → client batches.engine-corealready uses Bevy app/ECS/reflection/time subcrates. Exception:apps/webis Bun+SolidJS (standard web product). →docs/initial-idea/03-tech-stack.md - Server-authoritative, always. Client sends intent, never state.
- Ownership writes → YugabyteDB directly, in a transaction. Never via cache/bus. #1 anti-dupe rule. →
docs/architecture/04-data-and-consistency.md - Content is data, core is compiled. Factions/classes/quests change with no recompile. →
docs/architecture/05-ecs-and-scripting.md - Open formats only — glTF / heightmap / zstd. No proprietary tooling.
- Original IP only. Never extract/rip any game asset, name, or table. →
docs/initial-idea/01-legal-and-licensing.md - Horizontal from day 1. Autoscaled shards, no realm caps, no queues.
Architecture
- Core is compiled (
crates/), content is data (content/). If changing a faction needscargo build, the split is wrong. persistenceis the only crate that writes ownership.cachecurrently providesMemoryCache, with no ownership-write API — the dupe path must not compile. The Dragonfly cache backend is not yet implemented (planned: D6) → database batches.simis deterministic — same inputs → same state (replay, anti-cheat re-sim).ecs-coreis pure — types + logic, no I/O.content-schemahas pure types/validation and byte-based manifest parsing, but its split-tree loader performs filesystem I/O to load and validate the committed datapack.- Wire types live in
crates/protocol— single source of truth server↔client. - Target topology: edge →
gateway→shard(s) → cross-shard bus +worldsvc; state in Yugabyte (durable) + Dragonfly (ephemeral). The cache implementation is currentlyMemoryCache; the Dragonfly cache backend is not yet implemented (planned: D6) → database batches. Docker already provisions Dragonfly. →docs/architecture/02-server-topology.md
Coding Rules
Think before coding
- State assumptions. Uncertain → ask, don't guess. Multiple readings → present them.
Simplicity first
- Minimum code that solves the stated problem. No speculative abstraction/config. No handling of impossible cases.
Surgical changes
- Touch only what the task requires. Match existing style. Every changed line traces to the request.
Goal-driven execution
- Convert tasks to verifiable goals: bug → reproducing test → make it pass. Plan multi-step as
step → verify: check.
Rust conventions (hard)
- No
unwrap/expectoutsidemain/tests — a hot-path panic drops every player on the shard. - Typed errors (
thiserror), stable client codes; never leak credentials/internal detail in errors or logs. - Newtypes over primitives —
AccountId,ItemId, not rawu64. - Borrow by default —
&str/&[T]overString/Vec. - Async end-to-end —
tokio::sync, neverstd::sync::Mutexon the request/tick path. - Files ≤300 LOC. One crate = one reason to change. SOLID/SRP.
- Make illegal states unrepresentable — the type system is the first anti-cheat layer.
apps/web conventions (Bun + SolidJS)
- TypeScript strict (no
any), Zod at every boundary, custom typed errors. - SRP — one component/one job, ≤300 LOC; shared UI →
packages/ui. Thin routes; data in TanStack Query hooks. - Dark theme ONLY — no toggle. Semantic CSS-variable tokens by role, defined once in
:root. Components usebg-bg text-fg, never raw hex. - i18n from day one — every string via
t(); missing keys render loudly (⟦key⟧). Dates/money viaIntl, not i18n. - →
docs/architecture/09-operator-web.md
Commands
The bin/* shims invoke the Bun TypeScript scripts in scripts/.
bin/setup # check prereqs → Bun deps → Rust build → optional Docker → Playwright browsers
bin/dev [target] # default/all: gateway + shard + web
bin/check # Rust fmt/clippy/all-feature tests + content validation/schema bench compile + web lint/typecheck/Bun tests/build
bin/fmt # cargo fmt + biome --write
cargo nextest run # Rust tests (fast)
cargo clippy --all-targets -D warnings
bun run --filter @omm/web test # web testsbin/setup attempts to start Yugabyte + Dragonfly when Docker is available; it does not run migrations. bin/dev accepts gateway, shard, worldsvc, client, web, or all. Rust targets use cargo run, without automatic reload; the web target uses its dev server.
bin/check is the local gate: Rust fmt, all-feature clippy/tests, content validation and content-schema benchmark compilation (not execution), plus web lint/typecheck/Bun tests/build. It does not run Playwright browser tests, and no committed Git hook setup invokes it. CI runs its own workflow commands and additionally runs live-Postgres integration tests; a green local gate is not proof that CI passed.
Clone setup (AI agents — read on a fresh checkout)
Local agent tooling is git-ignored (per-developer, regenerated — never committed). After git clone, bootstrap it yourself; a fresh tree won't have it:
.codegraph/— CodeGraph symbol index. Absent → grep/Read still work, butcodegraph_explore/codegraph explore "…"won't. Rebuild:codegraph initat the repo root (picked up live, no restart). Prefer it over grep once present (→ global CLAUDE.md § CodeGraph)..claude-task-master/— Task-master local state. Regenerated by the tool; nothing to restore.- App deps + services — run
bin/setup(checks prerequisites → installs Bun deps → warms the Rust build → optionally starts Docker Yugabyte+Dragonfly → installs Playwright browsers; no migrations). Thenbin/checkmust pass before you touch code. - Secrets —
.env*are git-ignored; never commit real secrets.
Layout (target — see docs/architecture/01-monorepo-layout.md)
crates/*14 Rust libs:protocolecs-coresimnetcodetransportpersistencecachescriptingcontent-schemaerrorsworldengine-coremodule-apimodulesapps/*five Rust binaries:gatewayshardclient(headless prediction demo)mcpworldsvc· separateweb(Bun/Solid)packages/*TS shared for web:i18nuimodules/*COMPILED gameplay modules — fork adds features w/o core edits;bin/new-module <name>scaffolds one (→docs/architecture/10-modules.md)content/*data-driven game content (no recompile) +manifest.jsonassets/*onlyREADME.mdandmanifest.jsonship; referenced placeholder payloads are absent. glTF / heightmaps / textures / audio directories, AI generation, zstd delivery and hot-swapping are planned, not shipped.docs/*initial-idea/(spec) ·architecture/(design +decisions/ADRs)
Where to look (load on demand)
- What & why (the spec) →
docs/initial-idea/README.md - How it's built (design) →
docs/architecture/README.md - Monorepo layout →
docs/architecture/01-monorepo-layout.md - Netcode / sharding →
docs/architecture/03-netcode-and-sharding.md - Anti-dupe / consistency →
docs/architecture/04-data-and-consistency.md - Modding / ECS / scripting →
docs/architecture/05-ecs-and-scripting.md - Compiled modules (fork DX) →
docs/architecture/10-modules.md - Operator website →
docs/architecture/09-operator-web.md - Org standards →
../gold-standards-in-ai/docs/
Planning
Non-trivial work → write a multi-file plan under docs/plans/<YYYY>/<MM>/<DD>/<1NN>-<slug>/ (overview + slices + status.yml), then execute. → ../gold-standards-in-ai/docs/workflow/project-kickoff.md
Rules
SOLID/SRP. Tests always. Surgical diffs. Original IP only. Ownership → Yugabyte transaction, never cache.
Note
Do not use git worktrees — work directly in this checkout. If a task is big enough to need subagents, run them as a team in this same checkout: split the work into disjoint pieces so no two agents touch the same files.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

