English · 简体中文
Quick start · The big idea · How it works · What's in the box · Scope · Vision

_{From the street to the café counter, in frames captured from the 3D client.}

3D: walk up to Alice and press E. She remembers what you said.	2D: the same town, the same server, the same menu of actions.

MineWorld is an open-source framework for building a 1:1 digital world, a persistent world of people, places, rules and physics that you can walk into. Games are one use of it. Today it builds living, modular towns, such as a café town and a lakeside village, whose people work, shop, talk, remember and keep living while nobody is logged in. You play them in 2D or 3D, with friends, or alongside AI agents that follow exactly the same rules you do. The full 1:1 scope is the direction, not today's state.

• Compose, don't fork. A world is a list of packs and a few text files. Money, jobs, bodies and weather are each a module. The small kernel never learns what a job is.
• One authoritative world. Every view, every AI character and every outside agent asks the same server. Every change is recorded with its cause, survives a crash, and replays exactly.
• Alive with or without AI. Characters can run on a language model with their own memory, or on a plain script. Unplug every model and the world still works.

The big idea: an Interaction List for people

Particle physicists don't write a new simulator for every experiment. In Geant4 they pick a physics list: which processes act on which particles. MineWorld does the same for a human world. A world's Interaction List says which interactions exist, between whom, under which rules. Same engine, different list, different world.

How it works

The life of one action: what happens when you buy a coffee

Quick start

You need Rust (the right version installs itself) and Godot 4.7 on your PATH.

git clone https://github.com/yuema137/MineWorld && cd MineWorld
./mineworld-2d               # the market town in 2D: click to walk, click a person for a menu
./mineworld-slice --world    # walk into the café in 3D, press E at the counter to talk to Alice

No graphics at all? Run a world for 30 days of game time, or make your own:

cargo run -p mineworld-cli -- run worlds/market-town --headless --seed 7 --days 30
cargo run -p mineworld-cli -- create my-world

To build your own world step by step (two rooms, three people and a shop), follow the guide. Every command in it runs in CI on all three platforms.

Play from a program with clients/agent (Python, or MCP for Claude Code and other agents). Give characters a language model with cognition/lm-controller. Every setting a world can use is in the generated reference.

What's in the box

🧱 Kernel ✅ time, space, events, persistence, replay; deterministic on macOS, Linux and Windows	🧩 18 System Packs ✅ talk, friends, items, shops, jobs, wages, food, bodies, date, weather, and a third-party fishing pack	📜 Interaction List ✅ who may do what to whom, per world, as data
🗺️ 2D client ✅ walk, talk, invite, buy, give, eat, all through server menus	🏙️ 3D client ✅ walk, run, jump, enter the café, talk to Alice · 🚧 the full street, shopping	🧠 AI characters ✅ a local or online model, each person's own memory and forgetting · 🚧 shared memory
🤖 Agents as players ✅ Python library and MCP; the same seat rules as a human · 🚧 remote over HTTP	👥 Play together ✅ invite codes, reconnects, a hosted town that lives while nobody is online	🧬 People with depth 🚧 a curated attribute catalogue, population sampling, optional MatrAIx backend

✅ works on main and is tested · 🚧 designed and being built. Live detail: docs/MVP_STATUS.md.

Scope

The café town is the first composition, not the product. MineWorld is meant to grow into a 1:1 digital world: each new domain, from markets to politics to autonomous driving, arrives as more packs, never as a bigger kernel.

Stage	What	Status
MVP-0	one town that lives, in 2D and 3D, alone, with friends or with agents	✅ mostly built · 🚧 finishing
Next	many towns linked by train, bus and taxi; maps; real terrain and water	🗺 planned (VISION.md §5)
Later	World Creator, a pack ecosystem, public living worlds	🗺 planned
Long-term	trading, markets, politics, autonomous-driving tests	🔭 direction, not commitment (VISION.md §7)

Learn more

• docs/VISION.md: why this exists and where it is going
• docs/ARCHITECTURE.md and docs/CORE_CONCEPTS.md: how the parts fit, and the words we use
• docs/MODULE_SPEC.md: how to write packs, including the Interaction List
• docs/reference/: every field a world may set, generated from the code

Built with Rust · Godot 4.7 · Python · SQLite · the Model Context Protocol.

Contributing. Read CLAUDE.md and docs/ENGINEERING_RULES.md; python3 scripts/ci_layer.py fast runs the quick checks. If you want worlds like this to exist, a ⭐ helps other people find the project.

License

MIT, except the Blender scripts in clients/3d-spike/tools/blender/ (GPL-2.0-or-later, because they use Blender's GPL interface). Art from other people is CC0. Where every piece of art came from, including the parts made with AI tools, is listed in NOTICE. The screenshots and diagrams in docs/images/readme/ and docs/assets/readme/ were made for this project.