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.

Overview

Cultivation World Simulator combines traditional game-rule systems with large language models. By first establishing a complete ruleset for the cultivation world, it creates an autonomous, vibrant, immersive virtual world with emergent stories.

Core idea: Build a credible rule-based world model first, then plug in AI to bring it to life.

Tech Stack

• Frontend Rendering: pygame (Web support in the future)
• Simulation Engine: custom event-driven simulator
• World Model: rule-based deterministic systems
• AI Integration: LLM-generated actions, decisions, micro-stories

Background

I have been a long-time reader of xianxia novels, from classics to modern works. As a game AI practitioner, I believe today’s LLM capabilities are sufficient to support a xianxia-style world simulation.

However, LLM-only NPC decision/dialogue is not enough. A credible rule system must ground the world as the “world model”, and then AI makes it vivid.

I aim to create a pure, joyful, direct, living sense of immersion. Not a mere marketing demo, nor purely academic like “Stanford Town”, but a world that players can actually feel and inhabit.

If you like this project, consider starring it. You can also watch an intro video on my Bilibili: link.

Development Progress

🏗️ Foundation

• ✅ World map basics
• ✅ Diverse terrain types (plain, mountain, forest, desert, water, etc.)
• ✅ Time system (year-month timestamps)
• ✅ Frontend UI (pygame)
• ✅ Simulation framework
• ✅ Project documentation (README)
• ✅ Config system
• Standalone release (packaged exe)
• Web frontend (later)
• ECS parallel toolkit (later)
• Player-configurable prompts (later)

🗺️ Tile System

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

👤 Character System

• ✅ Core attributes
• ✅ Cultivation realms
• ✅ Spiritual roots
• ✅ Basic movement actions
• ✅ Personality
• ✅ Breakthrough system
• ✅ Relationships
• ✅ Perception radius
• ✅ Buff system: buffs/debuffs
• ✅ Artifacts
• Special abilities
• Epithets/nicknames
• Combat-related
  • Attribute points allocation
  • Skill system (techniques)
  • Equipment system
• Skill learning
  • Learnable skills
  • Personal techniques (flexible integration)
  • Life professions (alchemy, formations, farming, forging, etc., with tailored prompts and info space)
• Mortals support
• Prodigies (stronger abilities and AI)

🏛️ Organizations

• Sect system
  • ✅ Settings, techniques, healing, base, styles
  • ✅ Special sect actions: Hehuan Sect (dual cultivation), Hundred Beasts Sect (catch spirit animal)
  • sect will AI, tasks, recruiting
  • Sect tiers: different titles, abilities, actions
• Clans
• Court/Empire (TBD)
• Inter-organization relations

⚡ Action System

• ✅ Basic movement
• ✅ Action execution framework
• ✅ Defined actions (rule-complete)
• ✅ 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
• Richer actions

🎭 Event System

• World-scale events:
  • Auctions
  • Secret realm exploration
  • Martial tournaments
• Sudden events
  • Treasure/cave emergence
  • Novelized/CG/film-style presentations
• Natural events:
  • Natural disasters
  • Beast tides

⚔️ Combat

• Combat design (roots influence skills and styles)
• Advantages and counters
• ✅ Win-rate estimation (simple)

🎒 Items

• ✅ Basic items and spirit stones
• Trading mechanics
• Economy system

🌿 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
• NPC observation space design
• One-off choices (e.g., switch techniques or not)
• Long-term memories / unforgettable memories

🏛️ World Lore

• Lore framework
• Worldbuilding
• Ancient history generation

Specials

• ✅ Fortuitous encounters
• Paths/Daos
• Possession & Rebirth
• Formations
• Opportunities
• Tribulations & Heart devils
• Flexible world rules
• Divination & Omens
• Male-female traits inversion

Usage

Run Steps

1. Clone the repo:

   git clone https://github.com/your-username/cultivation-world-simulator.git
   cd cultivation-world-simulator
   

2. Install dependencies:

   pip install -r requirements.txt
   

3. Configure LLM: Edit static/config.yml:

   llm:
     model_name: "gpt-3.5-turbo"  # or another model supported by LiteLLM
     key: "your-api-key-here"     # your API key
   

   See the LiteLLM docs: link

4. Run the simulator:

   python -m src.run.run
   

Basic Operations

• A random map is generated at startup
• Observe characters moving and acting in the world
• Press ESC to quit

Contributing

Contributions are welcome!

License

This project is licensed as specified in LICENSE.

Contact

Open an issue or pull request if you have questions or suggestions.