Dice

Probability Director treats Dice as an exact, ordered probability system rather than as a collection of ad hoc random integer calls.

The Dice Runtime supports standard dice, custom numeric faces, weighted numeric definitions, heterogeneous expressions, rerolls, bounded explosions, ordered selection, Success Count pools, critical classification, Dice Bias, and a post-aggregation FlatModifier.

This document describes the Dice system itself: its mathematical and Runtime semantics, public API concepts, operation order, deterministic behavior, limits, and safe usage patterns.

For the Editor workflow, charts, Monte Carlo, isolated Lab samples, and exports, see Lab-Dice.md.

---

1. Purpose

Use Probability Director Dice when gameplay needs one or more of the following:

• Exact probability analysis.
• Reproducible Fixed-Seed rolls.
• Secure Runtime sampling.
• Sequential stream progression.
• Stable Keyed decisions.
• Weighted/custom dice.
• Mixed numeric dice terms.
• Rerolls.
• Explosions.
• Keep/drop selection.
• Advantage/disadvantage authoring.
• Dice pools and Success Count.
• Critical Success/Failure classification.
• Dice Bias.
• A normal post-roll additive modifier.

Typical uses include damage rolls, skill checks, tabletop-style systems, loot quality, randomized stats, and designer-authored weighted dice.

---

2. Core Numeric Die Model

A numeric die is an ordered collection of numeric outcomes with exact authored weight.

A fair D6 is conceptually:

Face	Weight
1	1
2	1
3	1
4	1
5	1
6	1

A weighted custom die might be:

Face	Weight
1	1
2	1
3	2
4	4

The authored weights define the Base Distribution.

Equal numeric outcomes are canonicalized before Dice Bias and exact analysis.

---

3. Standard Dice

The pure Make Standard Numeric Dice Pipeline helper supports:

• D4
• D6
• D8
• D10
• D12
• D20
• D100

The helper constructs a canonical Dice pipeline. It does not roll.

D100 is one die with 100 equally weighted numeric faces numbered 1 through 100. It is not percentile-pair or 00 notation.

Other face counts remain available through generic/custom numeric Dice authoring.

---

4. Custom and Weighted Numeric Dice

Custom dice may use:

• Negative outcomes.
• Sparse outcomes.
• Noncontiguous outcomes.
• Duplicate authored values.
• Unequal integer weights.

Example:

-2 : weight 1
 0 : weight 3
 5 : weight 5
10 : weight 1

Numeric order is semantic:

-2 < 0 < 5 < 10

Dice Bias uses that numeric order, not row order.

Duplicate numeric outcomes are merged before Bias.

---

5. Symbolic Outcomes

Symbolic/categorical outcomes do not automatically receive numeric Dice Bias.

Probability Director does not infer that:

Common < Rare < Epic

from names.

A future affinity/ranking contract would need to define such semantics explicitly.

Do not impose lexical ordering on symbolic outcomes merely to reuse numeric Dice Bias.

---

6. Dice Pipeline Order

The high-level Numeric Total pipeline is:

Generate face
    |
    +--> apply Dice Bias during generation
    |
    +--> bounded reroll/explosion mechanics
    |
    +--> construct complete candidate
    |
    +--> ordered selection where applicable
    |
    +--> aggregate
    |
    +--> FlatModifier
    |
    +--> classification where configured

This order is part of the behavior contract.

FlatModifier is not a face modifier.

Dice Bias is not a final arithmetic adjustment.

---

7. Dice Bias

DiceBias changes the probability of generated numeric faces.

It is not additive.

Direction	Meaning
Neutral	Preserve the Base Distribution exactly
Positive	Favor numerically higher generated faces
Negative	Favor numerically lower generated faces

The Runtime/API supports the exact range:

-100% ... 0% ... +100%

At the exact deterministic endpoints:

• +100% makes the highest numeric generated face certain.
• -100% makes the lowest numeric generated face certain.

Neutral is an exact identity path.

---

7.1 Exact Authoritative Bias

The authoritative Dice Bias path is exact.

Blueprint normally uses Make Probability Dice Bias with:

• Direction.
• Bias Percent.

C++ may construct/use the native exact representation directly.

Presentation percentages are designer-facing input, not an approximate floating authority.

---

7.2 Per-Face Application

Dice Bias applies independently to each generated face, including:

• Initial generation.
• Reroll replacements.
• Explosion children.

Selection and aggregation operate on the realized biased values.

---

7.3 Weighted Dice Stay Weighted

Bias reshapes the authored Base Distribution.

It does not first convert a weighted die to a uniform die.

For example:

1 : 5
2 : 3
3 : 2

remains the Base distribution before positive/negative Dice Bias is applied.

---

8. FlatModifier

FlatModifier is ordinary post-aggregation arithmetic.

Example:

2D6 + 5

means:

resolve 2D6
sum
add 5 once

It does not mean +5 to each generated die.

Use:

• Dice Bias to alter generated-face likelihood.
• FlatModifier to alter the final numeric total.

---

9. Heterogeneous Numeric Expressions

Supported Runtime paths can resolve mixed expressions such as:

2D6 + 1D4

as one logical operation.

Important semantics:

• Terms are sampled in authored order.
• Dice Bias applies to every generated numeric face.
• FlatModifier is applied once after final aggregation.
• One successful expression produces one final numeric result.

Unsupported specialized combinations return visible/structured failure rather than silently dropping mechanics.

---

10. Rerolls

Rerolls are bounded.

Probability Director does not perform unbounded retry-until-success loops.

Replacement generations use the same Dice Bias semantics as initial generations.

If a native reroll/work bound is reached, the operation reports a structured failure.

---

11. Exploding Dice

Explosion creates bounded additional generated faces/candidates.

Dice Bias applies to explosion children.

Explosion is intentionally bounded for Runtime safety and exact-analysis complexity control.

Excessive expressions report capacity/complexity failure instead of becoming unbounded.

---

12. Ordered Selection

Supported rules include:

• Keep Highest.
• Keep Lowest.
• Drop Highest.
• Drop Lowest.

The same authored rule feeds exact analysis and Runtime resolution.

There is no hidden offline-only selection rule.

---

13. Advantage and Disadvantage

Advantage/disadvantage are convenience authoring over ordered selection.

Conceptually:

Advantage:
Quantity 2
Keep Highest 1

Disadvantage:
Quantity 2
Keep Lowest 1

They are not a separate Dice mathematics system.

Use explicit ordered selection for more general keep/drop mechanics.

In V1.11 Resolution Rules, these are ordinary authored data combinations:

Advantage:    2xD20, Keep Highest 1
Disadvantage: 2xD20, Keep Lowest 1

V1.11 does not add dedicated Advantage or Disadvantage Runtime modes.

V1.11 Resolution Rules

Resolution Rules is a reusable authored layer over this existing authoritative Dice system. It has three modes:

• HomogeneousPipeline: one die and quantity with existing explosion, reroll, ordered keep/drop selection, FlatModifier, and Dice Bias behavior.
• HeterogeneousExpression: ordered terms with quantity per term, each using standard or explicit numeric faces, plus FlatModifier and Dice Bias. V1.11 adds no heterogeneous explosion, reroll, or selection algorithms.
• SuccessCount: the existing homogeneous success-count path with die, quantity, explosion, reroll, success predicate, and Dice Bias; it has no FlatModifier or ordered selection.

Each authored die uses StandardSides or ExplicitNumericFaces. Standard presets are D4, D6, D8, D10, D12, D20, D100, and Custom; Custom means faces 1..CustomSides. Explicit faces use numeric Value and positive Multiplicity, retaining existing Runtime validation for legal arbitrary, repeated, weighted, non-contiguous, and negative outcomes.

V1.11 exposes DiceBiasPercent from -99..+99: positive favors higher canonical numeric faces, negative favors lower faces, and zero is neutral. Runtime overrides use the same signed range through AdditionalDiceBiasPercent. Conversion and composition are exact; the existing lower-level/direct Dice Bias API retains its native exact endpoint semantics and was not reduced or changed by V1.11.

---

14. Numeric Total

Numeric Total produces one final numeric aggregate.

Typical examples:

1D20
2D6 + 3
2D6 + 1D4
4D8 Keep Highest 3

Public Blueprint resolver vocabulary includes:

• Resolve Sequential Single Numeric Die
• Resolve Keyed Single Numeric Die
• Resolve Sequential Numeric Dice Total
• Resolve Keyed Numeric Dice Total

Keyed calls require an explicit valid DecisionKey.

There is no hidden occurrence counter.

---

15. Success Count

Success Count models a homogeneous Dice Pool.

Each initial die becomes one candidate.

Each completed candidate contributes:

0 or 1 success

and the final result is:

0 ... Pool Size

Supported success conditions:

• Equal.
• At or Above.
• At or Below.
• Inclusive Range.

---

15.1 Success Count Pipeline

Conceptually:

initial candidate
    |
    +--> biased generation
    |
    +--> bounded explosion
    |
    +--> bounded reroll of complete candidate
    |
    +--> Success Rule
    |
    +--> 0 or 1

All candidate results are summed.

---

15.2 Success Count Restrictions

The V1 Success Count contract does not reinterpret Numeric Total controls.

Unavailable in Success Count:

• FlatModifier.
• Roll Style.
• Add Extra Dice.
• Ordered Selection.
• Critical Rules.

Editor UI may preserve their stored Numeric Total values while the mode is switched.

---

16. Critical Rules

Compatible Numeric Total configurations can use:

• Ordinary Success condition.
• Critical Success condition.
• Critical Failure condition.
• Classification source.
• Overlap policy.

Sources:

• Generated Face.
• Pre-Modifier Aggregate.
• Final Outcome.

Overlap policies:

• Reject Overlap.
• Critical Success Wins.
• Critical Failure Wins.

Generated Face requires one untransformed Standard die.

Unsupported provenance combinations are rejected/disabled rather than reinterpreted.

---

17. Sequential Runtime Dice

Sequential resolvers use the selected registered Sequential Probability Director stream.

Use Sequential when call order is intended to advance the gameplay sequence.

A Fixed Seed reproduces a compatible sequence only when the relevant call order remains compatible.

---

18. Keyed Runtime Dice

Keyed resolvers use:

• A registered Keyed stream.
• Explicit FProbabilityDecisionKey.
• Explicit Occurrence within that key.

Use Keyed when the outcome belongs to stable semantic identity rather than call order.

Example:

Namespace: Loot
Stable Subject ID: Chest.Region3.0042
Decision: DiceTier
Occurrence: 0

Do not use pointer values or transient Actor instance names as stable subject identity.

---

19. Blueprint API

Normal Blueprint gameplay should use target-free World Context facade nodes.

Important nodes include:

• Resolve Sequential/Keyed Single Numeric Die.
• Resolve Sequential/Keyed Numeric Dice Total.
• Resolve Sequential/Keyed Numeric Dice Success Count.
• Make Standard Numeric Dice Pipeline.
• Make Probability Dice Bias.

Blueprint projections intentionally do not expose raw RNG state or persistence secrets.

Detailed native Dice trace/provenance remains C++ where appropriate.

---

20. C++ Usage Pattern

Conceptually:

UProbabilityDirectorSubsystem* Probability =
    GameInstance->GetSubsystem<UProbabilityDirectorSubsystem>();

if (!Probability)
{
    return;
}

// Build/obtain the Dice definition or pipeline.
// Select the StreamId created earlier.
// Call the Sequential or Keyed resolver matching stream mode.
// Check structured status before consuming the result.

Do not create a new stream for every roll.

---

21. Exact Analysis

Supported Dice systems can produce exact:

• PMF.
• Expected Value.
• Variance.
• Success Count PMF.
• Bias comparison.
• Compatible classification projections.

Presentation decimals do not replace exact authority.

---

22. Exact Capacity and Representation

General biased analysis can retain reduced rational outcome masses independently rather than requiring one giant primitive ticket denominator.

Normal pools such as:

2D20
5D20
2D100

are intended to use the general exact projection.

Older/narrower primitive-count APIs may still return ExactCapacityExceeded when that representation cannot encode an otherwise valid exact distribution.

Neither path is allowed to round the authoritative probability.

---

23. Failure Model

Dice operations can fail for reasons including:

• Invalid face definition.
• Invalid weights.
• Unsupported mechanic combination.
• Invalid selection count.
• Invalid classification.
• Exact capacity exceeded.
• Exact complexity exceeded.
• Outcome range overflow.
• Sampling/work limit reached.
• Unknown Stream ID.
• Decision-mode mismatch.
• Invalid Decision Key.

Always handle the returned structured result/status.

---

24. Deterministic No-Draw Cases

Some successful operations consume no generator bytes.

Examples:

• One possible outcome.
• Exact ±100% Dice Bias endpoints.
• Bound-one selections.

Do not assume every successful random operation necessarily advances Sequential state.

Diagnostics expose the semantic Sequential state effect separately.

---

25. API Selection Guide

Need	Use
Roll one die	Single Numeric Die
Resolve several dice to a total	Numeric Dice Total
Count pool successes	Numeric Dice Success Count
Add a normal bonus	FlatModifier
Favor higher/lower faces	Dice Bias
Keep/drop outcomes	Ordered Selection
Simple 2-roll high/low	Advantage / Disadvantage
Call-order-driven result	Sequential
Stable semantic result	Keyed
Exact PMF/statistics	Exact Dice analysis
Editor exploration	Dice Lab

---

26. Recommended Patterns

Separate unrelated Sequential responsibilities

Prefer:

Combat.Damage
Combat.Critical
Loot.Dice

instead of one large stream if unrelated systems must not perturb one another.

Keep probability Bias and arithmetic separate

Dice Bias: +20%
FlatModifier: +3

means:

favor higher faces
then add 3 once

Use Keyed instead of repeated reseeding

For persistent semantic outcomes, Keyed decisions are usually clearer and safer than repeatedly destroying/recreating a Fixed Sequential stream.

---

27. Public Safety Boundaries

Dice public APIs do not expose:

• Raw RNG bytes.
• Secure root.
• Entropy bytes.
• Generator key/nonce.
• Raw ChaCha state.
• Byte position.
• Persistence secret state.

The Dice result is gameplay output.

The generator state that produced it remains private.

---

28. Common Mistakes

Dice Bias as +N

Wrong. Use FlatModifier.

FlatModifier once per die

Wrong. Numeric Total applies it once after aggregation.

Weighted die becomes uniform under Bias

Wrong. Bias reshapes the authored Base Distribution.

Symbolic names imply order

Wrong. Symbolic outcomes do not receive numeric ordering automatically.

Failed call always means no Sequential advancement

Only rely on zero-consumption guarantees explicitly documented for that failure path.

Ignoring resolver status

Never use an output as a successful roll unless status says it succeeded.

---

29. Related Documentation

• Lab-Dice.md
• API Overview
• Probability.md
• Distributions.md
• Diagnostics and Warnings
• DataAssets.md