p-e-w/waidrin

Waidrin is a purpose-built role-playing game engine powered by an LLM. It is designed around an asynchronous, fully typed, fully validating state machine that uses constrained generation based on JSON schemas to dynamically create locations and characters as the story progresses, and keep track of them. Waidrin produces structured narrative events, not just chat messages. It can handle potentially thousands of characters and locations, without ever losing sight of what is happening.

While the engine itself is headless and can power any frontend, Waidrin comes with its own beautiful React-based frontend that is co-evolving with the engine to drive development forward. The frontend features AI-generated artwork that adds flavor and atmosphere to text-first storytelling.

At each turn, the player is presented with a choice of multiple AI-suggested actions, but they can also provide a different action as freeform text. This blends a classic CYOA experience with the limitless freedom of generative AI. It's an RPG unlike any other.

Main story interface

Genre selection screen

Note that only the fantasy genre is currently implemented.

Character selection screen

The system generates a suitable character name and biography from the player's base choices. The player has the option to override those generated attributes.

Installation

Make sure you have Git and Node.js installed, then run the following commands:

git clone https://github.com/p-e-w/waidrin.git
cd waidrin
npm install
npm run build

Running

To use Waidrin, you need a running llama.cpp server with the model of your choice (Mistral Small 2506 is recommended). Once you have that set up, run

npm run start

from Waidrin's installation directory, open the displayed URL in the browser, and follow the instructions.

You can also use

npm run dev

to run in development mode, which gives you features like hot reload and React Strict Mode, and is probably what you want if you plan to work on Waidrin's code (which you are very welcome to do!).

License

Copyright © 2025 Philipp Emanuel Weidmann ([email protected])

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License along with this program. If not, see https://www.gnu.org/licenses/.

By contributing to this project, you agree to release your contributions under the same license.