RPG Tools

Mechanical tools for solo RPG sessions. Run scripts from scripts/.

Dice Rolling

Roll20-compatible notation with full modifier support.

bash

python scripts/dice.py "2d6+5"        # Basic roll with modifier
python scripts/dice.py "4d6kh3"       # Keep highest 3 (ability scores)
python scripts/dice.py "2d20kh1+5"    # Advantage
python scripts/dice.py "8d6!"         # Exploding dice
python scripts/dice.py "4dF"          # Fudge/Fate dice
python scripts/dice.py "6d10>=7"      # Count successes

Supports: kh/kl (keep), dh/dl (drop), r/rr (reroll), ! (exploding), !! (compounding), !p (penetrating), comparison operators for success counting.

Tarot

Draw cards for oracular guidance.

bash

python scripts/tarot.py         # Single card
python scripts/tarot.py 3       # Three-card spread (past/present/future)
python scripts/tarot.py 5       # Five-card spread

Max 10 cards per draw. Full 78-card deck (Major + Minor Arcana).

Name Generation

Generate names from campaign namesets. Requires nameset JSON files in namesets/ directory relative to script parent.

bash

python scripts/namegen.py list                              # Show available namesets
python scripts/namegen.py full --nameset ice-age-names      # Generate one name
python scripts/namegen.py full --nameset early-neolithic-names --count 5

Namesets define format strings (e.g., {firstName} {epithet}) and weighted name categories.

Story Collections

Retrieve folklore and character stories. Requires story JSON files in stories/ directory relative to script parent.

bash

python scripts/stories.py meta --campaign SESSION           # Show available tags/counts
python scripts/stories.py list --campaign SESSION           # List all stories
python scripts/stories.py random --campaign SESSION         # Random story
python scripts/stories.py random --campaign SESSION --theme loss --mood melancholic
python scripts/stories.py show --campaign SESSION --story STORY_ID

Filter options: --collection, --theme, --mood, --era

Characters

Load character profiles on-demand. Requires character JSON files in characters/ directory relative to script parent.

bash

python scripts/characters.py list                        # List character names
python scripts/characters.py list --short                # Show minimal profiles
python scripts/characters.py get NAME                    # Get minimal profile
python scripts/characters.py get NAME --depth full       # Get full profile
python scripts/characters.py get NAME --section powers   # Get specific section
python scripts/characters.py sections NAME               # List available sections

Filter options: --faction, --subfaction, --tag

Locations

Load location profiles with hierarchy/graph support. Requires location JSON files in locations/ directory relative to script parent.

bash

python scripts/locations.py list                         # List all locations
python scripts/locations.py list --tag settlement        # Filter by tag
python scripts/locations.py list --parent LOCATION       # List children
python scripts/locations.py tree                         # Show full hierarchy
python scripts/locations.py tree LOCATION                # Show subtree
python scripts/locations.py get NAME                     # Get minimal profile
python scripts/locations.py get NAME --depth full        # Get full profile
python scripts/locations.py path NAME                    # Show path from root
python scripts/locations.py connections NAME             # Show all connections

Filter options: --tag, --parent, --type

Memories

Campaign memory tracking with cross-references. Requires memory JSON files in memories/ directory relative to script parent.

bash

python scripts/memories.py list --campaign NAME                    # List all memories
python scripts/memories.py list --short --campaign NAME            # List with details (no text)
python scripts/memories.py list --character NAME                   # Filter by character
python scripts/memories.py list --type vivid-moment                # Filter by type
python scripts/memories.py get ID                                  # Get specific memory
python scripts/memories.py random --campaign NAME                  # Random memory
python scripts/memories.py search "query" --campaign NAME          # Full-text search
python scripts/memories.py character NAME                          # All memories with character
python scripts/memories.py location NAME                           # All memories at location

Filter options: --character, --location, --type, --tag, --era, --session, --intensity, --perspective

Oracle

Multi-system oracle for injecting randomness and stimulating interpretation.

bash

python scripts/oracle.py axis              # Multi-axis reading (tone/direction/element/action/twist)
python scripts/oracle.py omni              # Full reading: axis + tarot + rune + I Ching + fate + prompt
python scripts/oracle.py tarot [n]         # Draw tarot card(s)
python scripts/oracle.py rune [n]          # Draw Elder Futhark rune(s)
python scripts/oracle.py iching            # Cast I Ching hexagram
python scripts/oracle.py fate [likelihood] # Yes/no oracle (impossible/unlikely/even/likely/certain)
python scripts/oracle.py prompt            # Action + Theme word pair

Session Workflow

Guides for before and after play:

•Session Setup - Calibrate tone, direction, and pacing before starting
•Session Debrief - Post-session reflection for closure and character growth

Optional modifiers to load when needed:

•Mature Content - For authentic dark themes
•Combat Realism - For grounded, consequential violence

Content Creation

For creating new campaign content, see the detailed guides:

•Creating Namesets - Schema and guidelines for building name collections for new cultures/eras
•Capturing Stories - Template and workflow for extracting stories from sessions into JSON collections
•Creating Characters - Schema and workflow for building character JSON profiles
•Creating Locations - Schema and workflow for hierarchical location data