▶ Watch the 3-minute intro _(subtitles)

English · 简体中文
One world · A living town · New worlds · Quick start · What's in the box · Vision

MineWorld is an open-source framework for building living digital worlds: towns where people work, talk and remember, whether they are played by you, by simple rules, or by AI. You walk into them in 2D or 3D, with friends, or next to AI agents that follow exactly the same rules you do.

_{One small town, three players at the same moment: one in 2D, one walking it in 3D, and an AI agent.}

This town is not the product. It is one world built with the framework, and you can build your own.

The idea: a physics list for people

Particle physicists don't rewrite their simulator for every experiment. In Geant4 they pick a physics list: which processes act on which particles. MineWorld does the same for people. Entities are the particles, Systems are the processes, and a world's Interaction List picks which ones that world uses. Same engine, different list, different world.

That raises three questions. The rest of this page answers them with real footage.

One world, many players

How do 2D, 3D and AI players share one world without ever disagreeing?

Clients only ask. The server decides by the rules, and says why. Vera says hello to Alice from the doorway, and the server refuses: too_far_away. She walks up, and it goes through. No client holds a rule.

One record, every view. Vera buys a coffee in 3D. The economy System records it, so her wallet in 2D already shows 2000.00 → 1999.20.

3D: buy a coffee at the counter	2D: the same seat, the wallet already changed

A crash can't erase a fact. Every fact lives on the server. Kill it with kill -9 mid-walk, start it again, and the world carries on from the same revision. The client just reconnects.

How it works: one authoritative server, and the life of one action

A town that lives on its own

What keeps the town alive when nobody is playing?

Not a language model. Unplug every model and simple rules still run the town: people go to work, eat, walk home and sleep. This is Market Town at 17:00 with rule controllers only.

Each person runs on a swappable controller: plain rules, a motivated controller that weighs its needs, a language model, an outside agent, or you. Swapping one never touches the world; it is a line in a decisions file.

A model is just one option. Give Alice a local model and tell her some news in 2D. Later, in 3D, she remembers it.

Agents plug in the same way. Claude Code joins over MCP, walks to the counter and buys a coffee, under the same rules as you. Bob watches it happen in 2D.

New worlds, same engine

How do you build a new world without rewriting the engine?

A world is a list of packs on a kernel that never changes. This is the start of the café's real Interaction List:

$ mineworld interactions worlds/market-town --place cafe
interactions  Market Town (market-town)
section  conversation: default (compiled)
section  employment: default (compiled)
section  group-activity: default (compiled)
section  needs:
section  posture: default (compiled)
section  relationships: default (compiled)
section  sleep:
…

A social café lets you sit and chat. Add the economy packs, and the same café becomes a market town that sells coffee. Add a third-party fishing pack, and it is a lake village. The kernel changes by zero lines.

_{Lakeside runs in 2D today; 🚧 its 3D view is in progress.}

Three worlds, one kernel: which packs each one uses

Next come regions linked by train, then markets and institutions, one pack at a time (scope).

Quick start

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

The 3D character models are stored with Git LFS. Install it once:

• macOS: brew install git-lfs
• Linux (Debian or Ubuntu): sudo apt install git-lfs
• Windows: winget install GitHub.GitLFS

git lfs install             # once per computer
git clone https://github.com/yuema137/MineWorld && cd MineWorld
git lfs pull                # fetches the 3D character models
./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, buy · 🚧 the full street, Lakeside in 3D	🧠 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, clips and diagrams in docs/images/readme/ and docs/assets/readme/ were made for this project; the clips are cut from the intro video, whose narration is an AI-generated voice.