https://github.com/klieret/ppserver
A small server that helps to keep track of story lines and characters (NPCs) in my pen & paper game. The underlying data is collaboratively maintained in google sheets.
https://github.com/klieret/ppserver
dungeons-and-dragons flask graph network penandpaper tabletop tabletop-rpg-utility tabletop-rpgs
Last synced: 15 days ago
JSON representation
A small server that helps to keep track of story lines and characters (NPCs) in my pen & paper game. The underlying data is collaboratively maintained in google sheets.
- Host: GitHub
- URL: https://github.com/klieret/ppserver
- Owner: klieret
- License: mit
- Created: 2021-08-23T07:32:11.000Z (about 4 years ago)
- Default Branch: main
- Last Pushed: 2025-07-07T21:48:42.000Z (3 months ago)
- Last Synced: 2025-07-08T01:21:34.961Z (3 months ago)
- Topics: dungeons-and-dragons, flask, graph, network, penandpaper, tabletop, tabletop-rpg-utility, tabletop-rpgs
- Language: Python
- Homepage:
- Size: 354 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# ppserver
[](https://results.pre-commit.ci/latest/github/klieret/ppserver/main) [](https://git-scm.com/book/en/v2/GitHub-Contributing-to-a-Project) [](https://github.com/python/black) [](https://github.com/klieret/ppserver/blob/main/LICENSE.txt)
`ppserver` is a small [`flask`](https://flask.palletsprojects.com/) server that helps to keep track of story lines and characters ([NPCs](https://en.wikipedia.org/wiki/Non-player_character)) in my [pen & paper game](https://en.wikipedia.org/wiki/Tabletop_role-playing_game). The underlying data is collaboratively maintained in google sheets.
## Video
[](https://www.youtube.com/watch?v=Bz6TbnL1mEU)
## Setup
### Installing this package
Clone the repository and run
```python3
pip3 install -e .
```
### Data you need
`ppserver` works of two separate google sheets:
#### `characters`
This table lists all characters in your adventures. It should have the following columns:
1. `Name`
2. `Description`
3. `Race`
4. `Appeared` (date of first appearance)
5. `Locations` (comma separated if more than one location)
6. `Keywords` (comma separated if more than one)
The following keywords are allowed:
* `player` (this is not a NPC but a player character)
* `dead` (character is deceased)
#### `relations`
This table lists the relationships between characters. It should have the following columns:
1. `Actor` (who is the relationship originating from)
2. `Relation` (what is the relation)
3. `Target` (target of the the relation)
4. `Extra` (additional keywords, comma separated if more than one)
The following keywords are allowed:
* `bi` (draw a bidirectional arrow rather than a normal arrow pointing from actor to target)
### Google API
Follow [these instructions](https://docs.gspread.org/en/latest/oauth2.html#enable-api-access-for-a-project). This involves two steps:
* Creating the certificate json file and downloading it to your computer
* Sharing the google sheets with the email address from your service account
### Config file
Place the following file at `~/.ppserver.yaml`:
```yaml
# "share with edit rights" link to the characters sheet
character_sheet_link: https://docs.google.com/spreadsheets/d/XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/edit?usp=sharing
# file name of this sheet in your google drive
character_sheet_name: characters
# "share with edit rights" link to the relations sheet
relations_sheet_link: https://docs.google.com/spreadsheets/d/XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/edit?usp=sharing
# file name of this sheet in your google drive
relations_sheet_name: relations
# path to your certificate file
certificate_path: /home/X/Y/Z/pen-and-paper-xxxxxx-yyyyyyyyyyyy.json
```
## License
MIT license [](https://github.com/klieret/ppserver/blob/main/LICENSE.txt).
This repository contains `vis-network.min.js` from the [vis-network](https://github.com/visjs/vis-network) project. Its MIT license is tracked as `vis_js_license.txt`.