简体中文 · 繁體中文 · English · Tiếng Việt · 日本語 · Français

— ✦ —

# Cultivation World Simulator ![GitHub stars](https://img.shields.io/github/stars/4thfever/cultivation-world-simulator?style=social) [![LINUX DO](https://img.shields.io/badge/LINUX.DO-Community-2EA44F)](https://linux.do/t/topic/2439437) [![Bilibili](https://img.shields.io/badge/Bilibili-Watch_Video-FB7299?logo=bilibili)](https://space.bilibili.com/527346837) ![QQ Group](https://img.shields.io/badge/QQ%20Group-1071821688-deepskyblue?logo=tencent-qq&logoColor=white) [![Discord](https://img.shields.io/badge/Discord-Join%20Us-7289da?logo=discord&logoColor=white)](https://discord.gg/3Wnjvc7K) [![Epic Games Store](https://img.shields.io/badge/Epic%20Games%20Store-Get%20It%20Free-313131?logo=epicgames&logoColor=white)](https://store.epicgames.com/p/ai-cultivation-world-simulator-adebb8) ![Python](https://img.shields.io/badge/Python-3.10%2B-blue?style=flat&logo=python&logoColor=white) ![FastAPI](https://img.shields.io/badge/FastAPI-005571?style=flat&logo=fastapi&logoColor=white) ![Vue](https://img.shields.io/badge/Vue.js-3.x-4FC08D?style=flat&logo=vuedotjs&logoColor=white) ![TypeScript](https://img.shields.io/badge/typescript-%23007ACC.svg?style=flat&logo=typescript&logoColor=white) ![Vite](https://img.shields.io/badge/vite-%23646CFF.svg?style=flat&logo=vite&logoColor=white) ![PixiJS](https://img.shields.io/badge/PixiJS-E72264?style=flat&logo=pixijs&logoColor=white)

Game Demo

> **Act as the "Heavenly Dao" and observe a cultivation world simulator driven by rule systems and AI as it evolves on its own.** > **Fully LLM-driven with emergent ensemble storytelling, now available for free on the Epic Games Store, and also suitable for Docker deployment, source development, and secondary creation.**

4thfever%2Fcultivation-world-simulator | Trendshift

## 📖 Introduction This is an **AI-driven cultivation world simulator**. In the simulator, every cultivator is an independent Agent who can freely observe the environment and make decisions. At the same time, to avoid AI hallucinations and excessive divergence, a complex and flexible cultivation worldview and operating rules have been incorporated. In a world woven by rules and AI, cultivator Agents and sect wills compete and cooperate with each other, and new exciting plots constantly emerge. You can quietly observe the changes of the world, witness the rise and fall of sects and the rise of geniuses, or bring down heavenly tribulations or modify minds to subtly intervene in the world's progress. ### ✨ Core Highlights - 👁️ **Play as "Heavenly Dao"**: You are not a cultivator, but the **Heavenly Dao** who controls the rules of the world. Observe all walks of life and experience their joys and sorrows. - 🤖 **Fully AI-driven**: Every NPC is independently driven by LLM, with unique personality, memory, interpersonal relationships, and behavioral logic. They will make decisions based on the immediate situation, have love and hate, form cliques, and even change their fate against the heavens. - 🌏 **Rules as the Foundation**: The world runs on a rigorous system composed of spiritual roots, realms, cultivation methods, personalities, sects, elixirs, weapons, martial arts tournaments, auctions, lifespans, and other elements. AI's imagination is limited within a reasonable and rich cultivation logic framework, ensuring the world is authentic and credible. - 🦋 **Emergent Plot**: Even the developers don't know what will happen in the next second. There is no preset script, only world evolution woven by countless causes and effects. Sect wars, the struggle between righteous and demonic, and the fall of geniuses are all independently deduced by the world logic.

Sect System

City Region

Event History

Character Panel

Personality & Equipment

Independent Thinking

Nicknames

Dungeon Exploration

Character Info

Elixirs/Treasures/Weapons

## 🚀 Quick Start ### Recommended Method - **Want to modify code or debug**: Use source code deployment and prepare Python `3.10+`, Node.js `18+`, and available model services. - **Want to play directly**: Get the desktop version for free on the [Epic Games Store](https://store.epicgames.com/p/ai-cultivation-world-simulator-adebb8), or use one-click Docker deployment. - For a quick reference wiki on world info, actions, sects, and more, generate the local helper site in `tools/wiki`. ### First Launch Instructions - When using the Epic desktop version, launch the game and confirm the model configuration as prompted on the settings page before starting a new game. - When using source code or Docker, after entering for the first time, you need to configure available model presets (such as DeepSeek / MiniMax / Ollama) on the settings page before starting a new game. - In development mode, the frontend page usually opens automatically; if it doesn't, please visit the frontend address shown in the startup logs. ### Method 0: Epic Games Store Desktop Version Suitable for players who just want to play without setting up a development environment. 1. Get and install it for free from the [Epic Games Store](https://store.epicgames.com/p/ai-cultivation-world-simulator-adebb8). 2. After launching the game, confirm the model configuration as prompted on the settings page, then start a new game. 3. If you want to use your own model service, switch to presets such as DeepSeek / MiniMax / Ollama on the settings page. ### Method 1: Source Code Deployment (Development Mode, Recommended) Suitable for developers who need to modify code or debug. 1. **Install dependencies and start** ```bash # 1. Install backend dependencies pip install -r requirements.txt # 2. Install frontend dependencies (requires Node.js) cd web && npm install && cd .. # 3. Start service (automatically pulls up frontend and backend) python src/server/main.py --dev ``` 2. **Configure Model** After selecting a model preset (such as DeepSeek / MiniMax / Ollama) on the frontend settings page, you can start a new game. The configuration will be automatically saved to the user data directory. 3. **Visit Frontend** Development mode will automatically pull up the frontend development server. Please visit the frontend address shown in the startup logs, usually `http://localhost:5173`. ### Method 2: Docker One-click Deployment (Untested) No environment configuration required, just run directly: ```bash git clone https://github.com/4thfever/cultivation-world-simulator.git cd cultivation-world-simulator docker-compose up -d --build ``` Visit frontend: `http://localhost:8123` The backend container persists user data through `CWS_DATA_DIR=/data`, including settings, secrets, saves, and logs. It is mapped to the host's `./docker-data` by default, so this data will be retained even if `docker compose down` is executed and then `up` again.

LAN/Mobile Access Configuration (Click to expand)

> ⚠️ Mobile UI is not fully adapted yet, for early access only. 1. **Backend Configuration**: It is recommended to start the backend through environment variables, for example, execute `$env:SERVER_HOST='0.0.0.0'; python src/server/main.py --dev` in PowerShell. If you need to change the default value, you can edit the read-only configuration `system.host` in `static/config.yml`. 2. **Frontend Configuration**: Modify `web/vite.config.ts` and add `host: '0.0.0.0'` in the server block. 3. **Access Method**: Ensure the phone and computer are on the same WiFi, and visit `http://:5173`.

External API / Agent/Claw Access (Click to expand)

This part is suitable for external agent / Claw access, automation scripts, or achieving a closed-loop gameplay of "observation -> decision -> intervention -> re-observation". It is recommended to develop directly around stable namespaces: - Read-only Query: `/api/v1/query/*` - Controlled Write: `/api/v1/command/*` Common starting endpoints: - `GET /api/v1/query/runtime/status` - `GET /api/v1/query/world/state` - `GET /api/v1/query/events` - `GET /api/v1/query/detail?type=avatar|region|sect&id=` - `POST /api/v1/command/game/start` - `POST /api/v1/command/avatar/*` - `POST /api/v1/command/world/*` The minimal access process is usually: 1. First call `GET /api/v1/query/runtime/status` to determine the current running state. 2. If the game has not started, call `POST /api/v1/command/game/start` to initialize. 3. Use `world/state`, `events`, and `detail` to pull world snapshots and target information. 4. Call a `command` to perform an intervention according to the strategy. 5. `query` again after intervention, do not rely on local cache to infer results. When the interface is successful, it usually returns: ```json { "ok": true, "data": {} } ``` When it fails, it will return a structured error, and you can read `detail.code` and `detail.message` for program judgment. Additional notes: - Application settings are still managed through `/api/settings*` and `/api/settings/llm*`. They belong to the source of truth for settings and do not belong to the external control compatibility layer. - For a more complete interface list, layered design, and extension conventions, please refer to `docs/specs/external-control-api.md`.

### 💭 Why make this? The world in cultivation web novels is wonderful, but readers can only ever observe a corner of it. Cultivation genre games are either completely preset scripts or rely on simple rule state machines designed by humans, with many far-fetched and unintelligent performances. After the emergence of large language models, the goal of making "every character vivid" seems reachable. I hope to create a pure, happy, direct, and living sense of immersion in the cultivation world. It's not like a pure publicity tool for some game companies, nor like a pure research like Stanford Town, but an actual world that can provide players with real sense of substitution and immersion. ## 📞 Contact If you have any questions or suggestions for the project, welcome to submit an Issue. - **Bilibili**: [Click to Follow](https://space.bilibili.com/527346837) - **QQ Group**: `1071821688` (Answer to join: 肥桥今天吃什么) - **Discord**: [Join Community](https://discord.gg/3Wnjvc7K) --- ## ⭐ Star History If you find this project interesting, please give us a Star ⭐! This will motivate us to continuously improve and add new features.

# Sharing Thanks to contributors for sharing this repo and related projects. - [cultivation-world-simulator-api-skill](https://github.com/RealityError/cultivation-world-simulator-api-skill) - [cultivation-world-simulator-android](https://github.com/RealityError/cultivation-world-simulator-android) - [LINUX DO community post](https://linux.do/t/topic/2439437) ## 👥 Contributors

_4thfever	_xzhseh	_teps3105	_Meanliss	_octo-patch	_cooleryu	_LuckVd
_MarkYangKp	_Robinwhliu	_Seafoodsz	_Tianrant	_cw1990	_RealityError	_{mitsuko33000-ops}

For more contribution details, please check [CONTRIBUTORS.md](../../CONTRIBUTORS.md). ## 📋 Feature Development Progress ### 🏗️ Foundation System - ✅ Basic world map, time, event system - ✅ Diverse terrain types (plains, mountains, forests, deserts, waters, etc.) - ✅ Web frontend-based display interface - ✅ Basic simulator framework - ✅ Configuration files - ✅ One-click desktop build - ✅ Menu bar & Save & Load - ✅ Flexible custom LLM interface - ✅ Support Mac OS - ✅ Multi-language localization - ✅ Start game page - ✅ BGM & Sound effects - ✅ Player editable - ✅ Roleplay mode ### 🗺️ World System - ✅ Basic tile system - ✅ Basic regions, cultivation regions, city regions, sect regions - ✅ Same-tile NPC interaction - ✅ Spiritual energy distribution and output design - ✅ World events - ✅ Heaven, Earth, and Mortal Rankings - ✅ Larger and more beautiful maps & Random maps ### 👤 Character System - ✅ Character basic attribute system - ✅ Cultivation realm system - ✅ Spiritual root system - ✅ Basic movement actions - ✅ Character traits and personality - ✅ Realm breakthrough mechanism - ✅ Interpersonal relationships between characters - ✅ Character interaction range - ✅ Character Effects system: buff/debuff effects - ✅ Cultivation methods - ✅ Weapons & Auxiliary equipment - ✅ Cheat system - ✅ Elixirs - ✅ Character short and long-term memory - ✅ Character's short and long-term goals, supporting player active setting - ✅ Character nicknames - ✅ Life skills - ✅ Gathering, Hunting, Mining, Planting - ✅ Casting - ✅ Alchemy - ✅ Mortals ### 🏛️ Organizations - ✅ Sects - ✅ Settings, cultivation methods, healing, base, conduct style, tasks - ✅ Sect special actions: Hehuan Sect (dual cultivation), Baishou Sect (beast taming), etc. - ✅ Sect tiers - ✅ Orthodoxy - ✅ Imperial Court - ✅ Organization Will AI - ✅ Organization tasks, resources, functions - ✅ Inter-organization relationship network ### ⚡ Action System - ✅ Basic movement actions - ✅ Action execution framework - ✅ Defined actions with clear rules - ✅ Long-term action execution and settlement system - ✅ Support multi-month continuous actions (such as cultivation, breakthrough, games, etc.) - ✅ Automatic settlement mechanism when the action is completed - ✅ Multiplayer actions: action initiation and action response - ✅ LLM actions affecting interpersonal relationships - ✅ Systematic action registration and operation logic ### 🎭 Event System - ✅ Heaven and earth spiritual energy changes - ✅ Large multiplayer events: - ✅ Auction - ✅ Secret realm exploration - ✅ World Martial Arts Tournament - ✅ Sect preaching assembly - [ ] Sudden events - ✅ Treasure emergence - [ ] Natural disasters / celestial tribulations ### ⚔️ Combat System - ✅ Advantage and counter relationship - ✅ Win rate calculation system ### 🎒 Item System - ✅ Basic items, spirit stone framework - ✅ Item trading mechanism ### 🌿 Ecosystem - ✅ Animals and plants - ✅ Hunting, gathering, material system - ✅ Demon races ### 🤖 AI Enhancement System - ✅ LLM interface integration - ✅ Character AI system (Rule AI + LLM AI) - ✅ Coroutine decision-making mechanism, asynchronous operation, multi-threaded acceleration of AI decision-making - ✅ Long-term planning and goal-oriented behavior - ✅ Sudden action response system (immediate response to external stimuli) - ✅ LLM-driven NPC dialogue, thinking, interaction - ✅ LLM generates small plot fragments - ✅ Access max/flash models separately according to task requirements - ✅ Micro-theaters - ✅ Combat micro-theaters - ✅ Dialogue micro-theaters - ✅ Different text styles for micro-theaters - ✅ One-time choices (such as whether to switch cultivation methods) ### 🏛️ World Lore System - ✅ Inject basic world knowledge - ✅ Dynamic generation of cultivation methods, equipment, sects, and regional information based on user input history ### ✨ Special - ✅ Fortuitous encounters - ✅ Heavenly Tribulation & Heart Devil - ✅ Fate Revelation - ✅ Formations - ✅ Gu - ✅ Fortuitous opportunity - ✅ World secrets - ✅ POI - ✅ Background NPCs ### 🔭 Long-term Prospects - [ ] Ascension to the upper realm - [ ] Found a sect / Become emperor - [ ] Novelization & Imaging & Video of history/events - [ ] Skill agentification, cultivators independently plan, analyze, call tools, and make decisions - [ ] Integrate your own Claw into the cultivation world