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 |