Skip to content
Tuxedo CatSTUDIO
Menu

Monte Carlo and RNG Health

Probability Director’s Monte Carlo system is a temporary statistical experiment.

It repeatedly runs the same Probability Director operation many times, records the observed outcomes, and compares those observations with the exact/theoretical result.

Monte Carlo is useful for answering questions such as:

  • Does the Runtime sampler behave like the exact mathematics says it should?
  • How close are 10,000 or 1,000,000 observed samples to the theoretical PMF?
  • Does a finite random sequence show unexpected correlation?
  • Does Dice Bias, Probability Bias, or a supported Distribution behave empirically as expected?
  • Can I reproduce the same statistical experiment with a Fixed Seed?

Monte Carlo is not a gameplay Stream and does not advance a gameplay stream.

1. The Simple Mental Model

Section titled “1. The Simple Mental Model”

Probability Director has three different ideas that can appear together in a Lab:

Exact / Theoretical
    |
    | "What should happen mathematically?"
    |
    +--> Blue / Green


Monte Carlo
    |
    | "What happens if I simulate this many times?"
    |
    +--> Orange


Lab Samples
    |
    | "What is my real gameplay Stream producing?"
    |
    +--> Red

That distinction is intentional.

Exact / Theoretical

Section titled “Exact / Theoretical”

No randomness is required.

Probability Director calculates the expected probability distribution directly.

Monte Carlo

Section titled “Monte Carlo”

Probability Director creates a temporary isolated random experiment and samples it many times.

Lab Samples

Section titled “Lab Samples”

The Lab calls an actual Stream registered in a live gameplay GameInstance.

2. What Monte Carlo Actually Does

Section titled “2. What Monte Carlo Actually Does”

A Monte Carlo run follows this general pattern:

Compile / validate the experiment once
        |
        v
Create isolated temporary Runtime context
        |
        v
Create isolated Sequential Stream
        |
        v
Sample the same experiment repeatedly
        |
        v
Accumulate counts/statistics
        |
        v
Compare empirical results with theory
        |
        v
Destroy the temporary context

For example:

Dice configuration:
2D6


Trials:
100,000

Probability Director already knows the exact 2D6 PMF.

Monte Carlo then performs the Runtime-equivalent experiment 100,000 times and compares the observed histogram with that exact PMF.

One trial contributes one complete observation.

3. Does Monte Carlo Use a Seed?

Section titled “3. Does Monte Carlo Use a Seed?”

Yes.

Probability Director Monte Carlo supports:

  • Fixed Seed
  • Secure

The Seed Source belongs to the temporary Monte Carlo experiment.

It does not replace or modify a gameplay Stream’s seed.

3.1 Fixed Seed

Section titled “3.1 Fixed Seed”

Fixed mode makes the experiment reproducible.

Example:

Experiment:
2D6


Trials:
100,000


Random Mode:
Fixed


Seed:
12345

Running the same compatible experiment again with the same Fixed Seed produces the same empirical result.

Fixed mode is useful for:

  • Reproducing a test.
  • Comparing code changes.
  • Comparing Lab changes.
  • Investigating one known random sequence.
  • Automated testing.

3.2 Secure

Section titled “3.2 Secure”

Secure mode uses Probability Director’s Secure random infrastructure.

Each experiment receives isolated secure random state.

Secure mode is useful when you want a fresh random statistical sample.

Secure exports do not expose enough internal state to reproduce the run.

4. Monte Carlo Is Not a Gameplay Stream

Section titled “4. Monte Carlo Is Not a Gameplay Stream”

This is the most important distinction.

A Stream is part of Runtime gameplay state.

Monte Carlo is a temporary experiment that uses its own isolated Stream.

Compare them:

Monte Carlo Gameplay Stream
Main purpose Statistical experiment Actual gameplay decisions
Lifetime Temporary Usually long-lived
Registered in gameplay context No Yes
Can use Fixed Seed Yes Yes
Can use Secure randomness Yes Yes
Changes gameplay stream No Yes, for Sequential operations
Used for actual gameplay outcomes No Yes
Typical workload Thousands/millions of trials Individual gameplay operations
Main question “Does sampling behave as expected?” “What happens now?”

5. Example: Monte Carlo vs. Gameplay Stream

Section titled “5. Example: Monte Carlo vs. Gameplay Stream”

Suppose gameplay has:

Stream ID:
Combat.Damage


Decision Mode:
Sequential


Seed Source:
Secure

The game performs:

Combat.Damage
    |
    +--> Resolve 2D6
            |
            +--> Result = 9

That is a real gameplay Stream operation.

It can advance Combat.Damage.

Now Dice Lab runs:

2D6
Monte Carlo
100,000 trials
Secure

The Lab creates a separate isolated simulation context:

Temporary Monte Carlo context
    |
    +--> temporary Sequential Stream
            |
            +--> 2D6
            +--> 2D6
            +--> 2D6
            +--> ...
            +--> 100,000 trials

Combat.Damage is untouched.

6. Why Monte Carlo Can Be Much Faster Than Runtime Stream Sampling

Section titled “6. Why Monte Carlo Can Be Much Faster Than Runtime Stream Sampling”

Monte Carlo and Lab Samples are optimized for different jobs.

Monte Carlo is a high-throughput batch experiment.

It knows in advance:

Run this same experiment many times and give me aggregate results.

That allows a loop resembling:

Validate once
    |
    +--> sample
    +--> sample
    +--> sample
    +--> sample
    +--> ...
    |
    +--> update aggregate counts

The Lab does not need to update the full interactive UI after every individual Monte Carlo trial.

6.1 Lab Sampling and Live Stream Probes Are Separate

Section titled “6.1 Lab Sampling and Live Stream Probes Are Separate”

The Lab’s Sample Outcome, Sample Distribution, Roll Dice, and continuous sampling actions use isolated Lab experiment state. Their Red chart series is local aggregate data and never represents a gameplay stream.

To intentionally operate on a live gameplay stream, use Probability Director Runtime Controls and enable Enable Live Stream Probe. Sequential probes consume the selected stream and can change future gameplay outcomes. Keyed probes do not advance the Sequential cursor, but they execute through the live subsystem and may be recorded in diagnostics. Live probe results are reported in Controls status and are not added to Lab charts.

Monte Carlo remains useful for large isolated simulations. Lab sampling adds individual local outcomes for interactive comparison.

7. Why Run Monte Carlo When Exact Theory Already Exists?

Section titled “7. Why Run Monte Carlo When Exact Theory Already Exists?”

For supported experiments, Probability Director often already knows the exact answer.

Example:

2D6

has an exact PMF.

Monte Carlo is not needed to discover that PMF.

Instead, Monte Carlo tests the sampling behavior against it.

Suppose theory says:

P(7) = 1/6
     ≈ 16.6667%

A 100,000-trial Monte Carlo run might observe:

7 occurred 16,731 times


Observed:
16.731%


Expected:
16.6667%

That difference is ordinary finite-sample variation.

Monte Carlo lets the developer compare:

theoretical behavior
vs.
actual sampled behavior

without disturbing gameplay state.

8. Trial Count

Section titled “8. Trial Count”

Trial count is validated from:

1 ... 10,000,000

The Labs provide common presets:

  • 1K
  • 10K
  • 100K
  • 1M

10M is the safety ceiling, not the recommended value for every test.

Larger experiments generally reduce ordinary sampling noise, but they also require more work.

9. One Trial Means One Complete Experiment

Section titled “9. One Trial Means One Complete Experiment”

A Monte Carlo trial always represents the same random variable as the theoretical result.

Examples:

Bernoulli

Section titled “Bernoulli”
One trial
=
one Success/Failure observation

Binomial

Section titled “Binomial”
One trial
=
one complete N-trial success-count experiment

Dice Numeric Total

Section titled “Dice Numeric Total”
One trial
=
one complete final Dice total

Dice Success Count

Section titled “Dice Success Count”
One trial
=
one complete pool Success Count

Distribution

Section titled “Distribution”
One trial
=
one returned distribution sample

This alignment is critical.

The empirical result must measure the same thing as the theoretical chart.

10. Dice Monte Carlo

Section titled “10. Dice Monte Carlo”

Dice Lab Monte Carlo uses the same supported Runtime Dice semantics as the approved Dice system.

It does not create a simplified “Lab-only” die.

For a supported Numeric Total:

2D6 + 1D4

one trial:

  1. Samples the two D6 terms.
  2. Samples the D4 term.
  3. Preserves authored term order.
  4. Applies Dice Bias to every generated face.
  5. Combines the expression.
  6. Applies FlatModifier once after aggregation.
  7. Records one final outcome.

The histogram therefore represents the final combined Dice total.

11. Heterogeneous Dice

Section titled “11. Heterogeneous Dice”

Supported heterogeneous expressions can be sampled directly.

Example:

2D6 + 1D4

The empirical support comes from the exact compiled final support.

Fixed mode remains repeatable because terms are consumed in stable authored order.

A difference in die face counts is not itself an error.

12. Unsupported Dice Combinations

Section titled “12. Unsupported Dice Combinations”

Monte Carlo does not silently broaden the Runtime Dice contract.

If the authoritative Dice pipeline rejects a combination, Monte Carlo rejects it too.

For the current V1 heterogeneous Numeric Total path, combinations that remain incompatible include specialized cases such as mixed terms combined with certain:

  • Explosion rules.
  • Reroll rules.
  • Ordered Selection rules.

Critical Rules also remain outside empirical heterogeneous Numeric Total classification where the approved Runtime/exact path does not support them.

The Lab reports a clear validation failure instead of using different hidden semantics.

13. Distribution Monte Carlo

Section titled “13. Distribution Monte Carlo”

Distribution Lab Monte Carlo samples the selected distribution family using the isolated simulator.

Discrete families accumulate outcome counts.

Continuous families use the approved fixed display projection.

For continuous distributions:

64 equal-width display bins

are used for chart comparison.

Empirical PDF density is:

Count / (Trials * BinWidth)

CDF view reprojects the same empirical aggregate.

Changing PDF/CDF view does not rerun the Monte Carlo experiment.

14. Results

Section titled “14. Results”

A completed Monte Carlo result may include:

  • Status.
  • Requested trials.
  • Completed trials.
  • Random mode.
  • Fixed Seed when applicable.
  • Empirical sample count.
  • Empirical Expected Value.
  • Empirical variance.
  • Theoretical Expected Value.
  • Theoretical variance.
  • Outcome counts.
  • Empirical probabilities.
  • Theoretical probabilities.
  • Absolute probability errors.
  • RNG Health metrics.

Only values meaningful for the selected experiment are reported.

15. Theoretical vs. Empirical

Section titled “15. Theoretical vs. Empirical”

The theoretical result comes from Probability Director’s approved exact/native analysis.

Monte Carlo contributes the empirical result.

Conceptually:

Theoretical
    =
what Probability Director says should happen mathematically


Empirical
    =
what actually happened during this finite simulation

A difference between the two is normal.

The question is whether the observed difference is statistically reasonable for the sample size.

16. Chart Colors

Section titled “16. Chart Colors”

The shared Probability Director chart convention is:

Color Meaning
Blue Base / Exact / Theoretical
Green Configured / Bias
Orange Monte Carlo / Empirical
Red Lab Samples

Monte Carlo is always the Orange empirical series.

Lab Samples are Red.

This prevents the two sampling sources from being confused.

17. Orange and Red Can Coexist

Section titled “17. Orange and Red Can Coexist”

If both belong to the same authored configuration, the chart can show:

Blue  = exact Base
Green = configured Bias
Orange = isolated Monte Carlo
Red = isolated Lab stream

This lets a developer compare:

  1. Mathematical theory.
  2. High-throughput isolated simulation.
  3. Actual gameplay-stream observations.

without one contaminating another.

18. RNG Health

Section titled “18. RNG Health”

RNG Health analyzes the actual isolated Monte Carlo sample.

For a known discrete theoretical PMF, it can report:

  • Sample Count.
  • Maximum absolute probability error.
  • Mean absolute probability error.
  • Chi-square goodness-of-fit statistic.
  • Degrees of freedom.
  • Chi-square p-value.
  • Lag-1 serial correlation.
  • Lag-2 serial correlation.
  • Lag-3 serial correlation.
  • Lag-4 serial correlation.

These are observational diagnostics.

19. Probability Error

Section titled “19. Probability Error”

For each outcome:

Absolute Error
=
|Observed Probability - Theoretical Probability|

Maximum absolute probability error

Section titled “Maximum absolute probability error”

The largest outcome-level error.

Mean absolute probability error

Section titled “Mean absolute probability error”

The average outcome-level error.

These give a simple sense of how far the empirical PMF is from theory.

They should generally shrink as sample count becomes large, but they will not become exactly zero in ordinary finite random experiments.

20. Chi-Square Goodness of Fit

Section titled “20. Chi-Square Goodness of Fit”

For observed count:

O_i

and expected count:

E_i = N * p_i

the statistic is:

χ² = Σ ((O_i - E_i)² / E_i)

over valid cells.

Degrees of freedom are based on the supported categorical outcome count according to the V1 contract.

The p-value is the upper-tail probability of the observed chi-square statistic.

21. How to Interpret the P-Value

Section titled “21. How to Interpret the P-Value”

The p-value helps answer:

If this theoretical distribution is correct, how unusual is a discrepancy at least this large?

It is not:

  • A score where higher is always better.
  • A randomness percentage.
  • Proof of correctness.
  • Proof of cryptographic security.
  • A seed-quality rating.

A single Monte Carlo p-value should not be used to label one Seed as “good” or “bad.”

22. Serial Correlation

Section titled “22. Serial Correlation”

RNG Health can calculate Pearson serial correlation for lags:

1
2
3
4

when the experiment has a meaningful numeric sequence.

A lag asks whether values are linearly related to earlier values.

Example:

Lag 1:
sample[i] compared with sample[i-1]


Lag 2:
sample[i] compared with sample[i-2]

Values near zero are consistent with low simple linear serial dependence.

This is a limited diagnostic, not a complete RNG test suite.

23. What RNG Health Can Tell You

Section titled “23. What RNG Health Can Tell You”

RNG Health can provide evidence about:

  • Distribution fit.
  • Finite-sample error.
  • Simple serial dependence.
  • Whether a Runtime sampling implementation appears consistent with its expected PMF.

It is useful for identifying suspicious behavior that deserves investigation.

24. What RNG Health Cannot Tell You

Section titled “24. What RNG Health Cannot Tell You”

RNG Health does not prove:

  • Perfect randomness.
  • Cryptographic security.
  • Absence of every possible correlation.
  • That a particular Seed is objectively “good.”
  • That a short visually streaky run is defective.
  • That a high p-value means an RNG is better than another RNG.

Probability Director Secure cryptographic properties come from the approved Secure RNG architecture, not from finite Monte Carlo statistics.

25. Fixed Seed Does Not Change the Theoretical Distribution

Section titled “25. Fixed Seed Does Not Change the Theoretical Distribution”

Different Fixed Seeds can produce different finite empirical results.

Example:

Exact P(7) for 2D6:
16.6667%

One Fixed Seed might produce:

16.58%

Another might produce:

16.79%

Both are sampling the same theoretical system.

The Seed determines the finite sample sequence, not the theoretical probability.

26. Cancel

Section titled “26. Cancel”

Monte Carlo runs are processed in bounded chunks so the Editor remains responsive.

Cancel is observed at trial boundaries.

A canceled run reports:

  • Requested trials.
  • Completed trials.
  • Canceled status.

A canceled experiment is not presented as a completed statistical result.

27. Why Monte Carlo Uses Chunks

Section titled “27. Why Monte Carlo Uses Chunks”

Running millions of trials in one uninterrupted Editor call could freeze the interface.

Probability Director instead performs bounded chunks:

run some trials
    |
    +--> return control to Editor
    |
    +--> update progress
    |
    +--> continue

This is why the Lab can remain interactive and provide cancellation.

Chunking must not alter the Fixed-Seed result.

A Fixed experiment should be independent of how the workload happened to be divided into UI slices.

28. Isolation

Section titled “28. Isolation”

Monte Carlo owns a temporary Lab Runtime context.

Monte Carlo never uses a selected gameplay or PIE stream.

Automated isolation coverage verifies that an independent gameplay Sequential Stream produces the same sequence whether Monte Carlo runs or not.

That means:

Run Monte Carlo

must not secretly consume:

Combat.Damage
Loot.DropTable
AI.Decisions

or any other gameplay Stream.

29. Lab Samples and Live Stream Probes

Section titled “29. Lab Samples and Live Stream Probes”

Lab Samples are produced by isolated Sample Outcome, Sample Distribution, and Roll Dice actions. They are local chart aggregates and never come from a gameplay stream.

Live stream operations are provided separately by Probability Director Runtime Controls:

  • Sample Outcome
  • Sample Distribution
  • Roll Dice
  • Start Continuous / Stop

The session-local Enable Live Stream Probe gate starts disabled. Sequential operations consume live stream state and may change future gameplay outcomes. Keyed operations preserve Keyed semantics and do not advance the Sequential cursor, though they may add live diagnostics. Live probe results appear in Controls status, not as Lab chart series.

30. Continuous Sampling Rates

Section titled “30. Continuous Sampling Rates”

Lab continuous sampling and the live Controls probe are separately bounded to 1–100 operations per second, default 10. Continuous live sampling requires the explicit gate and an obvious Stop action. Closing Runtime Controls stops its active probe.

31. Lab Stream Ownership

Section titled “31. Lab Stream Ownership”

The Lab owns a local ephemeral Sequential experiment stream. It has no gameplay stream selector, cannot execute live Keyed calls, and cannot change gameplay stream state or diagnostics.

35. Isolated Lab Session Boundaries

Section titled “35. Isolated Lab Session Boundaries”

Lab experiments own their local ephemeral stream and chart aggregates. Clearing a Lab result or starting a new Lab session affects only that presentation and local experiment state. It does not reset a selected gameplay stream, rewind Sequential state, clear Inspector diagnostics, or change a gameplay stream’s seed source.

Lab samples and Monte Carlo results can coexist when they use compatible authored configuration. They remain separate experiment outputs; neither consumes a gameplay stream.

36. Lab Experiment Exports

Section titled “36. Lab Experiment Exports”

Lab exports contain aggregate frequency or statistical results for the local experiment. They are not raw chronological histories of a gameplay stream. Runtime Controls live-probe results remain in Controls status and runtime diagnostics rather than being added to Lab charts.

40. Monte Carlo Exports

Section titled “40. Monte Carlo Exports”

Monte Carlo exports can include:

  • Experiment configuration.
  • Requested/completed trials.
  • Random mode.
  • Fixed Seed when applicable.
  • Theoretical statistics.
  • Empirical statistics.
  • Outcome comparison.
  • RNG Health.
  • Cancellation status.
  • Shared chart output.

Secure internal random state is excluded.

41. Security Boundary

Section titled “41. Security Boundary”

Monte Carlo and RNG Health do not expose:

  • Secure root.
  • Entropy bytes.
  • Generator key.
  • Generator nonce.
  • Raw ChaCha state.
  • Byte position.
  • Reconstructable Secure seed material.

Fixed Seed is intentionally visible in Fixed mode because reproducibility is the purpose of that mode.

42. Recommended Developer Workflows

Section titled “42. Recommended Developer Workflows”

Validate a Dice configuration

Section titled “Validate a Dice configuration”
Configure Dice
-> Evaluate exact PMF
-> Run 100K Monte Carlo
-> compare Orange with theory
-> inspect RNG Health

Reproduce a suspicious experiment

Section titled “Reproduce a suspicious experiment”
Switch Monte Carlo to Fixed
-> enter known Fixed Seed
-> rerun same trial count
-> compare exact same empirical result

Inspect real gameplay Stream behavior

Section titled “Inspect real gameplay Stream behavior”
Open Probability Director Runtime Controls
-> select Runtime Context and Registered Stream
-> explicitly enable Enable Live Stream Probe
-> perform a one-shot live probe or explicitly start continuous sampling
-> inspect the Controls status result

Compare an isolated simulator and an actual Runtime Stream

Section titled “Compare an isolated simulator and an actual Runtime Stream”
Evaluate
-> run Monte Carlo
-> keep Orange result
-> use the gated live probe in Probability Director Runtime Controls
-> compare the recorded results manually; live results are not added to Lab charts

43. Which Tool Should I Use?

Section titled “43. Which Tool Should I Use?”
Developer question Use
What is the exact probability? Exact Evaluate
Does Runtime sampling match theory over many trials? Monte Carlo
Can I reproduce the same simulation? Fixed Monte Carlo
I want a fresh simulation Secure Monte Carlo
What is my gameplay Stream producing right now? Probability Director Runtime Inspector
Will this roll advance gameplay Stream state? Probability Director Runtime Controls / Runtime API
I want millions of observations quickly Monte Carlo
I want interactive live Stream inspection Probability Director Runtime Inspector
I want to intentionally probe a live Stream Probability Director Runtime Controls
I want to inspect Runtime decisions/history Probability Director Runtime Inspector

44. Common Mistakes

Section titled “44. Common Mistakes”

“Monte Carlo uses my gameplay stream.”

Section titled ““Monte Carlo uses my gameplay stream.””

It does not.

It uses an isolated temporary context/Stream.

“If Monte Carlo is faster, the gameplay Stream must be slow.”

Section titled ““If Monte Carlo is faster, the gameplay Stream must be slow.””

Not necessarily.

The Developer Lab Runtime sampler is deliberately throttled for interactive observation.

Its 100/sec ceiling is not the Runtime API’s maximum throughput.

“Fixed Seed changes the probability.”

Section titled ““Fixed Seed changes the probability.””

It does not.

It chooses the deterministic sample sequence.

The theoretical distribution remains the same.

“A high p-value means this is a better Seed.”

Section titled ““A high p-value means this is a better Seed.””

It does not.

A p-value is not a Seed-quality score.

“Orange and Red are both Monte Carlo.”

Section titled ““Orange and Red are both Monte Carlo.””

They are not.

Orange is isolated Monte Carlo.

Red is isolated Lab stream sampling.

“Clearing Lab samples resets a gameplay Stream.”

Section titled ““Clearing Lab samples resets a gameplay Stream.””

It does not.

It clears only the Lab-local experiment aggregate.

“Monte Carlo is needed to calculate the exact PMF.”

Section titled ““Monte Carlo is needed to calculate the exact PMF.””

For supported exact experiments, it is not.

Monte Carlo exists to compare sampled behavior with theory.

45. Quick Reference

Section titled “45. Quick Reference”
Exact Evaluate
    = no RNG
    = mathematical answer


Monte Carlo
    = isolated temporary Sequential Stream
    = Fixed or Secure
    = many fast trials
    = Orange


Lab Samples
    = isolated Lab stream
    = one-shot or 1–100/sec Continuous
    = independent of gameplay stream mode/state
    = Red


Live Stream Probe
    = explicit Runtime Controls session gate
    = operates through the selected live Probability subsystem
    = Sequential calls consume stream values
    = Keyed calls retain Keyed semantics

One-sentence distinction

Section titled “One-sentence distinction”

A gameplay Stream is a source of live random decisions; Monte Carlo and Lab sampling use isolated experiment state.

46. Related Documentation

Section titled “46. Related Documentation”
  • API Overview — subsystem access, Stream lifecycle, Sequential vs. Keyed, Fixed vs. Secure.
  • Dice — Dice Runtime semantics and exact analysis.
  • Lab-Dice — Dice Lab workflow and empirical comparison.
  • Probability — exact probability, Bernoulli, Binomial, Probability Bias.
  • Lab-Probability — Probability Lab Monte Carlo and Lab Samples.
  • Distributions — distribution families and Runtime sampling.
  • Lab-Distribution — Distribution Lab Monte Carlo and Lab Samples.
  • Diagnostics and Warnings — Runtime diagnostics and warning interpretation.
  • Probability Director Runtime Inspector — retained Runtime events and Stream inspection.