agentleFS
developerz-aideveloperz-ai/open-mmorpg/CLAUDE.md

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.

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
  1. Very specific:

    Ownership writes → YugabyteDB directly, in a transaction: Never via cache/bus. #1 anti-dupe rule.

    line 19
  2. Very specific:

    Original IP only: Never extract/rip any game asset, name, or table.

    line 22
  3. Very specific:

    Core is compiled (crates/), content is data (content/): If changing a faction needs cargo build, the split is wrong.

    line 26
  4. Distinctive:

    Do not use git worktrees — work directly in this checkout.

    line 111

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

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)

  1. Rust everywhere — server, client (Bevy target), tooling, MCP. The current apps/client is a headless prediction demo; the headful Bevy/wgpu client is not yet implemented (planned: C5/C8) → client batches. engine-core already uses Bevy app/ECS/reflection/time subcrates. Exception: apps/web is Bun+SolidJS (standard web product). → docs/initial-idea/03-tech-stack.md
  2. Server-authoritative, always. Client sends intent, never state.
  3. Ownership writes → YugabyteDB directly, in a transaction. Never via cache/bus. #1 anti-dupe rule. → docs/architecture/04-data-and-consistency.md
  4. Content is data, core is compiled. Factions/classes/quests change with no recompile. → docs/architecture/05-ecs-and-scripting.md
  5. Open formats only — glTF / heightmap / zstd. No proprietary tooling.
  6. Original IP only. Never extract/rip any game asset, name, or table. → docs/initial-idea/01-legal-and-licensing.md
  7. Horizontal from day 1. Autoscaled shards, no realm caps, no queues.

Architecture

  • Core is compiled (crates/), content is data (content/). If changing a faction needs cargo build, the split is wrong.
  • persistence is the only crate that writes ownership. cache currently provides MemoryCache, with no ownership-write API — the dupe path must not compile. The Dragonfly cache backend is not yet implemented (planned: D6) → database batches.
  • sim is deterministic — same inputs → same state (replay, anti-cheat re-sim).
  • ecs-core is pure — types + logic, no I/O. content-schema has 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 currently MemoryCache; 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/expect outside main/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 raw u64.
  • Borrow by default — &str/&[T] over String/Vec.
  • Async end-to-end — tokio::sync, never std::sync::Mutex on 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 use bg-bg text-fg, never raw hex.
  • i18n from day one — every string via t(); missing keys render loudly (⟦key⟧). Dates/money via Intl, 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 tests

bin/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, but codegraph_explore / codegraph explore "…" won't. Rebuild: codegraph init at 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). Then bin/check must 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: protocol ecs-core sim netcode transport persistence cache scripting content-schema errors world engine-core module-api modules
  • apps/* five Rust binaries: gateway shard client (headless prediction demo) mcp worldsvc · separate web (Bun/Solid)
  • packages/* TS shared for web: i18n ui
  • modules/* 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.json
  • assets/* only README.md and manifest.json ship; 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.