Cultivation World Simulator: an agentic Xianxia world where every cultivator is an LLM

What 4thfever/cultivation-world-simulator actually simulates

The pitch is unusual for a game repository. You do not play a cultivator. The README says you act as the 天道 (Heavenly Dao), watching a world evolve and occasionally intervening, for example by sending down a heavenly tribulation or rewriting a character's mind. The population is the simulation: each cultivator is a separate agent that observes its environment and makes its own decisions.

The stated reason for the rule layer is worth quoting because it is the whole design thesis. The README says the world is built on spirit roots, realms, techniques, personality, sects, pills, weapons, martial tournaments, auctions and lifespan, so that the AI's imagination is constrained inside a plausible cultivation framework. That is a direct response to a known failure of LLM-driven simulations: without hard constraints, agents drift into incoherence. Here the rules are the cage and the model is the inhabitant.

Who is this for? Three groups. People who want to watch emergent narrative instead of playing a scripted one. Developers studying agentic workflow design, since the repository is Python and the whole thing is inspectable. And modders, because the README explicitly frames source deployment as the path for people who want to change code or build on top of it.

The mechanism: rules, agents, and an HTTP boundary

Architecturally the project is a FastAPI backend plus a Vue 3 / TypeScript / Vite frontend, with PixiJS for rendering. The backend is where the world state lives and where the agents are driven; the frontend is a viewer and control panel. The README states the backend is Python 3.10+ and the frontend needs Node.js 18+.

The interesting part is the API surface, because it is the seam between the simulation and anything outside it. The README describes two namespaces it calls stable: read-only queries under /api/v1/query/* and controlled writes under /api/v1/command/*. The documented starting points include GET /api/v1/query/runtime/status, GET /api/v1/query/world/state, GET /api/v1/query/events, a detail endpoint taking type=avatar|region|sect with an id, plus POST /api/v1/command/game/start and the avatar and world command groups.

The README sketches a minimal integration loop: check runtime status, start the game if it has not begun, then read world state and events. It calls this an observe, decide, intervene, observe again cycle, and names external agents and automation scripts as the intended users. That is a real design decision rather than an afterthought: the simulation is exposed as a service first, and the bundled UI is one client of it. If you have ever wanted to point a script at a living world and let it meddle, this is the affordance you would look for.

What the README does not describe is the scheduling model. It does not say whether agents think on a fixed tick, on events, or on demand, nor how many concurrent model calls a running world generates. That is the number that determines your API bill, and it is absent.

Installing Cultivation World Simulator and starting a first world

There are three documented routes. The Epic Games Store desktop build is free and aimed at players who do not want a development environment. Source deployment is recommended for anyone changing code. Docker is a one-command option that the README itself labels untested, which is worth taking at face value.

For source deployment, the README gives three steps: install the Python requirements, install the frontend dependencies, then start the server in dev mode, which brings up both halves.

pip install -r requirements.txt
cd web && npm install && cd ..
python src/server/main.py --dev

In dev mode the frontend development server is started automatically, and the README says to open the address printed in the startup log, usually http://localhost:5173. Before a new game can begin you must configure a model. The README lists DeepSeek, MiniMax and Ollama as the presets available on the settings page, and notes the configuration is saved into the user data directory.

If you prefer containers, the README gives this sequence, and the compose file maps the frontend to port 8123 and the backend to 8002.

git clone https://github.com/4thfever/cultivation-world-simulator.git
cd cultivation-world-simulator
docker-compose up -d --build

After that, the README says the frontend is at http://localhost:8123. Persistence is handled by the CWS_DATA_DIR environment variable, set to /data in the compose file and mapped to ./docker-data on the host, so settings, keys, saves and logs survive a docker compose down followed by up. The backend container also sets CWS_DISABLE_AUTO_SHUTDOWN=1, and a healthcheck polls /api/v1/query/runtime/status every 30 seconds.

For LAN or phone access the README documents setting SERVER_HOST to 0.0.0.0, adding host: '0.0.0.0' to the server block in web/vite.config.ts, and reaching http://<local-ip>:5173 from a device on the same network. It also warns that the mobile UI is not fully adapted. The default host lives in a read-only file, static/config.yml, under system.host.

Where the design creaks

The Docker route is labeled untested in the README. That is an honest label and also a warning: the compose file is the least exercised path, so treat a first run as a debugging exercise rather than a deployment. The healthcheck depends on curl inside the backend image and wget inside the frontend image, which is a detail to check if you build your own images.

The model dependency is the larger constraint. Every cultivator is driven by an LLM, so a running world consumes API calls continuously, and the README does not quantify that. Ollama is offered as a preset, which suggests local inference is viable, but the README does not state a hardware requirement or a model size, so you cannot size a machine from the documentation alone. If you have no model service at all, the project does nothing: the settings page is a gate, not an optional step.

The API namespaces are described as stable, which is a narrower promise than it sounds. The README does not document versioning policy, deprecation windows, or what happens to /api/v1 when v2 arrives. It also does not document rollback of a save, so if you intervene destructively as the Heavenly Dao, assume there is no undo unless you have copied the data directory.

The licence is the other open question. The repository's licence is reported as NOASSERTION, meaning no standard licence identifier was detected. A LICENSE file exists at the top level, but the README does not summarize its terms. If you plan to redistribute a modified build, or ship it inside a commercial product, read that file yourself rather than assuming it matches the repository's open-source framing.

Alternatives and the difference in approach

The closest comparison in the search data is Amazing Cultivation Simulator, a commercial Chinese cultivation management game. The difference is fundamental. Amazing Cultivation Simulator is a deterministic simulation with authored systems and balance: outcomes follow from rules alone, and the same inputs produce the same world. Cultivation World Simulator keeps the rule layer but inserts an LLM inside each agent, so outcomes are generated rather than enumerated. You get unpredictability and prose; you give up reproducibility.

Against a general agent framework, the difference runs the other way. A framework gives you orchestration and no world. This project ships a specific, opinionated world model with spirit roots, realms, sects, auctions and lifespan already defined, and exposes it over HTTP. You inherit a setting rather than building one.

Against the desktop build, source deployment is not an alternative so much as a fork in intent. The Epic build is for playing. The source tree, with its tests directory, pyproject.toml and AGENTS.md, is for people who want to run pytest and change behaviour. If you only want to watch a world, the free desktop build removes the Python and Node setup entirely.

Maintenance, releases and upgrade cost

The repository is not archived. The most recent push was on 2026-08-16, and the latest release, v4.0.1, was published on 2026-08-02, following v4.0.0 on 2026-08-01 and v3.9 on 2026-07-19. That cadence, with two releases inside two days and a patch shortly after, suggests active iteration rather than a frozen snapshot.

Upgrade cost is dominated by the data directory, not the code. Because settings, keys, saves and logs all live under CWS_DATA_DIR, a rebuild of the containers leaves them intact, and a source upgrade leaves them intact too as long as you do not point the new version at a different directory. The README does not document save-format migration between major versions, so the practical approach is to copy ./docker-data before moving from v3.9 to v4.x and keep the old copy until a world loads cleanly.

The dependency footprint is modest and split in two: requirements.txt pulls in requirements-runtime.txt and then adds test and tooling packages such as pytest, pytest-asyncio, pytest-cov, httpx, polib and Pillow. If you only want to run the simulator rather than contribute, the runtime file is the smaller set, though the README's install command uses the full requirements.txt. The test configuration in pyproject.toml excludes web, tools and assets from collection and defines a docker marker for tests needing a local daemon, so container-related tests are opt-in rather than part of a default run.

On licensing, the reported NOASSERTION status means you should open LICENSE before deciding how you can use a fork. Nothing in the README states the terms, and this is not a question the documentation answers.

Editorial conclusion

Adopt it if you want to study or extend an agentic workflow inside a tightly specified world model, and you are comfortable supplying your own model service. Do not adopt it if you want a deterministic simulation you can replay frame by frame, or a game with a designed ending. Before committing, verify three things: that your model provider works from the settings-page presets, that CWS_DATA_DIR points somewhere you actually back up, and that the /api/v1/query and /api/v1/command namespaces cover the interventions you need, because those are the only stable surface the README promises.

Frequently asked questions

Official sources

1. 4thfever/cultivation-world-simulator on GitHub
2. Issues
3. README
4. Releases