Distributions

Probability Director provides bounded evaluation and sampling for common probability distributions, plus exact Custom Weighted discrete distributions.

This document describes distribution concepts and Runtime/API behavior.

For the Editor tool, family chooser, charts, Monte Carlo, isolated Lab samples, Bias target controls, and exports, see Lab-Distribution.md.

---

1. Purpose

Use distributions when gameplay values should follow a mathematical shape rather than a simple uniform roll.

Typical uses include:

• One yes/no event.
• Success counts across fixed repeated attempts.
• Event counts by average rate.
• Uniform delays.
• Designer-shaped bounded values.
• Waiting times.
• Symmetric mean-centered variation.
• Positive right-skewed quantities.
• Bounded 0..1 traits.
• Hand-authored weighted outcomes.

---

2. Supported Families

Probability Director V1 exposes:

1. Bernoulli
2. Binomial
3. Poisson
4. Continuous Uniform
5. Triangular
6. Exponential
7. Normal
8. Gamma
9. Chi-square
10. Beta
11. Custom Weighted

Custom Weighted is an exact discrete authoring family rather than a continuous analytical family.

---

3. Evaluation vs. Sampling

This distinction is fundamental.

Evaluation

Evaluation asks mathematical questions such as:

• PMF.
• PDF.
• CDF.
• Expectation.
• Variance.
• Exact equality.
• Exact numeric range probability.
• Discrete quantile.

Evaluation is RNG-free.

It does not consume a Probability Director Stream.

Sampling

Sampling asks:

Generate one realized value from this distribution.

Sampling uses:

• Sequential stream semantics, or
• Keyed stream semantics.

Sampling is a callable stateful operation.

---

4. PMF, PDF, and CDF

PMF

A Probability Mass Function applies to discrete outcomes.

Examples:

• Bernoulli.
• Binomial.
• Poisson.
• Custom Weighted numeric outcomes.

It gives probability assigned to each discrete outcome.

PDF

A Probability Density Function applies to continuous distributions.

Examples:

• Normal.
• Gamma.
• Beta.
• Exponential.

A PDF value is density, not the probability of one exact point.

CDF

A Cumulative Distribution Function answers:

P(X <= x)

Probability Director exposes CDF behavior where the approved family/API surface supports it.

---

5. Bernoulli

Bernoulli represents one two-outcome event.

Parameter:

p = probability of success

Typical uses:

• Does an attack crit?
• Does poison apply?
• Does a rare event occur?

Coin behavior is the special case:

p = 1/2

See Coins.md.

---

6. Binomial

Binomial represents the number of successes in a fixed number of independent Bernoulli trials with the same probability.

Parameters:

• Trial Count N.
• Success probability p.

Support:

0 ... N

Typical uses:

• How many of 20 shots hit?
• How many of 10 proc checks trigger?
• How many of 8 workers succeed?

---

7. Poisson

Poisson models event counts associated with an average rate.

Parameter:

• Lambda.

Typical uses:

• Ambient events in an interval.
• Arrivals.
• Rare-count processes.

Do not substitute Poisson for a fixed number of independent yes/no attempts; that is Binomial.

---

8. Continuous Uniform

Continuous Uniform assigns equal density across a range.

Parameters:

• Minimum.
• Maximum.

Use when no region of the range should be favored.

Example:

Patrol delay from 5 to 10 seconds

---

9. Triangular

Triangular uses:

• Minimum.
• Mode.
• Maximum.

It is useful when the designer wants:

• A hard minimum.
• A hard maximum.
• One most-likely value.

It provides simple shaped bounded behavior without requiring a Normal distribution.

---

10. Exponential

Exponential models positive waiting-time-like quantities.

Parameter:

• Rate.

Use when:

• Values are nonnegative.
• Short waits are common.
• Long waits remain possible.

---

11. Normal

Normal uses:

• Mean.
• Standard Deviation.

Use for symmetric variation around an average.

Examples:

• NPC height.
• Aim deviation.
• Measurement-like noise.

Normal is mathematically unbounded.

Do not use it when hard minimum/maximum bounds are part of the gameplay contract unless the game explicitly owns a separate truncation/clamping policy.

---

12. Gamma

Gamma uses positive shape/scale-style parameters.

It is useful for positive right-skewed values such as:

• Repair durations.
• Waiting times.
• Positive accumulated quantities.

It is not symmetric.

---

13. Chi-square

Chi-square uses Degrees of Freedom.

It is positive and right-skewed.

Use it when its mathematical shape is actually appropriate; do not choose it merely because a positive distribution is required.

---

14. Beta

Beta uses:

• Alpha.
• Beta.

Support:

0 ... 1

Useful for:

• Probabilities.
• Proportions.
• Normalized traits.
• Accuracy tendencies.
• Aggression/courage/loyalty-like values.

---

15. Custom Weighted

Custom Weighted represents exact designer-authored discrete outcomes.

Modes:

• Numeric.
• Symbolic.

Weights are positive integers.

---

15.1 Numeric Custom Weighted

Numeric outcomes may be:

• Negative.
• Sparse.
• Duplicate-authored.

Canonicalization:

• Merges duplicate numeric outcomes.
• Orders support numerically.

Supported exact reasoning includes:

• Equality.
• Ranges.
• Quantiles.

---

15.2 Symbolic Custom Weighted

Symbolic outcomes use FName identity.

Duplicate semantic identities are merged.

Symbolic categories remain unordered.

Probability Director does not invent mathematical ranking for names such as:

Common
Rare
Legendary

Numeric range/quantile operations therefore do not apply to Symbolic mode.

---

16. Exact Numeric Ranges

Exact weighted numeric range analysis supports independent:

• Lower bound.
• Upper bound.
• Inclusive/exclusive lower endpoint.
• Inclusive/exclusive upper endpoint.

Bounds do not snap to authored support.

Example support:

-5, 10, 100

Query:

0 < X <= 50

includes only 10.

---

17. Exact Discrete Quantiles

For a discrete numeric distribution:

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

No interpolation is invented between support values.

---

18. Exact Ratio Contracts

Blueprint exact-ratio projections use the bounded Blueprint int64 contract.

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

Do not convert exact authored probabilities to floating point and then rebuild them as authority.

Presentation decimals are not the authoritative value.

---

19. Probability Bias

Probability Bias changes an exact probability toward a selected boundary.

The native/API contract supports exact deterministic endpoints through:

-100% ... +100%

Bernoulli/Binomial probability Bias is conceptually different from general Distribution Parameter Bias.

See Probability.md.

---

20. Distribution Parameter Bias

Distribution Parameter Bias moves valid base parameters toward explicit caller-selected target parameters.

Typical targets:

Family	Target parameters
Poisson	Lambda
Uniform	Minimum / Maximum
Triangular	Minimum / Mode / Maximum
Exponential	Rate
Normal	Mean / Standard Deviation
Gamma	Shape / Scale
Chi-square	Degrees of Freedom
Beta	Alpha / Beta

The caller chooses the target.

Bias does not invent a target or decide that one direction is inherently “better.”

---

21. Neutral and Full Target

Neutral Bias preserves the base distribution.

At full target magnitude, supported parameter Bias reaches the authored target according to the native contract.

Invalid target combinations remain invalid; Bias does not excuse bad distribution parameters.

---

22. Sequential Sampling

Supported numerical distributions expose Sequential sampling on the Probability Director subsystem.

Examples include:

• TrySampleSequentialBernoulli
• TrySampleSequentialBinomial
• TrySampleSequentialPoisson
• TrySampleSequentialContinuousUniform
• TrySampleSequentialTriangular
• TrySampleSequentialExponential
• TrySampleSequentialNormal
• TrySampleSequentialGamma
• TrySampleSequentialChiSquare
• TrySampleSequentialBeta

A Sequential sampler uses the selected registered Sequential stream.

---

23. Keyed Sampling

Supported numerical distributions also expose corresponding Keyed samplers.

Keyed operations require:

• Registered Keyed stream.
• Valid Decision Key.
• Explicit Occurrence.

Keyed sampling does not advance Sequential stream state.

---

24. C++ Example

Conceptually:

double Sample = 0.0;

FProbabilityDistributionSamplingStatus Status =
    Probability->TrySampleSequentialNormal(
        StreamId,
        Distribution,
        Sample);

// Check the public success/status contract before using Sample.

The exact status helper/enum should match the Runtime version you are compiling against.

---

25. Blueprint Usage

Blueprint exposes safe distribution:

• Definitions.
• Evaluation projections.
• Sequential samplers.
• Keyed samplers.
• Probability Bias.
• Distribution Parameter Bias.

Raw generator objects and cryptographic state are not part of the Blueprint surface.

---

26. Validation

Distribution parameters are validated.

Invalid states can include:

• Nonfinite values.
• Invalid ranges.
• Nonpositive parameters where positivity is required.
• Invalid parameter relationships.
• Unsupported numerical configurations.

Runtime does not silently turn invalid data into a nearby valid distribution unless a specific Editor control is explicitly documented as clamping authoring input.

---

27. Numerical Failure

An extreme configuration may exceed supported numerical/representability limits.

Probability Director returns structured failure instead of fabricating a value.

Caller behavior:

1. Check status.
2. Do not consume the output after failure.
3. Correct the configuration.
4. Avoid blind retry loops.

---

28. Sampling Limits

Some algorithms use bounded sampling/work limits.

A sampling-limit failure means that safe bound was reached.

It does not imply automatic retry until success.

Repeated occurrences may appear in diagnostics warnings.

---

29. Generic Exact Mass Sampling

Native C++ supports exact discrete/categorical mass sampling:

• Sequential numeric exact mass.
• Keyed numeric exact mass.
• Sequential categorical exact mass.
• Keyed categorical exact mass.

Generic mass construction/sampling is intentionally not a broad arbitrary Blueprint authoring surface in V1.

Use specialized Blueprint Dice, Probability, Distribution, or Name APIs where possible.

---

30. Weighted Outcome Bias

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

It is not a general Blueprint/Lab affinity authoring workflow in V1.

Do not confuse:

• Custom Weighted distribution authoring.
• Distribution Parameter Bias.
• Probability Bias.
• Weighted Outcome Bias.

They solve different problems.

---

31. API Selection Guide

Need	Use
One yes/no event	Bernoulli
Fixed repeated success count	Binomial
Event count by average rate	Poisson
Equal density in a range	Continuous Uniform
Bounded min/mode/max shape	Triangular
Positive waiting-time shape	Exponential
Symmetric mean-centered variation	Normal
Positive right-skew	Gamma
Chi-square-shaped variable	Chi-square
0..1 trait/proportion	Beta
Hand-authored weighted outcomes	Custom Weighted
Inspect without RNG	Evaluation
Changing call-order-driven sample	Sequential
Stable semantic sample	Keyed
Editor analysis	Distribution Lab

---

32. Common Mistakes

Treating PDF as exact point probability

For a continuous distribution, PDF is density.

Using Normal when hard bounds are mandatory

Normal is unbounded.

Treating Symbolic Custom Weighted outcomes as ordered

They are categories, not ranks.

Sampling just to calculate theory

Use evaluation instead.

Ignoring sampling status

Always inspect the returned result.

Using a gameplay stream for offline analysis

Pure evaluation needs no stream; Lab Monte Carlo is isolated.

---

33. Public Safety Boundaries

Distribution APIs do not expose:

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

A returned sample is gameplay output.

The Secure generator internals remain private.

---

34. Related Documentation

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