Cultivation World Simulator
A rule-bound, LLM-driven simulator for observing and steering an evolving Xianxia world.
Per-dimension scores and reasoning
Evidence shows the project provides external control APIs (/api/v1/query/* and /api/v1/command/*), distinguishing read-only and controlled writes, reflecting least privilege. User confirmation: game startup requires model configuration, but not all sensitive operations have explicit user confirmation. Data flow transparency: README describes data persistence to user data directory, but not detailed data flow. Sensitive data handling: settings and keys stored in user data directory, but no encryption mentioned. Dependency security: requirements.txt lists dependencies, but no version pinning or security audit. External effects: simulator may make external API calls, but no explicit restrictions. Rollback: save/load feature exists, but no rollback mechanism described. Source attribution: README lists contributors, but not per-file source.
Self-consistency: README and code structure are consistent, tests exist, but not run. Dependency availability: requirements.txt and package-lock.json exist, but not verified. Failure messages: API returns structured errors, but no detailed failure handling docs.
Audience and scenarios: README targets players and developers, provides multiple deployment methods. Capability boundaries: README describes core features, but not limitations. Trigger precision: external API has clear namespaces, but not detailed trigger conditions. Environment fit: supports Docker, source, desktop, but mobile UI not fully adapted.
Information architecture: README is well-structured with TOC and feature list. Install notes: provides source, Docker, and desktop install steps. Naming stability: API namespaces stable, but no versioning policy. Examples and FAQ: README provides API examples, but no FAQ. Known limitations: README mentions mobile not fully adapted, but not comprehensive. License: LICENSE file is CC BY-NC-SA 4.0, but metadata says NOASSERTION. Versioning/changelog: no CHANGELOG provided. Maintenance responsibility: README lists contributors, but not explicit maintainer.
Output usability: provides API and frontend, output format clear. Marginal value: unique AI-driven simulator, innovative. Cost-benefit: free and open source, but requires LLM service configuration, cost depends on user.
Claim traceability: feature list in README lacks specific implementation evidence. Cross-source corroboration: tests and CI config exist, but not independently verified. Fact-inference separation: README descriptions are mostly assertions, not distinguishing facts and inferences.
- License metadata is NOASSERTION, actual LICENSE is CC BY-NC-SA 4.0, need to confirm compliance.
- Dependencies are not version-pinned, posing supply chain risk.
- Sensitive data (e.g., API keys) storage lacks encryption details.
- Mobile UI not fully adapted, may affect some users.
What does this agent do, and when should you use it?
Cultivation World Simulator is an AI-agent-workflow-based Xianxia simulation in which the player acts as a world-level observer and intervenor. Individual cultivator NPCs combine rules with LLM-driven behavior, including personality, memory, relationships, goals, and decisions; sects also have organizational-will AI. The repository combines a Python/FastAPI backend with a Vue 3, TypeScript, Vite, and PixiJS frontend, and offers source development, Docker deployment, and an Epic Games Store desktop edition. Model presets such as DeepSeek, MiniMax, and Ollama are configured in the application settings, while query and controlled-command APIs support external automation. Its outputs are evolving world state, events, character and organization details, and simulation-generated narrative snippets.
Running python src/server/main.py --dev starts the application’s development services; on first use, a model preset is selected and saved in the settings page before a new game begins. The simulator runs rules for maps, time, events, tiles, regions, sects, realms, items, and lifespan, while character AI handles long-term planning, immediate responses, dialogue, thought, and interaction. An external program can call GET /api/v1/query/runtime/status, use POST /api/v1/command/game/start when no game is active, and read data from /api/v1/query/world/state, /api/v1/query/events, and /api/v1/query/detail. It can then make controlled interventions through /api/v1/command/avatar/* or /api/v1/command/world/*; successful responses typically use { "ok": true, "data": {} }, while errors expose detail.code and detail.message.
- A developer changing simulation behavior or debugging the stack can run the source development mode with Python 3.10+ and Node.js 18+.
- A player who wants to observe unscripted Xianxia stories shaped by characters, sects, relationships, and world events can use the desktop edition or Docker deployment.
- A developer building an observe-decide-intervene-observe loop can automate against the
/api/v1/query/*and/api/v1/command/*endpoints. - A self-hosting user with their own model service can select presets such as DeepSeek, MiniMax, or Ollama in the settings UI.
- A local maintainer who needs quick reference material for world data, actions, or sects can generate a helper wiki with
tools/wiki.
What are this agent's strengths and limitations?
- Combines an LLM layer with a detailed rule system spanning spiritual roots, realms, techniques, sects, equipment, lifespan, and world events.
- Offers both a visual game interface and stable query/command API namespaces for interactive play and scripted interventions.
- Documents presets for DeepSeek, MiniMax, and Ollama, plus flexible custom LLM endpoint configuration.
- Provides three delivery paths: source development, persistent Docker deployment, and a desktop edition on the Epic Games Store.
- Initial use requires an available model service; the supplied material does not document model costs, quotas, or provider credential requirements.
- The Docker one-command deployment is explicitly labeled untested in the documentation.
- The mobile UI is not fully adapted and is presented as experimental.
- The supplied material does not describe authentication, authorization, or network-exposure security for the external-control API.
How do you install or deploy this agent?
For source development:
pip install -r requirements.txt
cd web && npm install && cd ..
python src/server/main.py --devYou need Python 3.10+, Node.js 18+, and an available model service. On first entry, configure a model preset such as DeepSeek, MiniMax, or Ollama in Settings, then start a new game; the frontend is usually at http://localhost:5173. For Docker: git clone https://github.com/4thfever/cultivation-world-simulator.git, enter the repository, run docker-compose up -d --build, then open http://localhost:8123.
How do you use this agent?
Start the application, confirm the model configuration in Settings, and create a new game. Use the frontend to inspect the map, characters, sects, events, and ongoing simulation, with world-level interventions including heavenly tribulations and mind-related changes. For external control, request GET /api/v1/query/runtime/status; if needed, send POST /api/v1/command/game/start; query world/state, events, or detail; then send an appropriate /api/v1/command/avatar/* or /api/v1/command/world/* request. Re-query after every write instead of inferring the result from local cache.
How does this agent compare with similar options?
The README positions the project as an immersive product rather than a purely research-oriented “Stanford town” approach, and contrasts it with cultivation games based on preset scripts or simple rule-state machines.
FAQ
Does this require a paid model provider?
Can an external script change the world?
/api/v1/command/* for controlled writes and /api/v1/query/* to inspect state. The documented flow is to query again after a write rather than infer results from local cache.How should API errors be handled?
detail.code and detail.message fields for programmatic handling.Does Docker preserve game data?
CWS_DATA_DIR=/data persists settings, keys, saves, and logs to ./docker-data on the host, so the data remains after bringing the Compose stack down and up again.