DOCSEARCHbyAlgolia
Submit Docs

Cultivation World Simulator Documentation

repository·main·Indexed 23 days ago

https://github.com/4thfever/cultivation-world-simulator

An AI-driven simulation where NPCs are independent LLM-based agents and users act as the 'Heavenly Dao'. The documentation covers source and Docker deployment, LAN/mobile configuration, and integration via stable API namespaces (/api/v1/query and /api/v1/command). It also includes detailed guides for developer tools, such as the image generation pipeline for avatars and item icons, and the Wiki Tool for game data lookup.

Tokens
87.9K
Snippets
138
Records
431
Agent score
84%

What's inside Cultivation World Simulator

  1. Overview of the Frontend Tech Stack

    main

    The frontend of the Cultivation World Simulator is built using a modern reactive stack designed for high-performance 2D rendering and complex state management:

    • Core Framework: Vue 3 using the Composition API and <script setup> syntax, with TypeScript for type safety.
    • Build Tool: Vite.
    • State Management: Pinia (modular stores).
    • UI Components: Naive UI (used for system menus, panels, and standard UI elements).
    • Game Rendering: Vue3-Pixi (a wrapper around Pixi.js) handles the 2D rendering engine, including maps, character animations, and viewports.
    • Networking: A lightweight wrapper around the fetch API located at web/src/api/http.ts.
    • Internationalization: Vue I18n.

  2. Overview of Cultivation World Simulator features

    main

    The Cultivation World Simulator is a comprehensive simulation framework featuring a diverse world map, complex character systems, and AI-driven interactions. Key functional areas include:

    • Foundation System: World map, time/event systems, terrain types, and a web-based frontend interface.
    • World & Organization Systems: Tile-based regions (cities, sects, cultivation regions), spiritual energy distribution, Sects (with unique behaviors like dual cultivation or beast taming), and Imperial Courts.
    • Character & Combat Systems: Attribute and cultivation realm systems, spiritual roots, personality traits, memory (short/long-term), and life skills (Alchemy, Mining, etc.). Combat uses an advantage/counter relationship and win-rate calculation.
    • Action & Event Systems: A framework for long-term continuous actions (e.g., multi-month cultivation) and large-scale multiplayer events like Auctions or Secret Realm explorations.
    • AI Enhancement: A hybrid AI system combining Rule-based AI and LLM-driven AI for NPC dialogue, thinking, and plot generation. It supports asynchronous, multi-threaded decision-making and micro-theaters for combat and dialogue.

  3. Overview of Cultivation World Simulator

    main

    Cultivation World Simulator is an AI-driven simulation where players act as the Heavenly Dao.

    Core Concepts

    • Heavenly Dao Role: Instead of playing as a single character, you control the rules of the world and observe the evolution of the simulation.
    • AI-Driven Agents: Every NPC is an independent Agent powered by an LLM. They possess unique personalities, memories, interpersonal relationships, and behavioral logic, allowing them to make decisions, form cliques, and react to their environment.
    • Rule-Based Foundation: To prevent AI hallucinations, the world operates within a rigorous system of spiritual roots, cultivation realms, sects, elixirs, weapons, and lifespans. This ensures the emergent storytelling remains grounded in consistent cultivation logic.
    • Emergent Storytelling: There are no preset scripts. Plots like sect wars or the rise and fall of geniuses emerge naturally from the interaction between the world's rules and the AI agents' decisions.

  4. Design principles for image generation in `tools/img_gen`

    main

    The image generation system for the Cultivation World Simulator follows several core principles to ensure consistency and ease of post-processing:

    • Visual-First Prompts: Prompts must describe only visible content (e.g., hair color, accessories, eye makeup) rather than character background or identity (e.g., avoid terms like "Alchemist" or "Sect member").
    • Cultivation Aesthetics: Use visible elements like hair crowns, forehead markings, eye makeup, and clothing patterns to express cultivation levels.
    • Post-processing Optimization: Avatars must use a pure white background with the subject centered. To facilitate flood-fill removal, ensure hair and accessories do not touch the image edges and explicitly prohibit shadows, gradients, fog, or halos.
    • Generation Workflow:
      • Qi Refining (qi_refining): Generated via Text-to-Image.
      • Higher Realms: foundation, golden_core, and nascent_soul are generated via Image Editing (using an OpenAI-compatible API) based on the original Qi Refining image. This avoids

  5. What is Rule-Based Test Mode?

    main

    Rule-Based Test Mode is a specific game session semantic designed for functional development, integration verification, and regression testing. When enabled, the simulator replaces all LLM-dependent tasks with deterministic, rule-based fallbacks.

    Key Characteristics:

    • No LLM Access: It does not read API keys, perform connectivity checks, or call any actual LLM HTTP endpoints.
    • Deterministic Results: Every LLM task (e.g., action_decision, relation_delta) returns a structured, business-consumable result defined by internal rules.
    • Session-Scoped: The mode is part of the RunConfig and is tied to a specific game session. It is saved with the world snapshot and persists through loading/saving.
    • Integration Ready: It allows testing the full path of characters, actions, events, sects, and WebSockets without the cost or unpredictability of LLMs.

  6. Overview of the World Lore Rewrite Pipeline

    main

    The World Lore Rewrite Pipeline is a system designed to transform generic game data into a customized, static text snapshot based on a player's chosen 'World Lore' and 'History' settings.

    Instead of just renaming a few items, the pipeline performs a full-scale rewrite of the following entities to ensure thematic consistency:

    • Map Locations: Cities, ordinary regions, cultivation areas, and sect residences.
    • Sects: Names and descriptions.
    • Techniques (Cultivation Methods): Names and descriptions.
    • Weapons: Names and descriptions.
    • Auxiliary Equipment: Names and descriptions.

    Key Constraint: The system only rewrites static display text (names and descriptions). It does not modify gameplay mechanics, numerical values, item types, grades, requirements, or structural data (e.g., it won't add new regions or change a sword into a spear).

  7. Calculate success rate for taking treasure

    main

    The success rate of the TakeTreasure action is determined solely by the difference between the character's realm rank (taker_realm_rank) and the treasure's realm rank (treasure_realm_rank).

    Success Rate Formula: success_rate = clamp(0.45 + (taker_realm_rank - treasure_realm_rank) * 0.15, minimum=0.05, maximum=0.95)

    Realm DifferenceSuccess Rate
    2+ stages lower5%
    1 stage lower30%
    Same stage45%
    1 stage higher60%
    2 stages higher75%
    4+ stages higher95%

    Note: Factors like HP, injuries, perception, luck, personality, sect, or equipment quality must not influence this probability. While treasures do not have a 'Qi Refining' level, characters in the Qi Refining stage are permitted to attempt claiming Foundation Establishment treasures.

  8. Understand the Game Initialization Flow

    main

    The frontend initialization follows a specific sequence to ensure the backend is ready before rendering game elements:

    1. Entry: App.vue is mounted.
    2. Check: useGameInit is called to poll the backend service status (Idle, Ready, or Running).
    3. Load: When the user clicks "Start", worldStore.initialize() is triggered. This performs parallel operations:
      • mapStore.preloadMap loads map data.
      • worldApi.fetchInitialState fetches the initial game state.
      • eventStore.resetEvents resets the event list.
    4. Render: Once isLoaded becomes true, GameCanvas and MapLayer begin rendering.

  9. Manage the Locale Registry

    main

    The file static/locales/registry.json is the single source of truth for the i18n system. It is used by Python i18n tools, locale validation, and the web frontend.

    Key fields in registry.json:

    • default_locale: The default language.
    • fallback_locale: The language used when a translation is missing.
    • schema_locale: The reference language for frontend schemas.
    • locales: A list of currently enabled/maintained languages.

    Note: To add a new language, you must first modify this file before creating directories or PO/JSON resources.

  10. Ensure Type Safety for i18n keys

    main

    The TypeScript schema for translations is dynamically generated from static/locales/registry.json via web/src/locales/registry.ts.

    If you experience missing code completion or TypeScript errors when using $t(), it means the key you are trying to use is missing from the JSON file corresponding to the current schema_locale. Always ensure that the key exists in the JSON file for the locale being used for type checking.

  11. Identify the i18n sources of truth

    main

    The project uses a tiered system for internationalization. To ensure consistency, always use the designated source files for maintenance and avoid modifying build artifacts directly.

    1. Language Registry

    The single source of truth for all enabled languages is:

    • static/locales/registry.json

    All tools, tests, and scripts must read from this file instead of hardcoding language lists.

    2. Maintenance Source Files

    Depending on the content type, use the following source files:

    • Runtime & UI Text: static/locales/<lang>/modules/*.po (includes UI, dynamic formatting, etc.)
    • Configuration Text: static/locales/<lang>/game_configs_modules/*.po (materials, regions, techniques, etc.)
    • LLM Prompt Templates: static/locales/<lang>/templates/*.txt
    • Configuration Data: static/locales/<lang>/game_configs/*.csv (names, etc.)

    3. Build Artifacts (Do NOT edit)

    Do not modify these files directly; they are generated from the sources above:

    • static/locales/<lang>/LC_MESSAGES/messages.po
    • static/locales/<lang>/LC_MESSAGES/game_configs.po
    • static/locales/<lang>/LC_MESSAGES/*.mo

  12. How Avatar Awakening Mechanics work

    main

    Awakening occurs through two primary methods during the simulation:

    • Bloodline Awakening: Mortal offspring managed by the MortalManager have a chance to awaken spiritual roots once they reach age 16.
    • Wild Awakening: Random "Wild" (Rogue) cultivators appear spontaneously based on the current world configuration.

    When an avatar awakens, they are initialized with a simplified configuration:

    • Weapon: One random weapon appropriate for their Realm (e.g., Qi Refinement).
    • Auxiliary: None.
    • Technique: A basic technique.
    • Resources: A small amount of Spirit Stones.