README

PHP library for parsing and rolling dice expressions for tabletop RPG systems.

PHPDice is a powerful and flexible library that allows developers to parse and roll complex dice expressions used in various tabletop role-playing games (RPGs). It supports a wide range of dice mechanics, including advantage/disadvantage, success counting, rerolls, exploding dice, critical hits, and more.

Features

🎲 Universal Dice Notation: Support for all major RPG systems (D&D 5e, Pathfinder, Shadowrun, World of Darkness, FATE, Savage Worlds, etc.)
⚡ Advanced Mechanics: Advantage/disadvantage, success counting, rerolls, exploding dice, critical detection, DC comparisons
📊 Statistical Analysis: Pre-calculated min/max/expected values for any expression
🔧 Placeholder Variables: Character sheet integration with $variable$ syntax
➗ Complex Arithmetic: Full expression evaluation with operator precedence and parentheses
❗ Error Handling: Clear, specific error messages with location information
🚀 High Performance: Parse <100ms, Roll <50ms for complex expressions
🔒 Type Safe: Full PHP 8.1+ type declarations and strict mode
⚡ Zero Dependencies: Pure PHP 8.1+ implementation using only stdlib and ctype extension
🧪 Well Tested: Unit tests with comprehensive coverage
📦 PSR-12 Compliant: Modern PHP coding standards

Requirements

PHP 8.1 or higher
ctype PHP extension enabled

Installation

composer require codryn/phpdice

Quick Start and Usage

<?php
require 'vendor/autoload.php';

use Codryn\PHPDice\PHPDice;

// Create instance
$dice = new PHPDice();

// Roll dice directly
$result = $dice->roll("3d6");

echo "Rolled: " . $result->total . "\n";
echo "Dice: " . implode(", ", $result->diceValues) . "\n";

// Example output:
// Rolled: 14
// Dice: 5, 6, 3

See docs/quickstart.md for a 10-minute tutorial.

Dice Expressions

See docs/expressions.md for all supported dice expressions.

Game System Support

System	Example	Features
D&D 5e	`1d20 auto 20 crit 20 +5 dc >= 15`	Auto success, criticals, modifiers, comparisons
Pathfinder	`3d6+2`	Basic dice, modifiers
Shadowrun 5e	`12d6 edge count >=5`	Success counting, edge (Rule of Six)
World of Darkness	`10d10 >=8`	Success counting
FATE	`4dF+2`	Fudge dice, modifiers
Savage Worlds	`1d6 explode + 1d8 explode`	Exploding dice
Call of Cthulhu	`d%`	Percentile dice
Even/Odd Counting	`6d6 count even` or `12d4 count odd`	Count even or odd results

API Overview

See docs/api.md for complete reference.

Documentation

Quick Start Guide - 10-minute tutorial
Dice Expressions - All supported dice expressions
API Documentation - Complete API reference with examples
Examples - Game system specific examples

Development

See CONTRIBUTING.md for development guidelines.

Architecture

PHPDice is structured into several key components:

Parser: Converts dice expression strings into an Abstract Syntax Tree (AST) using a recursive descent parser.
Model: Represents the AST nodes, dice expressions, roll results, and related data structures.
Roller: Evaluates the AST to perform dice rolls, applying game mechanics

Performance

PHPDice is optimized for real-time use:

Parsing: <100ms for complex expressions
Rolling: <50ms for typical rolls
Memory: <1MB per operation

Tips for best performance:

Reuse parsed DiceExpression objects for repeated rolls
Set reasonable explosion/reroll limits (default 100 is safe)
Use getStatistics() for probability analysis instead of Monte Carlo simulation

Quality Standards

✅ PHPStan Level 10: Strictest static analysis level from PHPSTan 2.1
✅ PSR-12: PHP coding standards compliance
✅ Strict Types: declare(strict_types=1) in all files
✅ TDD: Test-driven development methodology
✅ Type Hints: Full type declarations on all methods
✅ PHPDoc: Complete documentation blocks

Contributing

Contributions are welcome! See CONTRIBUTING.md for:

Development workflow
Coding standards
Testing requirements
Pull request process

License

This project is licensed under the MIT License - see the LICENSE file for details.

Changelog

See CHANGELOG.md for version history and migration guides.

Support

Credits

Created and maintained by Marco for Codryn.

Special thanks to:

The PHP community
PHPUnit, PHPStan, and PHP-CS-Fixer maintainers

Game Systems Copyright

This library implements dice roll mechanics from various tabletop RPG systems for non-commercial use. All game system names, mechanics, and related intellectual property remain the property of their respective copyright holders. See GAME_SYSTEMS_COPYRIGHT.md for detailed copyright notices and attributions.

Built for the tabletop RPG community 🎲

codryn / phpdice

Maintainers

Details