https://github.com/ttrpg-dev/ex_ttrpg_dev
ExRPG is an elixir based utility for tabletop role-playing games
https://github.com/ttrpg-dev/ex_ttrpg_dev
dungeons-and-dragons elixir hex rpg ttrpg
Last synced: 3 months ago
JSON representation
ExRPG is an elixir based utility for tabletop role-playing games
- Host: GitHub
- URL: https://github.com/ttrpg-dev/ex_ttrpg_dev
- Owner: TTRPG-Dev
- License: gpl-3.0
- Created: 2022-08-04T07:02:04.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2024-12-30T04:56:25.000Z (over 1 year ago)
- Last Synced: 2025-03-24T11:45:54.984Z (about 1 year ago)
- Topics: dungeons-and-dragons, elixir, hex, rpg, ttrpg
- Language: Elixir
- Homepage:
- Size: 235 KB
- Stars: 5
- Watchers: 1
- Forks: 0
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# ExTTRPGDev
[](https://hex.pm/packages/ex_ttrpg_dev)
[](https://hex.pm/packages/ex_ttrpg_dev)
[](https://hexdocs.pm/ex_ttrpg_dev)
[](https://github.com/TTRPG-Dev/ex_ttrpg_dev/blob/main/LICENSE)
[](https://coveralls.io/github/TTRPG-Dev/ex_ttrpg_dev?branch=main)
ExTTRPGDev is a general tabletop role-playing game utility written in Elixir.
## Table of Contents
- [ExTTRPGDev](#exttrpgdev)
- [Table of Contents](#table-of-contents)
- [Library Installation](#library-installation)
- [CLI Installation](#cli-installation)
- [Linux](#linux)
- [macOS (Intel)](#macos-intel)
- [macOS (Apple Silicon)](#macos-apple-silicon)
- [Windows](#windows)
- [Usage](#usage)
- [Rolling dice](#rolling-dice)
- [Rule systems](#rule-systems)
- [Characters](#characters)
- [Development Setup](#development-setup)
- [Contributing](#contributing)
## Library Installation
ExTTRPGDev is [available in Hex](https://hex.pm/packages/ex_ttrpg_dev), the package can be installed
by adding `ex_ttrpg_dev` to your list of dependencies in `mix.exs`:
```elixir
def deps do
[
{:ex_ttrpg_dev, "~> 0.2.1"}
]
end
```
## CLI Installation
Pre-built binaries are available on the [releases page](https://github.com/TTRPG-Dev/ex_ttrpg_dev/releases).
### Linux
```bash
curl -fsSL https://github.com/TTRPG-Dev/ex_ttrpg_dev/releases/latest/download/ttrpg_dev_cli_linux.tar.gz | tar -xz
sudo mv ttrpg-dev /usr/local/bin/
```
### macOS (Intel)
```bash
curl -fsSL https://github.com/TTRPG-Dev/ex_ttrpg_dev/releases/latest/download/ttrpg_dev_cli_macos.tar.gz | tar -xz
sudo mv ttrpg-dev /usr/local/bin/
```
### macOS (Apple Silicon)
```bash
curl -fsSL https://github.com/TTRPG-Dev/ex_ttrpg_dev/releases/latest/download/ttrpg_dev_cli_macos_arm.tar.gz | tar -xz
sudo mv ttrpg-dev /usr/local/bin/
```
### Windows
Download `ttrpg_dev_cli_windows.zip` from the [releases page](https://github.com/TTRPG-Dev/ex_ttrpg_dev/releases), extract it, and add `ttrpg-dev.exe` to your `PATH`.
## Usage
`ttrpg-dev` can be used as a one-shot command or as an interactive shell (run with no arguments):
```
ttrpg-dev
```
```
TTRPG Dev — interactive shell
Type `help` for available commands, `exit` to quit.
ttrpg-dev> _
```
### Rolling dice
```
ttrpg-dev roll 3d6
# 3d6: [2, 4, 5]
ttrpg-dev roll 2d6,1d10
# 2d6: [3, 6]
# 1d10: [7]
```
### Rule systems
```
ttrpg-dev systems list
ttrpg-dev systems show dnd_5e_srd
ttrpg-dev systems show dnd_5e_srd --concept-type skill
```
### Characters
```
# Generate a character (prompts to save)
ttrpg-dev characters gen dnd_5e_srd
# Generate and save immediately
ttrpg-dev characters gen dnd_5e_srd --save
# List and inspect saved characters
ttrpg-dev characters list
ttrpg-dev characters show misu_park
# Roll a skill or attribute check for a character
ttrpg-dev characters roll misu_park skill acrobatics
# Acrobatics check: 18 (1d20: 14, bonus: +4)
```
## Development Setup
**Prerequisites**: [asdf](https://asdf-vm.com/) with the `erlang`, `elixir`, and `zig` plugins.
```bash
git clone https://github.com/TTRPG-Dev/ex_ttrpg_dev.git
cd ex_ttrpg_dev
asdf install # installs Erlang, Elixir, and Zig from .tool-versions
mix deps.get
```
**Run the CLI locally** (no Zig required):
```bash
mix escript
./ttrpg-dev
```
**Build Burrito binaries** (requires Zig):
```bash
./scripts/build_cli.sh
./burrito_out/ttrpg_dev_cli_linux
```
## Contributing
1. Fork the repo and create a branch from `main`
2. Install dependencies: `mix deps.get`
3. Make your changes and add tests
4. Run the test suite: `mix test --umbrella`
5. Run the linter: `mix credo --umbrella`
6. Submit a pull request against `main`