$ show 4thfever/cultivation-world-simulator
This is a full-stack cultivation world simulator game (xianxia RPG) with a Python backend (FastAPI + asyncio) and a Vue 3 + TypeScript + PixiJS frontend, supported by an optional Electron desktop shell for Epic Games Store distribution. The simulation engine runs a month-by-month tick system orchestrating ~29 phases (lifecycle, actions, social, war, world events, etc.) producing emergent narratives driven by LLM calls (OpenAI/Anthropic compatible) for character decisions, story generation, world lore rewriting, and roleplay interactions. The codebase is heavily data-driven with static game configurations (sects, techniques, items, regions) loaded from CSV files and multi-language localization via gettext PO files. It exposes a public REST API (query/command) and WebSocket for real-time state updates, supports save/load with JSON snapshots and SQLite event storage, and includes comprehensive test coverage (pytest, vitest, Playwright) and CI/CD workflows. While the architecture shows strong engineering patterns (effect system, action registry, single-choice decision framework, phased simulation pipeline), it carries risks from tight coupling of global singleton registries, LLM dependency, and use of `eval` in effect conditions.
The LLM identified 4 files worth highlighting for reuse:
Defines ~100+ effect constants (e.g., extra_battle_strength_points, extra_breakthrough_success_rate) with typed values, merge rules, and documentation. This centralized effect registry is a decoupled, reusable pattern for any attribute-based game or system where effects modify numeric/list properties from multiple sources (techniques, roots, personas, equipment). It demonstrates non-obvious skill in designing a maintainable effect catalog that avoids magic strings across the codebase.
Provides base classes (DefineAction, TimedAction, InstantAction, ActualActionMixin) and a cooling decorator for action lifecycle management. Each action encapsulates start/execute/finish phases with cooldown support and parameter validation. This pattern is self-contained and could be extracted for any turn-based or timed action framework (e.g., RPG skills, job scheduling) with minimal adaptation. The registry in __init__.py allows discoverability.
Implements a generic LLM-driven single-choice decision engine with fallback to deterministic logic when LLM fails. Supports accept/reject scenarios, item exchange, and sect recruitment. The engine is decoupled from game-specific models and can be reused in any project requiring structured LLM decisions with recovery strategies.
Defines the ordered pipeline of 29 phases (lifecycle, actions, social, world, etc.) executed each month in the simulation. Each phase is a callable handler registered with a name, and the PhaseRunner orchestrates execution with hooks for before/after. This pattern is a clean, extensible pipeline architecture applicable to any iterative simulation or batch processing system.