dungeons-logic 0.0.2
Backend logic for DND 5e(2014)
License: MIT
Requires Python: <4.0.0,>=3.13

# Mind Goblin

```
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣀⣀⣠⣤⣤⣀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣠⣤⣶⣾⣿⣿⣿⣿⣿⣿⣿⣿⣧⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣀⣤⣾⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠀
⠀⠀⠀⠀⠀⠀⠀⢀⣴⣾⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠀
⠀⠀⠀⠀⢀⣀⢾⣿⣿⣿⣿⣿⣿⣿⣿⣿⠿⠛⢋⣭⡍⣿⣿⣿⣿⣿⣿⠀
⠀⢀⣴⣶⣶⣝⢷⡝⢿⣿⣿⣿⠿⠛⠉⠀⠀⣰⣿⣿⢣⣿⣿⣿⣿⣿⣿⡇
⢀⣾⣿⣿⣿⣿⣧⠻⡌⠿⠋⠁⠀⠀⠀⠀⢰⣿⣿⡏⣸⣿⣿⣿⣿⣿⣿⣿
⣼⣿⣿⣿⣿⣿⣿⡇⠁⠀⠀⠀⠀⠀⠀⠀⠈⠻⢿⠇⢻⣿⣿⣿⣿⣿⣿⡟
⠙⢹⣿⣿⣿⠿⠋⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⠻⢿⣿⣿⡿⠟⠁
⠀⠀⠉⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
```

# Initial Idea

1. Set of random generation tools (use DMG tables for reference)
- random dungeon generation
- random encounter generation
- random npc generation
- random villain generation
- random adventure genration


* have options to lock/freeze certain features and re-roll others
* have option to pipe output to a json file on "save"
* ea. sub-table used in any of the above generation must be accessible on its own

# terminal input or API	
# stretch goal: UI (fuck this shit)


2. Combat DM utils
- hell, write a fucking engine for combat that takes an excel sheet and randomly rolls initiative scores for all monsters, sorts them according to initiative and updates the same sheet


3. Story DM utils
- weather rolls
- random encounter rolls


4. Encounter planning utils
- calculate "difficulty" of an encounter
- generate equivalent difficulty of encounter, according to parameters:
    - monsters given as input
    - number of monsters
    - specific categories of monsters
! will need DB full of monsters



# Better Goals, to also help with Assessment


## Pick a web python framework
Pick from the following:
1. Django
+ fucking complex, piece of shit
- fucking complex, piece of shit, I hate it
+ ORM and signals and shit
1. Flask
+ simple
+ SQL alchemy ORM
+ we use on the project
~~1. FastAPI~~
~~+ lightweight~~
~~+ tight overlap with what I do for work~~


## Tables should be stored in model layer, via ORM


## I can also fucking model the combat encounter data
- calls monster manual
- conditions model
- AC mechanism

## I can also store a bestiary or see if there is any open-source API that has these fucks that I can call

https://www.dnd5eapi.co/



# Deliverables
DM utils

1. Encounter automation
- intiative calculation
- ordering by initiative
- need to take this as json artifact, have another middleware service that converts to excel-like
- then writes this data into an excel spreadsheet
- input: monster, number

2. Set of random generation tools (use DMG tables for reference)
- random dungeon generation
- random encounter generation
- random npc generation
- random villain generation
- random adventure genration
- story randomization


* have options to lock/freeze certain features and re-roll others
* have option to pipe output to a json file on "save"
* ea. sub-table used in any of the above generation must be accessible on its own


3. (stretch) I want something like a query processor:
- input: a term that I am searching for, with fuzzy search
- output: a description of its mechanics (str output), along with source of reference


4. Encounter planning utils

```
https://github.com/fantasycalendar/kobold-plus-fight-club/tree/master
https://koboldplus.club/
```
- poach this
- fuck the ui


- calculate "difficulty" of an encounter
- generate equivalent difficulty of encounter, according to parameters:
    - monsters given as input
    - number of monsters
    - specific categories of monsters


# Prerequisites

1. DB of monsters
> https://github.com/5e-bits/5e-database
- poach this, convert to relational mapping, practice ORM techniques


2. DB of active effects
> https://github.com/5e-bits/5e-database
- poach this, convert to relational mapping, practice ORM techniques

3. 


# Implementation

1. Web Framework: Flask
2. DB Layer/ORM: sqlAlchemy
3. Architecturally I want to have 3 major components:

    1. Self-contained, monolithic backend logic that can be interfaced with
    > dungeons_logic

    2. CLI interface: basic unix input handling and shit
    > dungeons_local
    
    3. MVC REST API that makes contact with the monolith
    > dungeons_web





# TODO
- deploy everything in docker image, create db dynamically

# Working with Alebic

1. Generate migration scripts to review: this also serves to check any "compilation errors" in the models
```bash
alembic revision --autogenerate -m "description of your migration"
```

- --autogenerate: Tells Alembic to automatically compare the database schema and the models to generate migration instructions.

-  -m: Specifies a short message describing the migration, such as "add new column to users table".

2. Update/fix the migration generated in `alembic/versions`

NOTE: upgrade, downgrade functions contain steps for upgrading and downgrading respectively

3. If satisfied, run
```bash
alembic upgrade head
```

## Reverting Migrations
### Latest Migration
Run
```bash
alembic downgrade -1
```
This command will undo the last migration, rolling back the database schema to its previous state.

### Migration by id
```bash
alembic downgrade <revision_id>
```

## Show History
```bash
alembic history --verbose
```


## Pending Migrations
```bash
alembic heads
```


# Versioning and Poetry
Use semver

## Poetry
At the time of this commit, I am new to Poetry, as such some practices listed below may be non-optimal. Who fucking cococares.

### Workflow
- Use `pip` and `requirements.txt` for local development
- Maintain `requirements.txt` in parity with `pyproject.toml`
- To update `pyproject.toml` dependencies with those in `requirements.txt`
```bash
poetry add $(cat requirements.txt)
```

## Pushing new releases
I have not implemented a workflow for releases to be pushed on commits to the main branch. Should do that later.

Currently, need to manually tag and release tags from CLI:
```bash
git tag <x.y.z>
git push origin --tags
```
*semper fi*

## Deleting tags if build fails
### Locally
```bash
git tag -d <x.y.z>
```
### Remotely
```bash
git push origin --delete <tag-name>
```