How 4thfever/cultivation-world-simulator works
Cultivation World Simulator is an AI-driven cultivation-world simulation in which the player observes the world as its “Heavenly Dao” and can intervene. The main loop runs from the web UI or external client through read-only queries and controlled commands, then back to refreshed world state and events. The backend also advances autonomous avatar, sect, and world simulation; roleplay choices can involve the player, while LLM services drive AI behavior. The README documents these capabilities; links for unsampled subsystems are limited to documented flows and the visible module structure.
Main entry points: phase_runner.py Phase Engine · App.vue Game UI · index.ts Web API Client · game_query_service.py Query Service
Components 25
Player Interfaces
- Game UI
web/src/App.vue - World View
web/src/components/game/GameCanvas.vue - Web API Client
web/src/api/index.ts
Control API
- Read Queries
src/server/api/public_v1/query.py - Game Commands
src/server/api/public_v1/command.py - Settings API
src/server/api/settings.py - Query Service
src/server/services/game_query_service.py - Command Service
src/server/services/game_command_service.py
World Simulation
- Game Runtime
src/server/runtime/session.py - Simulation Loop
src/server/loop/runner.py - Phase Engine
src/sim/simulator_engine/phase_runner.py
World Systems
- Avatar Agents
src/classes/core/avatar/core.py - Avatar Actions
src/classes/action_runtime.py - Sect Dynamics
src/sim/managers/sect_manager.py - World Model
src/classes/core/world.py - Event History
src/classes/event_storage.py - Points of Interest
src/classes/poi/manager.py
Runtime Services
- Roleplay Service
src/server/services/roleplay_service.py - Choice Engine
src/systems/single_choice/engine.py - LLM Client
src/utils/llm/client.py - Settings Service
src/config/settings_service.py - Save Load
src/sim/save/save_game.py - Epic Metrics
desktop/src/epicRuntime.ts
Other components
- Player
- External Agent
Connections 25
- Player → Game UI: interacts
- Game UI → World View: renders
- Game UI → Web API Client: requests
- Web API Client → Read Queries: queries
- Web API Client → Game Commands: commands
- External Agent → Read Queries: queries
- External Agent → Game Commands: commands
- Read Queries → Query Service: delegates
- Query Service → Game Runtime: reads state
- Query Service → Event History: queries events
- Game Commands → Command Service: delegates
- Command Service → Game Runtime: controls
- Settings API → Settings Service: manages
- Simulation Loop → Phase Engine: runs phases
- Phase Engine → World Model: advances
- Phase Engine → Avatar Agents: simulates
- Phase Engine → Sect Dynamics: updates
- Avatar Agents → Avatar Actions: performs
- Phase Engine → Points of Interest: updates
- Phase Engine → Event History: records events
- Choice Engine → LLM Client: requests decision
- Choice Engine → Roleplay Service: waits for choice
- Roleplay Service → LLM Client: generates dialogue
- Save Load → Game Runtime: loads and saves
- Epic Metrics → External Agent: reports sessions