Dice Lab

Dice Lab is the Editor-facing environment for authoring, evaluating, comparing, simulating, and Runtime-sampling Probability Director Dice systems.

This document describes the Lab workflow and presentation.

For Dice Runtime semantics, API contracts, Dice Bias, pipeline order, and public safety boundaries, see Dice.md.

1. Purpose

Use Dice Lab to answer questions such as:

What outcomes can this Dice system produce?
What is the exact probability of each total?
How does Dice Bias change it?
What are Base EV, Bias EV, EV Delta, and variance?
What do Advantage/Disadvantage change?
What do rerolls/explosions do?
What is the exact Success Count distribution?
Does Monte Carlo agree with exact theory?
What is the isolated Lab stream producing in PIE?

Dice Lab is a developer/designer analysis surface, not gameplay authority.

2. Relationship to Runtime Dice

Dice Lab uses the same approved Dice semantics as Runtime.

It must not invent an Editor-only interpretation of:

Dice Bias.
Reroll.
Explosion.
Ordered Selection.
FlatModifier.
Success Count.
Critical Rules.

Actual Lab rolls use its isolated local stream and supported Runtime resolver.

3. Main Workflow

1. Author Dice configuration
2. Choose Result Mode
3. Configure Bias/transforms
4. Evaluate Dice
5. Inspect exact chart/statistics
6. Optionally run Monte Carlo
7. Optionally select Runtime Context + Registered Stream
8. Roll Dice or Start Continuous
9. Compare Blue/Green/Orange/Red
10. Export

4. Result Modes

Dice Lab supports:

Numeric Total
Success Count

Dependent controls appear/disable according to mode.

Values from another mode may remain preserved so mode switching does not destroy prior authoring.

5. Numeric Total Authoring

Typical controls include:

Standard/custom die.
Quantity.
Extra numeric terms.
Roll Style.
Ordered Selection.
Reroll.
Explosion.
Dice Bias.
Flat Modifier.
Critical Rules where compatible.

6. Standard Presets

Presets:

D4
D6
D8
D10
D12
D20
D100

D100 means one numeric die numbered 1 through 100.

Custom face counts use generic authoring.

7. Dice Bias in the Lab

The Lab exposes one signed:

Dice Bias (%)

field.

Normal Lab range:

-99.999% ... +99.999%

Positive favors higher faces.
Negative favors lower faces.
Zero is Neutral.

Up to four decimal places are converted through the exact authoring path.

The Runtime/API exact ±100% certainty endpoints are intentionally not normal Dice Lab authoring values.

8. Base vs. Bias

Neutral Bias:

Show Base only.
Do not draw a duplicate identical Bias series.

Nonzero Bias:

Base = same Dice mechanics with Neutral Bias.
Bias = selected signed Dice Bias.

Reroll, explosion, selection, weighting, and FlatModifier remain identical so the comparison isolates Dice Bias.

9. Shared Chart Colors

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

Where all exist:

Blue -> Green -> Orange -> Red

Red and Orange may coexist.

10. Statistics

Exact evaluation can display:

Base EV.
Bias EV.
EV Delta.
Variance.
Exact outcome probability.

Success Count uses corresponding success-count statistics such as Expected Successes where applicable.

11. Roll Style

Standard uses stored Quantity and explicit selection.

Eligible Quantity 1 configurations may use:

Advantage
    -> Quantity 2
    -> Keep Highest 1

Disadvantage
    -> Quantity 2
    -> Keep Lowest 1

Derived settings do not overwrite Standard authoring.

11.1 Roll Style Availability

Roll Style is unavailable with incompatible authoring, including:

Success Count.
Add Extra Dice.
Quantity other than one.
Explicit Ordered Selection.

Explosion remains compatible where the canonical candidate pipeline supports it.

12. Ordered Selection

When enabled, the Lab clearly shows:

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

and the count.

The same selection feeds exact, Runtime, Monte Carlo where supported, and export.

13. Success Count

Set:

Result Mode = Success Count

for a homogeneous Dice Pool.

Controls include:

Pool Size.
Die definition.
Success Rule.
Threshold/range.
Dice Bias.
Reroll.
Explosion.

Success Rules:

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

14. Success Count Restrictions

Unavailable while Success Count is active:

Numeric Quantity.
Add Extra Dice.
Ordered Selection.
Roll Style.
Flat Modifier.
Critical Rules.

Their Numeric Total values remain preserved where appropriate.

15. Critical Rules

Compatible Numeric Total configurations expose:

Ordinary Success.
Critical Success.
Critical Failure.
Generated Face / Pre-Modifier Aggregate / Final Outcome.
Reject Overlap / Critical Success Wins / Critical Failure Wins.

Incompatible provenance paths are reported/disabled rather than guessed.

16. Evaluate Dice

Evaluate Dice performs pure exact analysis.

It does not require PIE or a Runtime Context.

Use it to establish the mathematical reference before empirical sampling.

17. Authoring-Change Invalidation

A meaningful Dice input change:

Stops Continuous.
Clears stale theory.
Clears stale Monte Carlo.
Clears stale Lab Samples.
Clears last result.
Clears old export snapshot.
Returns to Guide/result-empty state.

No Runtime sample should be plotted against an older Dice theory configuration.

18. Runtime Header

The compact Runtime header uses:

Runtime Context
Registered Stream
Refresh Runtime Contexts
Export

Streams are discovered from the selected live GameInstance.

The developer does not type an arbitrary Stream ID into this workflow.

Internal Lab/Monte Carlo/test contexts are filtered from the normal context list.

19. Roll Dice

Roll Dice resolves the configured dice expression against the Lab-owned isolated Sequential stream. It does not call a live gameplay subsystem. The authored configuration is evaluated before sampling; invalid configurations are rejected without an operation.

20. Isolated Dice Sampling

Each successful local roll contributes one bounded aggregate Lab sample. Repeated and continuous rolls advance only Lab experiment state and do not alter gameplay streams, diagnostic history, or future gameplay outcomes.

21. Live Dice Probes

The Lab does not perform live Sequential or Keyed dice rolls. To probe a live gameplay stream, open Probability Director Runtime Controls, select the context and stream, enable Enable Live Stream Probe, then choose Roll Dice. Sequential live rolls consume values and can change future outcomes; Keyed live rolls do not advance the Sequential cursor but may be recorded in diagnostics.

22. Continuous Lab Rolls

Start Continuous and Stop run the selected dice configuration against the isolated Lab stream at 1–100 rolls per second (default 10). This Lab feature does not use a gameplay stream and does not depend on the Runtime Controls safety gate.

23. Lab Samples

Successful final outcomes accumulate as bounded Lab-local counts. Clear Lab Samples clears only that presentation accumulator and leaves all gameplay streams and diagnostics unchanged.

24. Monte Carlo

Monte Carlo is isolated repeated simulation.

It does not use the Lab-owned isolated stream.

It owns a temporary Probability Director GameInstance/subsystem/stream.

Modes:

Fixed Seed.
Secure.

Keyed Monte Carlo is intentionally not V1.

24.1 Monte Carlo Bounds

Trials:

1 ... 10,000,000

Presets:

1K
10K
100K
1M

Runs are chunked and cancellable.

24.2 RNG Health

Monte Carlo may show:

Sample Count.
Maximum absolute probability error.
Mean absolute probability error.
Chi-square.
Degrees of freedom.
P-value.
Lag-1 through Lag-4 correlation where meaningful.

These diagnostics are evidence about the experiment, not proof of perfect or cryptographically secure randomness.

25. Orange and Red Together

If both belong to the same authored configuration:

Orange Monte Carlo may remain.
Red Lab Samples may be added.

Interpretation:

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

A real authored Dice change invalidates both empirical series.

26. Heterogeneous Runtime Roll

Supported mixed Numeric Total expressions such as:

2D6 + 1D4

are resolved as one Runtime operation.

Bias applies to every generated face.

FlatModifier applies once.

One successful expression becomes one Red final-outcome observation.

27. Semantic Chart Titles

Priority:

Red Runtime samples.
Orange Monte Carlo if no Red.
Exact online.
Exact offline.

Dice titles:

Runtime:

Exact Dice PMF - <StreamId>

Monte Carlo:

Monte Carlo Theoretical vs Empirical Distribution - Dice Lab

Exact online:

Exact Dice PMF

Exact offline:

Exact Dice PMF - Offline

PIE/GameInstance/map names are not placed in visible titles.

28. Hover Semantics

Red hover identifies the actual action as:

Roll Dice Result

rather than presenting it as another theoretical series.

Runtime bar percentages use readable black text.

29. Context / Stream Boundaries

Changing Runtime Context, Registered Stream, or relevant stream configuration clears the Lab’s runtime presentation session.

It does not reset the gameplay Stream itself.

Authored Dice inputs remain.

30. Lab Switching

Switching Labs clears cross-Lab presentation state and restores the selected Lab Guide.

A chart from another Lab must never remain visible as though it belongs to Dice Lab.

31. Exports

Dice Lab supports:

CSV.
Markdown.
PNG.
SVG.
Report bundle.

Exact comparison CSV includes Base/Bias exact ratios plus invariant decimal presentation.

Runtime aggregate export:

DiceLab-RuntimeSamples.csv

It contains aggregate frequency rows, not an unbounded raw roll log.

32. Export Security

Exports do not expose:

Secure root.
Entropy bytes.
Key.
Nonce.
Raw RNG state.
Byte position.

A Fixed Monte Carlo seed may be exported because it is intentionally authored/reproducible.

Secure internal state is never exported.

33. Failure Presentation

Visible failures include, as applicable:

Invalid die.
Invalid Success Range.
Unsupported mechanic combination.
Exact capacity/complexity failure.
Missing Runtime Context.
Missing Stream.
Mode mismatch.
Invalid Decision Key.
Unsupported heterogeneous Runtime combination.

A failed automatic Evaluate blocks the Runtime operation.

34. Recommended Workflows

Exact balance

Configure
-> Evaluate Dice
-> inspect Blue/Green and statistics

Empirical validation

Evaluate
-> Run Monte Carlo
-> compare Orange

Gameplay stream investigation

Start PIE
-> select Runtime Context
-> select Registered Stream
-> Roll Dice / Start Continuous
-> inspect Red

Keyed investigation

Select Keyed Stream
-> author/select Decision Key
-> set Occurrence Index
-> Roll
-> intentionally repeat/change occurrence

35. Common Mistakes

Orange means gameplay Stream

Wrong. Orange is isolated Monte Carlo.

Clearing Runtime Samples resets RNG

Wrong. It clears only the Lab aggregate.

Old chart after editing is still valid

No. Authored changes invalidate the previous result session.

Dice Lab should expose exact ±100% Bias

The Runtime/API does. Lab normal probabilistic authoring intentionally stops at ±99.999%.

Keyed Continuous has a hidden counter

No. Occurrence behavior is explicit.

36. Quick Reference

Evaluate Dice
    = exact analysis

Roll Dice
    = one isolated Lab stream operation

Start Continuous
    = repeated isolated Lab stream operations

Monte Carlo
    = isolated repeated simulation

Blue
    = Base

Green
    = Bias / Configured

Orange
    = Monte Carlo

Red
    = Lab Samples