Probability

Probability Director provides exact probability representations, exact discrete analysis, Bernoulli/Binomial behavior, Probability Bias, weighted numeric and symbolic outcomes, and safe Sequential/Keyed sampling.

This document describes Probability as a Runtime/API concept.

For the Editor workflow, charts, Monte Carlo, RNG Health, and isolated Lab samples, see Lab-Probability.md.

---

1. Purpose

Use Probability Director probability APIs when you need to answer or execute questions such as:

• What is the exact chance of an event?
• What are the corresponding odds?
• What is the probability of one exact outcome?
• What is the probability below or above a threshold?
• What is the probability inside a numeric range?
• What percentile corresponds to an exact discrete weighted distribution?
• How does Probability Bias change an event probability?
• How many successes occur across repeated independent trials?
• How can one actual outcome be sampled through a Sequential or Keyed Stream?

Probability Director separates probability definition and analysis from random realization.

---

2. Exact Probability

Where the public contract supports exact discrete probability, Probability Director preserves authoritative ratios rather than replacing them with rounded decimals.

Example:

1 / 3

may be displayed as:

33.3333%

but the displayed decimal is not the mathematical source of truth.

---

3. Blueprint Exact-Ratio Boundary

Blueprint uses a bounded exact-ratio projection whose numerator and denominator fit the approved signed int64 range.

Native C++ exact infrastructure can retain wider unsigned capacity where applicable.

This means:

• Blueprint can author common exact gameplay probabilities safely.
• Native C++ may represent some wider exact values.
• Blueprint and C++ still share the same semantic probability contract.
• A decimal display must not be converted back into the authoritative probability when an exact value already exists.

---

4. Probability, Chance, and Odds

Probability Director distinguishes validated probability concepts rather than treating every probability-like value as an arbitrary float.

Use the provided constructors/helpers for:

• Probability.
• Chance.
• Odds.
• Exact ratios.

Invalid forms should be rejected through structured results rather than normalized silently.

---

5. Bernoulli

Bernoulli models one event with two outcomes:

Success
Failure

with success probability:

p

Use Bernoulli for questions such as:

• Does this attack crit?
• Does this effect proc?
• Does this rare event occur?

A fair coin is the special case:

p = 1/2

See Coins.md.

---

6. Binomial

Binomial models the number of successes in a fixed number of independent Bernoulli trials using the same probability.

Parameters:

• Trial Count N.
• Success probability p.

Support:

0 ... N successes

Examples:

• Number of critical hits in 20 attacks.
• Number of successful checks in 8 attempts.
• Number of proc successes in 10 identical trials.

---

7. One Binomial Sample Is One Complete Experiment

This is an important Runtime semantic.

For:

Trial Count = N

one Binomial sample returns:

K successes

where:

0 <= K <= N

One Binomial API call is not one Bernoulli trial.

It is one complete N-trial observation.

---

8. Exact Discrete Numeric Mass

FProbabilityDiscreteMassFunction represents exact weighted numeric outcomes.

It supports exact reasoning over numeric support, including:

• Point/equality probability.
• Cumulative comparisons.
• Inclusive/exclusive ranges.
• Discrete quantiles.
• Exact weighted construction.

Example:

Outcome 10 : weight 2
Outcome 20 : weight 3
Outcome 50 : weight 5

can be analyzed exactly without treating the weights as approximate floating-point percentages.

---

9. Exact Categorical Mass

FProbabilityCategoricalMassFunction represents exact weighted symbolic outcomes using semantic category identity.

Example:

Common
Rare
Epic

These are categories, not an ordered numeric scale.

Probability Director does not invent:

Common < Rare < Epic

for range/quantile mathematics unless an explicit future ranking contract defines that meaning.

---

10. Exact Numeric Range Queries

Numeric exact mass supports explicit endpoint semantics.

Examples:

P(X < 10)
P(X <= 10)
P(5 <= X < 20)
P(X > 100)

Lower and upper inclusivity are separate choices.

Bounds do not need to coincide with support values.

---

11. Discrete Quantiles

For an exact discrete numeric distribution:

• 0% returns the minimum support value.
• 100% returns the maximum support value.
• An interior percentile returns the smallest support value whose CDF reaches the requested exact percentage.

No interpolation is invented between discrete outcomes.

---

12. Probability Bias

Probability Bias changes a valid probability toward the selected boundary using an exact magnitude.

The native/Runtime contract supports:

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

Neutral preserves the original probability.

The exact endpoints can represent deterministic impossibility/certainty according to the approved Bias contract.

---

13. Probability Bias vs. Dice Bias

These are different concepts.

Probability Bias changes one probability.

Dice Bias reshapes probability mass across ordered numeric generated faces.

Use:

• Probability Bias for Bernoulli/event probability.
• Dice Bias for numeric Dice-face likelihood.

Do not treat Dice Bias as a generic replacement for Probability Bias.

---

14. Probability Bias vs. Distribution Parameter Bias

Distribution Parameter Bias moves distribution parameters toward explicit targets.

Examples:

• Normal Mean toward a target Mean.
• Gamma Shape toward a target Shape.
• Beta Alpha/Beta toward target values.

Probability Bias changes the probability value itself.

They should not be conflated.

---

15. Lab Authoring vs. Runtime Endpoints

The Runtime/API supports exact ±100% Probability Bias endpoints.

Probability Director Lab intentionally uses the normal probabilistic authoring range:

-99.999% ... +99.999%

This is an Editor authoring choice.

It does not weaken the Runtime exact contract.

---

16. Pure Analysis vs. Sampling

Pure probability analysis consumes no RNG.

Sampling realizes an outcome and uses/derives random state according to the selected stream mode.

Use exact analysis when asking:

What is the probability?

Use sampling when asking:

What happened this time?

Do not sample merely to estimate a result that Probability Director can already calculate exactly.

---

17. Sequential Sampling

Sequential probability/distribution sampling uses a registered Sequential Stream.

Successful random work advances the Stream according to the operation’s actual draw behavior.

Use Sequential when call order should matter.

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

---

18. Keyed Sampling

Keyed sampling uses:

• A registered Keyed Stream.
• Explicit FProbabilityDecisionKey.
• Explicit Occurrence.

It does not advance the Stream’s Sequential state.

Use Keyed when the result belongs to a stable semantic decision rather than to “the next random call.”

---

19. Bernoulli Runtime Interpretation

One Bernoulli sample is one complete event observation:

Success
or
Failure

The resulting gameplay meaning belongs to the caller.

Probability Director determines the sampled outcome; it does not decide what “Success” means in your game.

---

20. Binomial Runtime Interpretation

One Binomial sample is one complete N-trial success-count observation.

Example:

N = 10
Sample result = 4

means:

4 successes out of 10 trials

A Runtime empirical histogram for Binomial therefore uses buckets:

0 ... N

---

21. Weighted Outcome Bias

General Weighted Outcome Bias exists as an advanced native C++ capability.

It is intentionally not a general V1 Blueprint affinity-authoring workflow.

Do not confuse it with:

• Probability Bias.
• Dice Bias.
• Distribution Parameter Bias.
• Custom Weighted authoring.

---

22. Blueprint Usage

Blueprint provides safe probability/exact projections and supported Bernoulli/Binomial operations.

Use:

• Pure Blueprint library functions for RNG-free mathematical queries.
• Target-free World Context facade nodes for stateful sampling.

Blueprint intentionally does not expose raw random generator objects or Secure state.

---

23. C++ Pure Analysis Pattern

Conceptually:

FProbabilityDiscreteMassFunction MassFunction;

// Construct through the validated exact public API.
// Query exact equality/range/quantile results.
// No Probability Director Stream is required.

Pure exact analysis should not create or advance a gameplay Stream.

---

24. C++ Sampling Pattern

Conceptually:

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

if (!Probability)
{
    return;
}

// StreamId was created earlier.
// Call the Sequential or Keyed Bernoulli/Binomial/distribution API.
// Check returned status before using the output.

Do not create a new Stream solely for every probability sample.

---

25. Validation

Probability APIs reject invalid inputs rather than silently redefining them.

Examples include:

• Invalid denominator.
• Numerator outside the supported projection range.
• Probability outside [0,1].
• Invalid Binomial Trial Count.
• Exact capacity exceeded.
• Invalid Stream.
• Decision-mode mismatch.
• Invalid Decision Key.

Always handle structured status/results.

---

26. No Floating-Point Authority

Do not implement an exact gameplay probability by:

convert exact ratio to float
modify float
convert float back

when an exact Probability Director operation exists.

Floating-point decimal output is appropriate for:

• UI.
• Charts.
• Human-readable export.

It is not a replacement for exact authoritative math.

---

27. Error Handling

A returned output is only a successful gameplay result when the returned status says the operation succeeded.

Possible failure categories include:

• Invalid input.
• Exact capacity exceeded.
• Numerical failure.
• Unknown Stream.
• Decision-mode mismatch.
• Invalid Decision Key.

Do not silently substitute a random fallback value after failure unless that fallback is an explicit game rule owned by the caller.

---

28. API Selection Guide

Need	Use
One yes/no event	Bernoulli
Repeated fixed success-count experiment	Binomial
Exact weighted numeric outcomes	Discrete Mass
Exact symbolic categories	Categorical Mass
Move probability toward boundary	Probability Bias
Change Dice face likelihood	Dice Bias
Move distribution parameters toward targets	Distribution Parameter Bias
Ask a mathematical probability question	Pure exact analysis
Call-order-driven random observation	Sequential
Stable semantic observation	Keyed
Editor balancing/empirical comparison	Probability Director Lab

---

29. Recommended Usage Patterns

Keep definition separate from realization

Probability = 25%

is configuration.

Did the event occur?

is sampling.

Keep those concepts separate.

Preserve authored exact rules

If the game rule is:

1 in 20

prefer exact 1/20 over an approximate decimal representation.

Use Keyed for persistent semantic decisions

A stable question such as:

Does Chest 42 have the bonus?

is often better represented by a Keyed decision than by inserting another call into an unrelated Sequential stream.

---

30. Public Safety Boundaries

Probability sampling does not expose:

• Raw random bytes.
• Secure root.
• Entropy bytes.
• Generator key.
• Generator nonce.
• Raw generator state.
• Byte position.
• Persistence secret state.

Exact probability values are ordinary public gameplay configuration.

Secure generator state remains private.

---

31. Common Mistakes

One Binomial sample means one trial

Wrong. It returns the full N-trial success count.

A decimal is close enough to replace an exact game rule

Use the exact API when exact probability is part of the design.

Dice Bias can bias a Bernoulli probability

Use Probability Bias.

Sampling is needed to determine theoretical probability

Use pure analysis.

Keyed Occurrence can be ignored

Occurrence is explicit and part of semantic identity.

Failure output can still be consumed

Only consume successful outputs.

---

32. Related Documentation

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