XianTu: an AI-driven cultivation text adventure built on Vue 3 and FastAPI

What XianTu actually is, and who it is built for

XianTu is a browser-based text adventure set in a cultivation (修仙) world. The player character advances through realms, learns techniques, refines equipment, and interacts with NPCs, and the narrative text is generated at runtime by a large language model rather than being pre-written. The README lists Gemini, Claude, OpenAI and DeepSeek as supported providers, so the game is not tied to one vendor's API.

The audience is narrow and specific. It is for people who already read Chinese, since the README, the in-game content and the linked 游戏介绍 page are all in Chinese. It is for people who have an API key for one of those providers, or who run SillyTavern and want a game front end inside it. And it is for people who enjoy the fiddly part: choosing a model, tuning prompts, and accepting that the same action may resolve differently on two runs. Anyone looking for a fixed, deterministic RPG with a hand-authored script is in the wrong place, because the model is the script.

How the Vue client, the FastAPI server and the model fit together

The repository splits into a front end and an optional back end. The front end is Vue 3 with TypeScript, Pinia for state, Vue Router, and Webpack as the bundler (the package.json scripts are webpack-based, not Vite). Chart.js and Pixi.js appear in the dependency list, which suggests the character sheet and map views are rendered rather than plain HTML. Saves are held in IndexedDB through the idb package, so a single-browser playthrough needs no server at all.

The back end under server/ is described as optional and exists to provide account and save APIs. It is Python with FastAPI, uses SQLite by default and PostgreSQL as an alternative, and authenticates with JWT. WebSocket appears in the stack table, which is consistent with streaming model output into the client rather than waiting for a full response.

The interesting design decision is the judgement system. The README describes it as computing outcomes from realm, attributes, equipment and techniques together. That means the model is not the sole arbiter of whether an action succeeds; the game state feeds into the resolution. The README does not publish the formula, so how much weight the model carries versus the numeric state is something you would have to read out of src/ yourself.

Installing XianTu with Docker and running a first session

The README marks Docker as the recommended path. The image is published on Docker Hub, and one command starts it:

docker run -d -p 8080:80 qianye60/xiantu:latest

The container serves the built front end through nginx on port 80, mapped here to host port 8080. Open http://localhost:8080 in a browser and you should land on the game's entry screen. Note what this does not give you: the image is the client only. The Dockerfile has a Node build stage and an nginx runtime stage, and nothing in it starts the Python server, so accounts and server-side saves are not part of this container.

For local development the README gives the npm flow:

npm install
npm run serve

npm run serve runs webpack-dev-server in development mode. npm run build produces the production bundle, and npm run type-check runs tsc --noEmit, which is also what the CI workflow executes on every push and pull request.

If you want the save and account APIs, the README provides the backend commands separately. Install the Python requirements and start uvicorn on port 12345:

pip install -r server/requirements.txt
uvicorn server.main:app --reload --port 12345

The README points at server/.env.example for environment variables, and states that SQLite is the default so no database setup is required to start. The repository also carries a top-level config.yaml whose contents are not described in the README, so treat it as something to read before you change it.

The licence is the first thing to check, not the last

GitHub reports the licence as NOASSERTION, and the package.json declares Apache-2.0. Those two do not agree, and the README settles it in prose: the project is free for personal study and research, and commercial use requires contacting the author first. The LICENSE file is the document that governs, and it is not an OSI-standard text as far as the repository metadata shows.

This matters more than usual for a project like this, because the game is a thin layer over a third-party model API. Your own API usage is billed by your provider under their terms, entirely separate from XianTu's licence. Running the Docker image locally for yourself is the use case the README describes. Shipping it inside a paid product, or hosting it as a service for other people, is the case the README explicitly routes to the author. If that is your plan, read LICENSE and NOTICE before you build anything on top.

Where XianTu is the wrong tool

The most obvious failure mode is cost and latency. Every turn is a model call. A long session with a frontier model is not free, and the pacing of a text adventure depends on how fast the provider streams tokens back. If your endpoint is slow or rate-limited, the game feels broken in a way that has nothing to do with the code.

Second, the game is non-deterministic by design. The README's judgement system mixes realm, attributes, equipment and techniques into the outcome, but a model still writes the prose and can still surprise you. If you want reproducible runs, replayable balance testing, or a rules engine you can unit-test, this architecture fights you.

Third, the documentation is uneven. The README covers deployment and the tech stack, but it does not document the HTTP API, the shape of a save file, or the schema of the SQLite database. There is a CHANGELOG.md and a docs/ directory in the repository, but the README does not summarise what is in them. Anyone integrating XianTu into another system is reading source, not documentation.

Fourth, the server is optional and the two deployment modes are not equivalent. Browser IndexedDB saves and server-side saves are different stores. The README does not describe how or whether they reconcile, so pick one mode and stay in it.

SillyTavern compatibility versus running XianTu standalone

The README advertises two ways to play: as a standalone web app, or inside SillyTavern. These are genuinely different propositions rather than two names for the same thing. SillyTavern is an existing front end for chatting with language models, with its own prompt handling and character card conventions. Running XianTu there means the model connection, key management and prompt plumbing are already solved, and XianTu supplies the cultivation game layer on top.

Standalone means you own the whole stack. You get the Vue client and, if you want it, the FastAPI server with JWT accounts and SQLite or PostgreSQL persistence. You also own model configuration, and the repository ships a config.yaml at the top level that the README does not explain.

The trade-off is control against setup. If you already run SillyTavern, the embedded route costs you almost nothing to try. If you do not, standing up SillyTavern first just to play XianTu is more moving parts than the single docker run command. The README does not state which path receives more attention from the author, so treat that as unknown rather than assuming the standalone build is the primary one.

Maintenance signals and the cost of upgrading

The repository is not archived. Its last push was on 2026-07-24, which is recent enough that the codebase is moving, and the release history backs that up: v4.7.6 in April 2026, v4.7.7 in May, and v4.7.8 in July, the same day as the last push. Nothing in the README describes a support policy, a deprecation window, or a migration path between releases.

Upgrade cost depends on which deployment you chose. If you run the published image, upgrading is pulling a new tag. If you built from source, you are tracking a webpack toolchain with a large dependency set including Vue 3, Pinia 3, Pixi.js 7 and a React graph library, plus the Python side with FastAPI and Tortoise migrations under server/migrations. That is two ecosystems to keep current.

The save format is the part to worry about. The README documents import and export for saves and mentions cloud sync, but it does not promise format stability across versions. Before upgrading mid-playthrough, export your saves. That is the concrete precaution the documentation supports, and it is cheap.

Editorial conclusion

XianTu fits players and tinkerers who want a self-hosted, model-agnostic cultivation RPG and are comfortable reading Chinese documentation and a config.yaml. It does not fit anyone who needs an OSI-approved licence, a documented API surface for the backend, or a stable save format across versions. Before committing a long playthrough, verify three things: which model endpoint you will point it at, where saves actually live (IndexedDB in the browser versus the SQLite server), and whether the LICENSE file's terms cover your intended use. If you plan to build on top of it commercially, the README asks you to contact the author first.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. qianye60/XianTu on GitHub
4. README
5. Releases