RPG NPC Generator

The RPG NPC Generator is a web application for generating non-player characters (NPCs) for tabletop role-playing games. The current logic of the app is based on the Pathfinder 2e ruleset.

This is a project developed for University of Helsinki databases & web programming course. The main goal of the project was to create a character creator tool without relying on heavy client-side UI frameworks. Instead, the focus was on keeping the technology stack minimal and exploring the capabilities of large language model APIs, such as the ChatGPT API, while leveraging database concepts.

How it works

The RPG NPC Generator utilizes character templates defined under the data/character_templates.json file. These templates serve as the basis for generating characters. When the app is initialized, these templates are inserted into the Postgres database.

When generating a character, the template is cloned, and the character's stats are generated based on the template's stats. This ensures that each character has unique attributes and abilities. In addition to the stats, the generator also leverages AI-generated content to enhance the character's details. AI generated content is powered by ChatGPT API.

The app also has a character gallery feature that allows users to view and browse the generated characters.

Stack

Core technologies:

Flask: Lightweight web framework for Python.
PostgreSQL: Powerful open-source relational database.
SQLAlchemy: Python SQL toolkit and ORM library.
Alembic: Database migration tool for SQLAlchemy.
Celery: Distributed task queue framework for Python.
Redis: In-memory data structure store.
Bulma: Modern CSS framework for building user interfaces.

Linting, formatting and testing:

flake8: Python code linter.
isort: Python import sorter.
black: Python code formatter.
djLint: Linter and formatter for Jinja2 templates.
pytest: Testing framework for Python.
pytest-cov: Plugin for pytest that generates coverage reports.

Note about Flask

The course this app was developed for required the use of Flask, which is the reason it was chosen. Because the app is very IO heavy and ChatGPT calls can sometimes be quite slow, I'd normally choose a framework that better supports async operations, such as node.js or Quart.

To solve the issue of slow IO operations and improve the performance of the app, the project utilizes Celery, a distributed task queue framework for Python.

Celery allows for the asynchronous execution of tasks, which is particularly useful for handling time-consuming operations such as making API calls to ChatGPT. By offloading these tasks to Celery workers, the main application can continue processing other requests without waiting for the slow tasks to complete.

Project structure

The project follows a typical structure for a Flask web application. Here is an overview of the main directories and files:

├── npcgen           # Main application directory
│   ├── auth         # Authentication related files
│   ├── characters   # Character generation and management files
│   ├── static       # Static files (CSS, JS, images)
│   └── templates    # HTML templates
├── data             # Data directory (character templates, etc.)
├── tests            # Test directory
├── .env.example     # Example environment variable file
├── compose.yml      # Docker Compose configuration file
└── requirements.txt # Python dependencies

Local setup

NOTE: Please note that the setup steps provided below have not been tested on Windows. It is recommended to run these steps using Windows Subsystem for Linux (WSL) or a similar environment.

To run the app locally using Docker, follow these steps:

Make sure you have Docker installed on your machine.

Clone the repository:

git clone https://github.com/jrauha/rpg-npc-generator.git

Navigate to the project directory:
```
cd rpg-character-generator
```
Copy the .env.example file and rename it to .env:
```
cp .env.example .env
```
Configure the OpenAI API key:

Open the .env file and set the value of OPENAI_API_KEY to your OpenAI API key.
Start the Docker containers:
```
docker compose up -d
```
Init database:
```
./run flask db reset --with-testdb
./run flask db migrate
```
If you're not planning to run tests locally you can leave out the --with-testdb option.

Create admin user:

./run cmd flask auth create-user --superuser
# follow the prompts

Init character templates:

./run cmd flask characters init-templates

Open your web browser and visit http://localhost:8000 to access the app.

Running tests

To run the tests, follow these steps:

Make sure you have the project set up locally as described in the "Local setup" section.
Run linters and formatters:
```
./run quality
```
Run the tests:
```
./run test
```
This command will execute all the tests in the project and provide you with the test results.

Alternatively you can run only unit tests with following command:
```
./run test:unit
```

Continuous integration (CI)

The project includes support for continuous integration (CI) to automate the build and testing process. .github/workflows/ci.yml file defines the steps that will be executed whenever a new commit is pushed to the repository.

References

NPC templates are based on Pathfinder NPC Gallery
The Docker support in this project is based on the Docker Flask example.

jrauha / rpg-npc-generator Goto Github PK