Ultimate Dice Roll Toolkit

API Reference

Complete documentation of all public methods in the DiceAPI class. This reference covers the exact method signatures, parameters, and return types as they exist in the codebase.

API Access: All methods are static and accessed through the DiceAPI class. Import the namespace: using UltimateDiceToolkit;

API Categories

Basic Rolling

  • Roll
  • RollMultiple
  • RollAdvantage
  • RollDisadvantage

Advanced Rolling

  • RollAdvanced
  • RollWithTarget
  • RollExploding
  • RollPool
  • RollDrop
  • RollWeighted
  • RollWithReroll

Conditional Rules

  • ProcessConditionalRules
  • RollWithRules

Opposed Rolls

  • ExecuteOpposedRoll
  • QuickOpposedRoll
  • QuickAbilityContest

Probability Analysis

  • CalculateProbability
  • CalculateRangeProbability
  • GetProbabilityDistribution

Configuration Management

  • ExportConfiguration
  • ExportSpecific
  • ImportConfiguration
  • SaveConfigurationToFile
  • LoadConfigurationFromFile

Seeded Operations

  • InitializeSeed
  • DisableSeed
  • IsSeedActive
  • ResetSeed

Session Management

  • StartModifierSession
  • EndModifierSession
  • EndAndClearModifierSession
  • ResetSessionModifiers
  • GetSessionModifiers
  • GetSessionHistory
  • GetSessionSummary
  • GetSessionBreakdown
  • HasSessionModifiers

Multi-Dice Sessions

  • CreateSession
  • RollSession
  • RollMultipleDifferent
  • QuickRollSet
  • RollSessionWithRules
  • CreateSessionAsset
  • ValidateSession
  • GetSessionPerformanceEstimate

Session Templates

  • CreateDnDCombatSession
  • CreateSkillChallengeSession
  • CreateDamageBreakdownSession

Basic Rolling

Roll

public static int Roll(int sides, int modifier = 0, bool useSession = true)

Parameters:

  • sides - Number of sides (2-1000, automatically clamped)
  • modifier - Explicit modifier to add to roll
  • useSession - Whether to apply accumulated session modifiers

Returns: Roll result (1 to sides) + modifiers

Behavior: Session modifiers are consumed when used. Result is clamped to minimum 1.

RollMultiple

public static int[] RollMultiple(int sides, int count, int modifier = 0, bool useSession = true, RollMode mode = RollMode.Simultaneous)

Parameters:

  • sides - Number of sides per die (2-1000, automatically clamped)
  • count - Number of dice to roll (1-100, automatically clamped)
  • modifier - Explicit modifier to add to each roll
  • useSession - Whether to apply session modifiers to first roll only
  • mode - RollMode.Simultaneous or RollMode.Sequential

Returns: Array of individual results

Behavior: Session modifiers only apply to first die to avoid consuming multiple times.

RollAdvantage

public static int RollAdvantage(int sides, int modifier = 0, bool useSession = true)

Parameters:

  • sides - Number of sides
  • modifier - Explicit modifier to add to final result
  • useSession - Whether to apply accumulated session modifiers

Returns: Higher of two rolls + modifiers

Behavior: Logs both rolls and best result. Session modifiers consumed before rolling.

RollDisadvantage

public static int RollDisadvantage(int sides, int modifier = 0, bool useSession = true)

Parameters:

  • sides - Number of sides
  • modifier - Explicit modifier to add to final result
  • useSession - Whether to apply accumulated session modifiers

Returns: Lower of two rolls + modifiers

Behavior: Logs both rolls and worst result. Session modifiers consumed before rolling.

Advanced Rolling

RollAdvanced

public static RollResult RollAdvanced(DiceConfiguration config, int modifier = 0, bool useSession = true)

Parameters:

  • config - DiceConfiguration ScriptableObject
  • modifier - Explicit modifier to add to roll
  • useSession - Whether to apply accumulated session modifiers

Returns: RollResult with detailed metadata

Behavior: Supports all 6 roll types from RollType enum. Delegates to DiceRollEngine.RollWithType.

RollWithTarget

public static TargetResult RollWithTarget(DiceConfiguration config, TargetConfiguration targetConfig, int modifier = 0, bool useSession = true)

Parameters:

  • config - Dice configuration
  • targetConfig - Target evaluation settings
  • modifier - Explicit modifier to add to roll
  • useSession - Whether to apply accumulated session modifiers

Returns: TargetResult with success/failure data, or null if target disabled

Behavior: Calculates margin and degrees of success (margin รท 5).

RollExploding

public static RollResult RollExploding(int sides, int maxExplosions = 10, int modifier = 0, bool useSession = true)

Parameters:

  • sides - Number of sides
  • maxExplosions - Maximum number of explosions
  • modifier - Explicit modifier to add to roll
  • useSession - Whether to apply accumulated session modifiers

Returns: RollResult with explosion metadata

Behavior: Creates temporary configuration with RollType.Exploding.

RollPool

public static RollResult RollPool(int sides, int poolSize, int threshold = 0, int modifier = 0, bool useSession = true)

Parameters:

  • sides - Number of sides per die
  • poolSize - Number of dice in pool
  • threshold - Success threshold (auto-calculated if 0)
  • modifier - Explicit modifier to add to each die
  • useSession - Whether to apply accumulated session modifiers

Returns: RollResult where successCount is the pool result

Behavior: Creates temporary configuration with RollType.Pool.

RollDrop

public static RollResult RollDrop(int sides, int diceCount, int dropCount, DropType dropType = DropType.Lowest, int modifier = 0, bool useSession = true)

Parameters:

  • sides - Number of sides
  • diceCount - Total dice to roll
  • dropCount - Number of dice to drop
  • dropType - DropType.Lowest or DropType.Highest
  • modifier - Explicit modifier to add to final result
  • useSession - Whether to apply accumulated session modifiers

Returns: RollResult with drop metadata

Behavior: Creates temporary configuration with RollType.Drop and DropConfiguration.

RollWeighted

public static RollResult RollWeighted(int sides, WeightAlgorithm algorithm, int modifier = 0, bool useSession = true)

Parameters:

  • sides - Number of sides
  • algorithm - WeightAlgorithm (Normal, BiasHigh, BiasLow, Dramatic, Bell)
  • modifier - Explicit modifier to add to roll
  • useSession - Whether to apply accumulated session modifiers

Returns: RollResult with weighted outcome

Behavior: Creates temporary configuration with WeightConfiguration.

RollWithReroll

public static RollResult RollWithReroll(int sides, RerollType rerollType, int[] rerollValues = null, int threshold = 1, int maxRerolls = 1, int modifier = 0, bool useSession = true)

Parameters:

  • sides - Number of sides
  • rerollType - RerollType (Exact, Below, Above, Range)
  • rerollValues - Values to reroll (for exact type, defaults to {1})
  • threshold - Threshold for above/below rerolls
  • maxRerolls - Maximum number of rerolls
  • modifier - Explicit modifier to add to roll
  • useSession - Whether to apply accumulated session modifiers

Returns: RollResult after reroll processing

Behavior: Creates temporary configuration with RerollConfiguration.

Conditional Rules

ProcessConditionalRules

public static (RollResult result, int nextRollModifier) ProcessConditionalRules(RollResult result, ConditionalRule[] rules, int currentModifier = 0)

Parameters:

  • result - Initial roll result
  • rules - Array of conditional rules to evaluate
  • currentModifier - Current accumulated modifier from previous rules

Returns: Tuple of modified result and accumulated next roll modifier

Behavior: Delegates to RuleProcessor.ProcessConditionalRules. Logs rule executions.

RollWithRules

public static (RollResult result, int nextRollModifier) RollWithRules(DiceConfiguration config, ConditionalRule[] rules, int modifier = 0, bool useSession = true)

Parameters:

  • config - Dice configuration
  • rules - Conditional rules to apply
  • modifier - Explicit modifier to add to roll
  • useSession - Whether to apply accumulated session modifiers

Returns: Tuple of final result and accumulated next roll modifier

Behavior: Rolls first, then processes rules on the result.

Opposed Rolls

ExecuteOpposedRoll

public static OpposedResult ExecuteOpposedRoll(OpposedRollConfig config)

Parameters:

  • config - OpposedRollConfig ScriptableObject

Returns: OpposedResult with winner determination

Behavior: Delegates to OpposedRollEngine.ExecuteOpposedRoll.

QuickOpposedRoll

public static OpposedResult QuickOpposedRoll(DiceConfiguration attackerDice, DiceConfiguration defenderDice, ResolutionMode mode = ResolutionMode.Simple, int marginRequired = 0)

Parameters:

  • attackerDice - Attacker's dice configuration
  • defenderDice - Defender's dice configuration
  • mode - ResolutionMode (Simple, Margin, Contested, Blackjack)
  • marginRequired - Required margin for margin mode

Returns: OpposedResult with contest results

Behavior: Delegates to OpposedRollEngine.QuickOpposedRoll.

QuickAbilityContest

public static OpposedResult QuickAbilityContest(int attackerModifier = 0, int defenderModifier = 0)

Parameters:

  • attackerModifier - Attacker's ability modifier
  • defenderModifier - Defender's ability modifier

Returns: OpposedResult with contest results

Behavior: Delegates to OpposedRollEngine.QuickAbilityContest.

Probability Analysis

CalculateProbability

public static ProbabilityResult CalculateProbability(DiceConfiguration config, int targetValue, ComparisonType comparison, int iterations = 50000)

Parameters:

  • config - Dice configuration to analyze
  • targetValue - Value to test probability against
  • comparison - ComparisonType (GreaterEqual, Greater, Equal, Less, LessEqual)
  • iterations - Number of simulations (default 50,000)

Returns: ProbabilityResult with statistical analysis

Behavior: Delegates to ProbabilityEngine.CalculateProbability.

CalculateRangeProbability

public static ProbabilityResult CalculateRangeProbability(DiceConfiguration config, int minValue, int maxValue, int iterations = 50000)

Parameters:

  • config - Dice configuration to analyze
  • minValue - Minimum value (inclusive)
  • maxValue - Maximum value (inclusive)
  • iterations - Number of simulations

Returns: ProbabilityResult with range probability

Behavior: Delegates to ProbabilityEngine.CalculateRangeProbability.

GetProbabilityDistribution

public static System.Collections.Generic.Dictionary<int, float> GetProbabilityDistribution(DiceConfiguration config, int iterations = 50000)

Parameters:

  • config - Dice configuration to analyze
  • iterations - Number of simulations

Returns: Dictionary of outcome to probability percentage

Behavior: Delegates to ProbabilityEngine.CalculateDistribution.

Configuration Management

ExportConfiguration

public static string ExportConfiguration(bool includeHistory = false, string description = "")

Parameters:

  • includeHistory - Include roll history in export
  • description - Description for the export

Returns: JSON configuration string

Behavior: Delegates to ImportExportSystem.ExportToJson.

ExportSpecific

public static string ExportSpecific(DiceConfiguration[] diceConfigs = null, ConditionalRule[] rules = null, OpposedRollConfig[] opposedConfigs = null, string description = "")

Parameters:

  • diceConfigs - Dice configurations to export
  • rules - Conditional rules to export
  • opposedConfigs - Opposed roll configs to export
  • description - Description for the export

Returns: JSON configuration string

Behavior: Delegates to ImportExportSystem.ExportSpecific.

ImportConfiguration

public static bool ImportConfiguration(string configJson, bool createAssets = true, string assetPath = "Assets/Ultimate Dice Roll Toolkit/Imported/")

Parameters:

  • configJson - JSON configuration string
  • createAssets - Whether to create ScriptableObject assets
  • assetPath - Path to create assets in

Returns: Success status

Behavior: Delegates to ImportExportSystem.ImportFromJson.

SaveConfigurationToFile

public static bool SaveConfigurationToFile(string filePath, bool includeHistory = false, string description = "")

Parameters:

  • filePath - File path to save to
  • includeHistory - Include roll history
  • description - Export description

Returns: Success status

Behavior: Calls ExportConfiguration then ImportExportSystem.SaveToFile.

LoadConfigurationFromFile

public static bool LoadConfigurationFromFile(string filePath, bool createAssets = true, string assetPath = "Assets/Ultimate Dice Roll Toolkit/Imported/")

Parameters:

  • filePath - File path to load from
  • createAssets - Whether to create ScriptableObject assets
  • assetPath - Path to create assets in

Returns: Success status

Behavior: Calls ImportExportSystem.LoadFromFile then ImportConfiguration.

Seeded Operations

InitializeSeed

public static void InitializeSeed(object seed)

Parameters:

  • seed - Seed value (string or int)

Behavior: Delegates to RandomProvider.InitializeSeed.

DisableSeed

public static void DisableSeed()

Behavior: Delegates to RandomProvider.DisableSeed.

IsSeedActive

public static bool IsSeedActive { get; }

Returns: True if seeded mode is currently active

Behavior: Property that delegates to RandomProvider.IsSeedActive.

ResetSeed

public static void ResetSeed()

Behavior: Delegates to RandomProvider.ResetSeed.

Session Management

StartModifierSession

public static void StartModifierSession()

Behavior: Delegates to ModifierSession.StartSession.

EndModifierSession

public static void EndModifierSession()

Behavior: Delegates to ModifierSession.EndSession. Preserves accumulated modifiers.

EndAndClearModifierSession

public static void EndAndClearModifierSession()

Behavior: Delegates to ModifierSession.EndSessionAndClear.

ResetSessionModifiers

public static void ResetSessionModifiers()

Behavior: Delegates to ModifierSession.ResetSession.

GetSessionModifiers

public static int GetSessionModifiers()

Returns: Current accumulated modifier value

Behavior: Delegates to ModifierSession.PeekAccumulatedModifier. Does not consume modifiers.

GetSessionHistory

public static ModifierSource[] GetSessionHistory()

Returns: Array of modifier sources with metadata

Behavior: Delegates to ModifierSession.GetModifierHistory.

GetSessionSummary

public static string GetSessionSummary()

Returns: Human-readable session summary

Behavior: Delegates to ModifierSession.GetSessionSummary.

GetSessionBreakdown

public static string GetSessionBreakdown()

Returns: Formatted string with all modifier details

Behavior: Delegates to ModifierSession.GetDetailedBreakdown.

HasSessionModifiers

public static bool HasSessionModifiers()

Returns: True if modifiers are waiting to be applied

Behavior: Delegates to ModifierSession.HasUnconsumedModifiers.

Multi-Dice Sessions

CreateSession

public static DiceSession CreateSession(string sessionName = "New Session")

Parameters:

  • sessionName - Name for the new session

Returns: New DiceSession ScriptableObject

Behavior: Creates instance with ScriptableObject.CreateInstance. Logs creation.

RollSession

public static SessionResult RollSession(DiceSession session, int modifier = 0, bool useSession = true)

Parameters:

  • session - DiceSession to execute
  • modifier - Explicit modifier to apply to all dice in session
  • useSession - Whether to apply accumulated session modifiers

Returns: SessionResult with individual and aggregate results

Behavior: Delegates to SessionEngine.ExecuteSession.

RollMultipleDifferent

public static SessionResult RollMultipleDifferent(DiceConfiguration[] configs, string[] labels = null, int modifier = 0, bool useSession = true)

Parameters:

  • configs - Array of different dice configurations
  • labels - Optional labels for each die
  • modifier - Explicit modifier to apply to all dice
  • useSession - Whether to apply accumulated session modifiers

Returns: SessionResult with combined results

Behavior: Delegates to SessionEngine.ExecuteMultipleDifferent with sessionName "Multi-Dice Roll".

QuickRollSet

public static SessionResult QuickRollSet(int modifier = 0, bool useSession = true, params (DiceConfiguration config, string label)[] diceSet)

Parameters:

  • modifier - Explicit modifier for all dice
  • useSession - Whether to apply session modifiers
  • diceSet - Array of (config, label) tuples

Returns: SessionResult with named dice results

Behavior: Validates input, extracts configs and labels, delegates to SessionEngine.ExecuteMultipleDifferent.

RollSessionWithRules

public static (SessionResult result, int nextRollModifier) RollSessionWithRules(DiceSession session, ConditionalRule[] rules, int modifier = 0, bool useSession = true)

Parameters:

  • session - DiceSession to execute
  • rules - Conditional rules to apply to all dice
  • modifier - Explicit modifier for all dice
  • useSession - Whether to apply session modifiers

Returns: SessionResult and accumulated next roll modifiers

Behavior: Delegates to SessionEngine.ExecuteSessionWithRules.

CreateSessionAsset

public static DiceSession CreateSessionAsset(string sessionName, string assetPath = "Assets/Ultimate Dice Roll Toolkit/Sessions/")

Parameters:

  • sessionName - Name for the session
  • assetPath - Path to save the asset

Returns: Created and saved DiceSession asset

Behavior: Editor-only. Creates directory, generates unique filename, uses UnityEditor.AssetDatabase. Returns regular session in builds.

ValidateSession

public static bool ValidateSession(DiceSession session, out string errorMessage)

Parameters:

  • session - Session to validate
  • errorMessage - Output error message if validation fails

Returns: True if session is valid and ready to execute

Behavior: Null check, then delegates to session.IsValid.

GetSessionPerformanceEstimate

public static (float estimatedTimeMs, int estimatedMemoryKB) GetSessionPerformanceEstimate(DiceSession session)

Parameters:

  • session - Session to analyze

Returns: Estimated execution time and memory usage

Behavior: Returns (0,0) if session null, otherwise delegates to SessionEngine.GetPerformanceEstimate.

Session Templates

CreateDnDCombatSession

public static DiceSession CreateDnDCombatSession(DiceConfiguration attackDie, DiceConfiguration damageDie, string sessionName = "D&D Combat")

Parameters:

  • attackDie - Attack roll configuration
  • damageDie - Damage roll configuration
  • sessionName - Name for the session

Returns: Configured DiceSession ready for combat

Behavior: Creates session, sets description, adds dice with labels "Attack Roll" and "Damage Roll".

CreateSkillChallengeSession

public static DiceSession CreateSkillChallengeSession(DiceConfiguration[] skillConfigs, string[] skillNames = null, string sessionName = "Skill Challenge")

Parameters:

  • skillConfigs - Array of skill check configurations
  • skillNames - Names of the skills
  • sessionName - Name for the session

Returns: Configured DiceSession for skill challenges

Behavior: Creates session, sets description, iterates configs adding them with provided names or defaults.

CreateDamageBreakdownSession

public static DiceSession CreateDamageBreakdownSession(DiceConfiguration[] damageConfigs, string[] damageTypes = null, string sessionName = "Damage Breakdown")

Parameters:

  • damageConfigs - Array of different damage type configurations
  • damageTypes - Names of damage types
  • sessionName - Name for the session

Returns: Configured DiceSession for complex damage calculations

Behavior: Creates session, sets description, iterates configs adding them with provided names or defaults.

Parameter Validation: The API automatically validates and clamps parameters. Invalid configurations will not crash but may produce warnings.

Session Modifiers: Session modifiers are consumed when used. They only apply to the first die in multi-dice operations to prevent multiple consumption.

Quick Nav