ExTTRPGDev

ExTTRPGDev is a general tabletop role-playing game utility written in Elixir.

Table of Contents

• ExTTRPGDev
  • Table of Contents
  • Library Installation
  • CLI Installation
    • Linux
    • macOS (Intel)
    • macOS (Apple Silicon)
    • Windows
  • Usage
    • Rolling dice
    • Rule systems
    • Characters
  • Development Setup
  • Contributing

Library Installation

ExTTRPGDev is available in Hex, the package can be installed by adding ex_ttrpg_dev to your list of dependencies in mix.exs:

def deps do
  [
    {:ex_ttrpg_dev, "~> 0.2.1"}
  ]
end

CLI Installation

Pre-built binaries are available on the releases page.

Linux

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)

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)

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, 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 with the erlang, elixir, and zig plugins.

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):

mix escript
./ttrpg-dev

Build Burrito binaries (requires Zig):

./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