About ArcanaPDF

AI-Powered 5E compatible character sheet generator.


ArcanaPDF is a personal, free, and open-source project designed to streamline the creation of character sheets for 5E compatible TTRPGs.

The initial idea began in 2023 as an NPC generator for Harvard's CS50P course final project. Back then, the application was quite simple, solely usable via CLI, yet still fun to use!

A year later, I took Harvard's CS50X, where I learned about dev stacks, utilizing Python with the Flask framework, Jinja2 templates, HTML/CSS/JavaScript, and SQL. Upon course completion, I delved into programming to improve and flesh out the NPC generator. It was a nice touch to have a GUI after all 😄.

Artificial intelligence was recently released for public users, and then it hit me: Wouldn't it be great to have an AI agent craft interesting backstories for NPCs? Or even better, to visualize your favorite allies and villains? What a useful tool for DMs that would be, huh? 🤗 Indeed, when REST APIs were made public, implementing those AI features was mind-blowing!

During the development process, as I was adding new features and options to the web app, I realized it could easily be used for character creation instead of just NPC creation. After all, it was becoming too complex and detailed for merely a "poor little NPC."

Are you in the mood to contribute? Feel free to contact me!

How It Works

  • Create your account for free or login as a demo user.
  • Free accounts get 20 AI tokens upon email verification.
  • Demo users don't need to register, but lack AI tokens for AI features.
  • Create a character. You can store up to 10 characters.

GitHub README.md

This page is generated from GitHub ArcanaPDF repository


ArcanaPDF v1.0.0

A character generator tailored for 5E compatible TTRPGs. It creates character sheets in PDF form powered by AI APIs to include interesting backstories, unique portraits, and audio presentations.

Character statistics are determined either randomly or customed by the user.

The application runs either in terminal mode (more convenient for testing purposes) or in browser mode based on Flask microframework.

Available options

Races and Subraces

  • Dragonborn
    • All draconic ancestries
  • Dwarf
    • Hill
  • Elf
    • High
  • Halfling
    • Lightfoot
  • Half-orc
  • Human

Classes and Subclasses

  • Fighter
    • Champion
  • Rogue
    • Thief
  • Wizard
    • Evoker

World Settings

  • User-defined World Settings including further details such as:
    • World Setting Style
    • Nationality
    • Hometown
    • Ethnicity

Appearance

  • User-defined or app-generated character appearance

Attributes (ability scores)

  • User-defined or app-generated ability scores, put on character's attributes either automatically or manually

Identity

  • User-defined character name or app-generated
  • Select between 11 backgrounds:
    • Acolyte
    • Arcane Street Urchin
    • Exiled Diplomat
    • Guild Cartographer
    • Hermetic Alchemist
    • Librarian of the Forgotten Lore
    • Retired Gladiator
    • Sanctuary Healer
    • Sky-faring Trader
    • Subterranean Scout
    • Whispering Oracle
  • All ethical and moral alignments that are 5E compatible according to SRD 5.1

Organization

  • User-defined organization and ability to upload image of heraldry

Weapons

  • All weapons that are 5E compatible according to SRD 5.1

Armor

  • All armor that are 5E compatible according to SRD 5.1

AI-Powered Features

  • Backstrory
  • Portrait
  • Audio presentation

Magic Items

  • All magic items* that are 5E compatible according to SRD 5.1

*Magic Items selection is random, based on an algorimth.

Spells

  • All spells* that are 5E compatible according to SRD 5.1

*Spells selection is random, based on an algorimth.

Skills

  • All skill* that are 5E compatible according to SRD 5.1

*Skill selection is random, based on an algorimth.

More to come options

Races and Subraces

  • All races and subraces included in SRD5.1

Classes and Subclasses

  • All classes and subclasses included in SRD5.1

Custom Spell Selection

Spells will be selected by the user instead of being randomly selected by the web app.


For Contributors

Branches

ArcanaPDF uses a Git branching strategy that is based on the Git Flow methodology. The repository has three main branches:

  • development. Main branch where all the development work is done in a new branches that are created from it. It is used to create pull requests to merge new features or bugfixes.
  • staging. For testing purposes - runs in a staging server.
  • production. For production code - runs in a production server.

Contributors should not modify neither staging nor production branches.

Setup

In general it is recommended to use a Linux Ubuntu machine as your development environment to be aligned with production. Staging and production servers utilize a deployed Docker image that runs Ubuntu 22.04 LTS.

Developers can either use a Docker image that is tailored for development [source: arcanapdf-dev] to run the repository source code through a Docker container or install all application dependencies as described in the *deprecated documentation stored in static/docs/README.md.old file.

The following guide is to support ONLY Linux Ubuntu environments that use the developer Docker image.

*The deprecated documentation is outdated and you must troubleshoot any incompatibilities by yourself.

Containerized setup

1. Install and enable Docker

sudo apt update && sudo apt upgrade -y
sudo apt install -y docker.io
sudo systemctl enable --now docker
sudo systemctl status docker

2. Pull developer Docker image

sudo docker pull atsagkalidis/arcanapdf-dev:latest

3. Download ArcanaPDF GitHub repository

git clone https://github.com/a-tsagkalidis/arcanapdf.git

4. Inject environment variables

ArcanaPDF uses a .env file to get the *environment variables that are needed for the application to operate. In the repository there is a stored file under the name of .env.arcanapdf.development.enc. To decrypt the file you should claim the password with a request at arg.tsag@gmail.com. Then replace the placeholder 'DEV_ENV_DECRYPTION_PASSWORD' with the actual password that was sent to you in the following command before running it.

openssl enc -d -aes-256-cbc -salt -in .env.arcanapdf.development.enc -out .env.arcanapdf.development -iter=100000 --pass pass:<DEV_ENV_DECRYPTION_PASSWORD>

*In case you want to use your own .env file you can create one by following the steps in section Create your own .env file that is presented at the bottom of this README.md file.

5. Run the app through the container

While you are in the repository root directory at the development branch run the container giving the following *command:

sudo docker run -it --rm --name 'arcanapdf-dev-environment' -p 5000:5000 -v $(pwd):/app atsagkalidis/arcanapdf-dev:latest sh -c

*It is recommended to make an alias of this command in ~/.bashrc (Bash) or $profile (PowerShell) for your convenience.

Running this command is going to partially start the application, since it runs the container which prompts to specify more command line arguments. For example if you want to start the application in a browser with debugging mode then you must pass the 'python3 app.py --webapp --debug' argument to the container command as follows:

sudo docker run -it --rm --name 'arcanapdf-dev-environment' -p 5000:5000 -v $(pwd):/app atsagkalidis/arcanapdf-dev:latest sh -c 'python3 app.py --webapp --debug'

Run the previous command and ArcanaPDF will start in the development server. Flask server will populate something like this:

* Serving Flask app 'app'
* Debug mode: on
WARNING: This is a development server. Do not use it in a production deployment. Use a production WSGI server instead.
* Running on all addresses (0.0.0.0)
* Running on http://127.0.0.1:5000
* Running on http://172.17.0.2:5000
Press CTRL+C to quit
* Restarting with stat
* Debugger is active!
* Debugger PIN: 684-058-015

Copy and paste the IP address http://127.0.0.1:5000 into your web browser for the graphical interface to be displayed.

Now you can start coding and the changes will be reflected in the web app that is running locally into your browser.

6. Coding and adding features

When you want to add a new feature, make a bugfix, or add some new documentation, then you must create a new branch from the development branch - all other branches must not be cloned or modified for any reason!

For example if you want to create a new feature that will add cleric as an option in the available 5E compatible classes, then you should create a new branch as follows:

git checkout -b feature/class-cleric development

Then you can push the branch into the GitHub repository and begin to modify the code to add the new feature.


Using CLI arguments

For our convenience let's assume that we aliased the developer Docker container command as devenv by adding the following line in ~/.bashrc file.

alias devenv="sudo docker run -it --rm --name 'arcanapdf-dev-environment' -p 5000:5000 -v $(pwd):/app atsagkalidis/arcanapdf-dev:latest sh -c"

Initially you should check all available CLI arguments which can be given to the program.

devenv 'python3 app.py --help'

Common running modes

1. Run the app in terminal mode for testing purposes with random inputs and pauses so you can check terminal stdout easier

devenv 'python app.py --terminalmode --customprint --pauseprogram'

2. Run the app in terminal mode for testing purposes with prompted inputs

devenv 'python app.py --terminalmode --customprint --promptuser'

3. Run batches in terminal mode for testing purposes

source static/scripts/devenvbatchtimes.sh INT* --terminalmode --customprint

*where INT enter desired number of times that the application is going to run.

4. Run the app in web app mode for testing purposes

devenv 'python app.py --webapp --customprint --debug'

*To create AI generated content using API functionalities then add the following arguments in the previous commands:

  • --backstory
  • --portrait
  • --presentation

Valid Command Line Arguments and their fucntionality

Argument Functionality Description
-bs, --backstory Get an AI-generated backstory
-cp, --customprint Print output in terminal
-d, --debug Run flask in debug mode
-fp, --freeportrait Web scrap free portrait (deprecated)
-l, --limiter Run flask in limiter mode
-ntf, --notxtfile Prevents program from storing the txt
-p, --portrait Get an AI-generated portrait
-pp, --pauseprogram Runs the program with pauses
-pr, --presentation Get an AI-generated mp3 presentation
-ptj, --pngtojpg Converts png to jpg and saves TTI prompt
-pu, --promptuser prompt the user for value entries
-tm, --terminalmode Runs the program solely in terminal
-wa, --webapp Runs combination of arguments for flask

Check output for debugging

PDF, TXT, MP3, and PNG files are stored in static/dev/flask/usr path. When you use the app in terminal mode all the output files are stored in user 0 - so expect some output in static/dev/flask/usr/0 path.

In case you're using the app in web app mode then the subdirectory integer in the usr folder corresponds to the user_id that is given in the SQLite database.


Create your own .env file [optional]

The .env file must be named as .env.arcanapdf.development and placed in the root directory of the repository. In case you didn't receive a password to decrypt .env.arcanapdf.development.enc file you can create the .env file by yourself and use your very own API keys.

Non-sensitive enviroment variables

You can safely copy-paste the following environment variables to your .env.arcanapdf.development file

  • DEV_WEBSITES_PORT=5000
  • DEV_WEBSITES_FQDN=http://127.0.0.1
  • DEV_SQL_ENGINE=sqlite:///arcanapdf.db
  • DEV_FREE_AI_TOKENS=20
  • DEV_MAX_CHARACTERS_STORED=10
  • DEV_MOUNT_PATH=static/dev/flask
  • DEV_SECRET_KEY=d75xd2f280fe5586sad89t7s74c8e93e7y7td0e7a93d409ss10eb87s871o9981
  • DEV_REDIS_HOST=localhost
  • DEV_REDIS_PORT=6379

Sensitive environment variables

ArcanaPDF app uses the following services:

  • Anthropic API
  • OpenAI API
  • Stability API
  • Google Gemini API
  • Brevo Email Services SMTP client

You can create your own API keys and other sensitive environment variables and add them in your .env.arcanapdf.development file according to the following table.

Service Environment Variable Name Example Variable Value
Anthropic API DEV_ANTHROPIC_API_KEY sk-ant-api03-P695_Apojetc...
OpenAI API DEV_OPENAI_API_KEY sk-IoP9scwlsdaAmcOo10zetc...
Stability API DEV_STABILITY_API_KEY sk-OpsX09scplAsmc12Wpsetc...
Google Gemini API DEV_GOOGLE_GEMINI_API_KEY KoraSaCXSHaytoPamdkgipPdf...
Brevo SMTP Server DEV_MAIL_SERVER smtp-service.example.com
Brevo SMTP User DEV_MAIL_USERNAME 541n1c883@smpt-brevo.com
Brevo SMPT Pass DEV_MAIL_PASSWORD 9b3jKAePA8cNSK9b