Ultimate Dice Roll Toolkit

System Architecture: 29-Script Framework Design

The Ultimate Dice Roll Toolkit follows a carefully-designed four-layer architecture that balances simplicity for basic use cases with powerful extensibility for complex gaming scenarios. This document explains the architectural decisions, design patterns, and integration points based on the actual 29 C# scripts in the codebase.

Design Philosophy: The architecture follows the facade pattern at the API level, strategy pattern for different roll types, command pattern for conditional rules, and singleton pattern for session management. Each layer has clear responsibilities and minimal coupling.

Table of Contents

Architectural Overview

Layer-by-Layer Analysis

Component Analysis

Integration Patterns

Architectural Overview

Four-Layer Design

The 29 scripts are organized into a clean four-layer architecture:

Layer 1: API Facade (1 script)

  • DiceAPI.cs - Single entry point with 32 static methods

Layer 2: Engine Layer (2 scripts)

  • DiceRollEngine.cs - Core rolling mechanics
  • ProbabilityEngine.cs - Statistical analysis engine

Layer 3: Data Layer (4 scripts)

  • DiceConfiguration.cs - Dice setup and configuration
  • ConditionalRule.cs - Rule definitions
  • DiceSession.cs - Multi-dice sessions
  • OpposedRollConfig.cs - Contest configurations

Layer 4: Core Foundation (7 scripts)

  • DiceEnums.cs - Type definitions
  • DataStructures.cs - Result containers
  • SeededRandom.cs - Deterministic RNG
  • RandomProvider.cs - RNG abstraction
  • ModifierSession.cs - Session state management

Design Patterns Used

Facade Pattern

Implementation: DiceAPI.cs provides unified access to all functionality

Benefit: Simplified interface hiding complexity

Singleton Pattern

Implementation: ModifierSession.cs manages global state

Benefit: Thread-safe modifier accumulation

Strategy Pattern

Implementation: Roll types in DiceRollEngine.cs

Benefit: Extensible roll mechanics

Template Method

Implementation: Template generation system

Benefit: Consistent configuration patterns

File Organization

Scripts/ (29 files total)

  • API/ (1 file) - DiceAPI.cs
  • Core/ (5 files) - Foundation systems
  • Data/ (4 files) - ScriptableObject configurations
  • Engine/ (2 files) - Processing engines
  • Editor/ (5 files) - Unity editor integration
  • Utility/ (12 files) - Support systems and templates

Layer-by-Layer Analysis

API Layer: DiceAPI.cs

The DiceAPI serves as the single entry point with 32 carefully designed methods:

Basic Rolling (8 methods)

  • Roll, RollDetailed - Simple die rolling
  • RollAdvantage, RollDisadvantage - D&D 5e mechanics
  • RollExploding - Savage Worlds style
  • RollPool - Success counting systems
  • RollDrop - Variance reduction
  • RollTarget - Success/failure evaluation

Advanced Rolling (8 methods)

  • RollWithRules - Conditional rule processing
  • RollOpposed - Contest resolution
  • RollSession - Multi-dice sessions
  • CreateSession, CreateSessionAsset - Session management
  • Template creation methods

Analysis and Utility (16 methods)

  • Probability calculation methods
  • Seeded random initialization
  • Configuration import/export
  • Validation and debugging

Engine Layer: Processing Cores

DiceRollEngine.cs

Responsibility: Core rolling mechanics for all 6 roll types

Key Features:

  • Roll type strategy implementation
  • Reroll mechanics with configurable conditions
  • Weighted probability distributions
  • Target number evaluation
  • Performance optimization for hot paths

Performance: Sub-millisecond for simple rolls

ProbabilityEngine.cs

Responsibility: Statistical analysis via Monte Carlo simulation

Key Features:

  • 1K-100K iteration simulations
  • Complete statistical breakdowns
  • Range and threshold probability calculations
  • Configuration comparison analysis

Use Cases: Game balance testing, difficulty tuning

Data Layer: ScriptableObject Configurations

DiceConfiguration.cs

Purpose: Complete die setup with all options

Properties: sides, rollType, modifier, rerollConfig, dropConfig, weightConfig, targetConfig

Validation: Comprehensive with helpful error messages

ConditionalRule.cs

Purpose: If-then rule definitions

Structure: 11 trigger types × 7 action types = 77 combinations

Features: Priority system, chaining, validation

DiceSession.cs

Purpose: Multi-dice session management

Capabilities: Up to 20 dice per session, labeled results, enable/disable

Modes: Simultaneous and sequential rolling

OpposedRollConfig.cs

Purpose: Contest configuration for two sides

Resolution Modes: Simple, Margin, Contested, Blackjack

Features: Multi-dice support per side, template generation

Core Layer: Foundation Systems

DiceEnums.cs

Comprehensive type definitions for all system components

  • RollType (6 values) - Normal, Advantage, Disadvantage, Exploding, Pool, Drop
  • TriggerType (11 values) - OnMax, OnMin, OnValue, OnRange, etc.
  • ActionType (7 values) - RollBonus, AddValue, MultiplyResult, etc.
  • Supporting enums for comparisons, weights, and modes

DataStructures.cs

Rich result containers with comprehensive metadata

  • RollResult: Complete roll outcome with natural and total results
  • TargetResult: Success/failure evaluation with margin data
  • OpposedResult: Contest results with winner determination
  • SessionResult: Multi-dice session outcomes with aggregation

RandomProvider.cs

Abstraction layer for random number generation

  • Unity Random mode for normal gameplay
  • Seeded Random mode for deterministic results
  • Seamless mode switching
  • Consistent API across all rolling operations

ModifierSession.cs

Thread-safe singleton for global modifier management

  • Accumulates modifiers from conditional rules
  • Thread-safe with lock-based synchronization
  • Detailed history tracking for debugging
  • Clear and reset functionality

Component Analysis

Editor Integration (5 scripts)

Custom Inspectors (3 scripts)

  • DiceConfigurationEditor.cs - Enhanced inspector with foldouts
  • ConditionalRuleEditor.cs - Rule visualization
  • OpposedRollConfigEditor.cs - Contest editor

Editor Wizards (2 scripts)

  • DiceSessionWizard.cs - Template-based session creation
  • ProbabilityCalculatorWizard.cs - Visual analysis interface

Utility Systems (6 scripts)

Import/Export System (2 scripts)

  • ImportExportSystem.cs - JSON serialization engine
  • ImportExportWizard.cs - Editor wizard interface

Enables sharing configurations between projects and users

Template Generation (4 scripts)

  • TemplateGenerationSystem.cs - Core template engine
  • MasterTemplateData.cs - Complete framework template
  • DiceTemplateData.cs - Dice configuration templates
  • RuleTemplateData.cs - Rule system templates

Provides AI-consumable documentation and quick-start templates

Template System Architecture

The template system provides structured data for AI integration and user onboarding:

Master Templates

Complete framework documentation with all 77 rule combinations documented

Component Templates

Focused templates for specific components (dice, rules, sessions)

Use Case Templates

Common scenarios like D&D combat, skill challenges, crafting systems

Integration Patterns

Data Flow Architecture

1. API Entry

DiceAPI validates inputs and routes to appropriate engine

2. Engine Processing

DiceRollEngine or ProbabilityEngine handles core logic

3. Foundation Services

RandomProvider generates numbers, ModifierSession applies effects

4. Result Assembly

DataStructures contain results with comprehensive metadata

Error Handling Strategy

Input Validation

API layer validates all parameters before processing

  • Range checking (dice sides 2-1000, modifiers -99 to +99)
  • Null reference validation
  • Configuration consistency checks

Graceful Degradation

Invalid configurations produce error results instead of exceptions

  • Descriptive error messages in result objects
  • Safe fallback values where appropriate
  • Continued operation despite individual failures

Debug Support

Comprehensive logging and inspection capabilities

  • Detailed operation logs
  • Performance timing information
  • State inspection utilities

Performance Design

Memory Management

  • Minimal object allocation during rolling
  • Object reuse patterns where safe
  • Garbage collection awareness

Computational Efficiency

  • Hot path optimization in DiceRollEngine
  • Lazy evaluation for complex calculations
  • Early exit strategies for expensive operations

Resource Limits

  • Maximum 20 dice per session (recommended)
  • Explosion limits to prevent infinite loops
  • Reroll limits for bounded execution time
  • Probability iteration limits for controlled analysis time
Architectural Excellence: This 29-script architecture provides the perfect balance of simplicity for beginners and power for advanced users. Each layer has clear responsibilities, minimal coupling, and clean extension points. The result is a system that's easy to use, maintain, and extend while remaining performant in production environments.

Quick Nav