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

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

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions
• 📧 Email

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 🎲