README

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

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.0+ type declarations and strict mode
• Well Tested: 235+ tests with comprehensive coverage

Requirements

• PHP 8.0 or higher

Installation

composer require phpdice/phpdice

Quick Start and Usage

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

use 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

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.

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

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome! See CONTRIBUTING.md for:

• Development workflow
• Coding standards
• Testing requirements
• Pull request process

Changelog

See CHANGELOG.md for version history and migration guides.

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

Credits

Developed with adherence to:

• PSR-12 coding standards
• PHPStan level 9 strict analysis
• Test-Driven Development (TDD)
• Comprehensive documentation

Built for the tabletop RPG community 🎲