cultivation-world-simulator/EN_README.md

🇨🇳 中文 · 🇺🇸 English

— ✦ —

Cultivation World Simulator

An AI-driven cultivation world simulator that aims to create a truly living, immersive xianxia world.

📖 Introduction

This is an AI-driven open-world cultivation simulator.

Unlike traditional RPGs where you play a specific character, here you play as the "Heavenly Dao" (God). You don't need to personally fight monsters or level up. Instead, you observe all living beings from a god's perspective. In an open world woven together by rules and AI, you witness the rise and fall of sects and the emergence of prodigies. You can quietly watch the world change, or bring down tribulations and alter minds, subtly intervening in the world's progress.

✨ Core Highlights

• 👁️ Play as "Heavenly Dao" (God Perspective): You are not a cultivator, but the Heavenly Dao controlling the world's rules. Observe the myriad forms of life and experience their joys and sorrows.
• 🤖 Fully AI-Driven: Every NPC is independently driven by LLMs, with unique personalities, memories, relationships, and behavioral logic. They make decisions based on the current situation, have love and hate, form factions, and even defy the heavens to change their fate.
• 🌏 Rules as the Cornerstone: The world runs on a rigorous numerical system including spiritual roots, realms, cultivation methods, and lifespans. AI imagination is constrained within a reasonable cultivation logic framework, ensuring the world is authentic and credible.
• 🦋 Emergent Storytelling: Even the developer doesn't know what will happen next. There is no preset script, only world evolution woven from countless causes and effects. Sect wars, righteous vs. demonic conflicts, the fall of geniuses—all are deduced autonomously by the world's logic.

Sect System City Region Life Experiences

Character Panel Personality Traits Independent Thinking Nicknames

Dungeon Exploration Short/Long Term Goals Elixirs/Treasures/Weapons

💭 Why make this?

The worlds in cultivation novels are fascinating, but readers can only ever observe a corner of them.

Cultivation games are either completely scripted or rely on simple state machines designed by humans, often resulting in forced and unintelligent behaviors.

With the advent of Large Language Models, the goal of making "every character alive" seems reachable.

I hope to create a pure, joyful, direct, and living sense of immersion in a cultivation world. Not a pure marketing tool for some game company, nor pure research like "Stanford Town", but an actual world that provides players with real immersion.

📞 Contact

If you have any questions or suggestions, feel free to open an Issue or Pull Request.
You're also welcome to leave a message on my Bilibili account!
You can also join the QQ group for discussion: 1071821688. Verification answer: 肥桥今天吃什么
Join our Discord community: https://discord.gg/shhRWmZR

🚀 Usage

⚙️ Run Steps

Option 1: Docker Compose (Recommended)

If you have Docker installed, this is the easiest way:

1. Clone the repo

   git clone https://github.com/AI-Cultivation/cultivation-world-simulator.git
   cd cultivation-world-simulator
   

2. Start Service (Auto build & run)

   docker-compose up -d --build
   

Option 2: Manual Installation

1. Clone the repo:

   git clone https://github.com/AI-Cultivation/cultivation-world-simulator.git
   cd cultivation-world-simulator
   

2. Install dependencies:

   # Backend dependencies
   pip install -r requirements.txt
   
   # Frontend dependencies (Node.js environment required)
   cd web && npm install
   

3. Configure LLM:

   Recommended: Configure directly in the frontend (supports quick preset filling)

   

   You can also manually configure it in static/local_config.yml (OpenAI compatible format):

   llm:
     base_url: https://api.deepseek.com       # API addr
     key: your-api-key-here                   # your api key
     model_name: deepseek-chat                # normal model name
     fast_model_name: deepseek-chat           # fast model name
     mode: default                            # run mode (default/normal/fast)
   

   Supports all API providers compatible with OpenAI interface format (e.g., Qwen, DeepSeek, SiliconFlow, OpenRouter, etc.)

   Local Deployment (Ollama): Also supports connecting to local Ollama, just select "Ollama (Local)" preset in the frontend.

4. Run:

   # Start service (Recommended dev mode, automatically starts frontend)
   python src/server/main.py --dev
   

   The browser will automatically open the web frontend.

🌐 Access Application

Frontend: http://localhost:8123 Backend API: http://localhost:8002

📱 Mobile / LAN Access

You can access the game from other devices on the same network (e.g., phone, tablet).

⚠️ Note: The mobile UI is not optimized yet. See Issue #130.

Configuration steps:

1. Add to static/local_config.yml:

   system:
     host: "0.0.0.0"  # Allow LAN access
   

2. If using dev mode (--dev), also add to web/vite.config.ts in the server config:

   server: {
     host: '0.0.0.0',  // Add this line
     proxy: { ... }
   }
   

3. After starting the server, access from your phone:

   http://<your-computer-lan-ip>:5173  # Dev mode
   http://<your-computer-lan-ip>:8002  # Production mode
   

4. Find your computer's LAN IP:

   # macOS
   ipconfig getifaddr en0
   
   # Linux
   hostname -I
   
   # Windows
   ipconfig
   

💡 Make sure your phone and computer are on the same WiFi, and the firewall allows the corresponding port.

📊 Project Status

⭐ Star History

If you find this project interesting, please give us a Star ⭐! It will motivate us to keep improving and adding new features.

👥 Contributors

For more details on contributions, please see CONTRIBUTORS.md.

📋 Development Progress

🏗️ Foundation

• ✅ World map basics, time, event system
• ✅ Diverse terrain types (plain, mountain, forest, desert, water, etc.)
• ✅ Web-based frontend interface
• ✅ Simulation framework
• ✅ Configuration files
• ✅ Standalone release (packaged exe)
• ✅ Menu bar & Save & Load
• ✅ Flexible custom LLM interface
• ✅ Support macOS
• ✅ Support multi-language localization
• ✅ Start Game Page
• Mod Support

🗺️ World System

• ✅ Basic tile mechanics
• ✅ Normal, cultivate, city, sect regions
• ✅ Same-tile NPC interactions
• ✅ Qi distribution and yields
• ✅ World event

👤 Character System

• ✅ Core attributes
• ✅ Cultivation realms
• ✅ Spiritual roots
• ✅ Basic movement actions
• ✅ Trait & Personality
• ✅ Breakthrough system
• ✅ Relationships
• ✅ Interaction range
• ✅ Effect system: buffs/debuffs
• ✅ Techniques
• ✅ Combat equipment & auxiliary equipment
• ✅ Elixir
• ✅ Short/Long term memory
• ✅ Character's short and long term objectives, supporting player active setting
• ✅ Avatar nicknames
• Life Skills
  • ✅ Forging
  • ✅ Refine
  • Planting
  • Taming
  • Evolving skills
• Mortals

🏛️ Organizations

• Sect system
  • ✅ Settings, techniques, healing, base, styles
  • ✅ Special sect actions: Hehuan Sect (dual cultivation), Hundred Beasts Sect (beast taming)
  • ✅ Sect tiers
  • Sect will AI
  • Sect tasks
• Clans
• Court/Empire (TBD)
• Inter-organization relations

⚡ Action System

• ✅ Basic movement
• ✅ Action execution framework
• ✅ Defined actions
• ✅ Long-duration actions and settlement
  • ✅ Multi-month actions (cultivate, breakthrough, play, etc.)
  • ✅ Auto-settlement upon completion
• ✅ Multiplayer actions: initiator + responder flow
• ✅ LLM actions that affect relationships
• ✅ Systematic action registration and runtime logic

🎭 Event System

• ✅ Heaven-earth Qi fluctuations
• World-scale events:
  • ✅ Auctions
  • ✅ Hidden domain exploration
  • Martial tournaments
  • Sect grand competition
• Sudden events
  • Treasure/cave emergence
• Natural events:
  • Natural disasters
  • Beast tides

⚔️ Combat

• ✅ Advantages and counters
• ✅ Win-rate estimation system

🎒 Items

• ✅ Basic items and spirit stones
• ✅ Trading mechanics

🌿 Ecology

• ✅ Animals and plants
• ✅ Hunting, gathering, materials
• Beasts/monsters

🤖 AI Enhancements

• ✅ LLM interface integration
• ✅ Character AI (rules AI + LLM AI)
• ✅ Coroutine decision making, async, multithreaded speedups
• ✅ Long-term planning and goal-driven behavior
• ✅ Reactive responses to external stimuli
• ✅ LLM-driven NPC dialogue, thinking, interaction
• ✅ LLM-generated micro-stories
• ✅ Use different models (max/flash) per task needs
• ✅ Micro-theaters
  • ✅ Battle micro-theaters
  • ✅ Dialogue micro-theaters
  • ✅ Multiple writing styles
• ✅ One-off choices (e.g., switch techniques or not)

🏛️ World Lore

• ✅ Inject basic world knowledge
• ✅ User input history, dynamic generation of techniques, equipment, sects, and region info

✨ Specials

• ✅ Fortuitous encounters
• ✅ Tribulations & Heart devils
• Possession & Rebirth
• Opportunities & Karma
• Divination & Prophecy
• Male appearance female traits & Female appearance male traits
• Character Secrets & Two-faced
• Ascension to Upper Realm
• Formations
• Paths/Daos
• World Secrets & World Laws (Flexible customization)
• Gu Refining
• World-ending Crisis

🔭 Long-term

• Novelization/imagery/video for history and events
• Avatar calling MCP tools on their own