Distribution Lab

Distribution Lab is the Editor-facing tool for selecting a Probability Director distribution family, authoring parameters, evaluating theory, comparing Bias targets, running isolated Monte Carlo, and sampling an actual registered gameplay Stream.

For Runtime/API concepts and mathematical family behavior, see Distributions.md.

1. Purpose

Use Distribution Lab to answer:

Which distribution family fits this gameplay variable?
How do parameter changes reshape it?
What are its analytical statistics?
How does Distribution Bias change configured behavior?
Do isolated Monte Carlo samples match theory?
What is the isolated Lab stream producing?
How do PDF and CDF projections differ?
How should Custom Weighted outcomes behave?

2. Supported Families

The Lab exposes:

Bernoulli.
Binomial.
Poisson.
Uniform.
Triangular.
Exponential.
Normal.
Gamma.
Chi-square.
Beta.
Custom Weighted.

Normal is the approved default selection.

3. Family Guide

Before successful evaluation, the chart area presents a Family Guide.

It includes:

General Distribution Lab purpose.
Best general use.
When/why to use distributions.
A clearly separated selected-family section.
Family-specific best use.
Game example.
Use when.
Avoid when.
Bias/sampling guidance.
Family chooser reference.

The selected family is visually distinct from the general Distribution Lab boilerplate.

4. Family Selection Is a Session Boundary

Changing Family immediately clears stale:

Chart.
Result summary.
PMF/PDF/CDF presentation.
Monte Carlo result.
Lab Samples.
Export snapshot.

The new Family Guide appears immediately.

A failed evaluation does not restore the previous family’s chart.

5. Authoring Parameters

Each family exposes only meaningful parameters.

Family	Primary authoring
Bernoulli	Probability
Binomial	Probability, Trials
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
Custom Weighted	Outcomes / Weights

Inputs are committed through the live/action-time path before Evaluate.

6. Evaluate

Evaluate analyzes the selected family without consuming a gameplay Stream.

Depending on family/view it may produce:

PMF.
PDF.
CDF.
Expected Value.
Variance.
Base parameters.
Configured/Bias parameters.
Exact weighted output.

7. Base and Configured Series

For Bias-capable families:

Blue = Base.
Green = Configured/Bias.

At zero Bias:

Base is shown.
A redundant identical Configured series is omitted.

At nonzero Bias:

Base remains the authored baseline.
Configured reflects the Bias target transformation.

8. Distribution Bias

Distribution Lab authors Distribution Bias (%) through the exact Lab parsing path.

For parameter Bias:

Base parameters
    +
Explicit target parameters
    +
Bias magnitude/direction
    =
Configured distribution

The Runtime mathematics remain authoritative.

9. Bias Capability Matrix

Family	Supported	Target controls
Bernoulli	Yes	Probability endpoint behavior
Binomial	Yes	Probability endpoint behavior
Poisson	Yes	Lambda
Uniform	Yes	Minimum / Maximum
Triangular	Yes	Minimum / Mode / Maximum
Exponential	Yes	Rate
Normal	Yes	Mean / Standard Deviation
Gamma	Yes	Shape / Scale
Chi-square	Yes	Degrees of Freedom
Beta	Yes	Alpha / Beta
Custom Weighted	No general parameter target	N/A

Custom Weighted is not silently forced into a parameter-Bias model.

10. CDF Availability

CDF is visible for:

Uniform.
Triangular.
Exponential.
Normal.
Gamma.
Chi-square.
Beta.

CDF controls are collapsed for:

Bernoulli.
Binomial.
Poisson.
Custom Weighted.

The Lab does not fabricate unsupported CDF behavior.

11. Custom Weighted — Numeric

Numeric Custom Weighted supports:

Positive integer weights.
Negative outcomes.
Sparse outcomes.
Duplicate outcomes.

Duplicates are canonicalized.

Numeric mode supports exact:

PMF.
Range analysis.
Percentile/quantile.

12. Custom Weighted — Symbolic

Symbolic mode uses FName outcome identity.

It supports exact category probabilities.

Disabled because they are not meaningful:

Numeric ranges.
Quantiles.
Numeric ordering.

No lexical ranking is inferred.

The Lab uses a categorical/list presentation rather than inventing false numeric semantics.

13. Percentile

For numeric Custom Weighted:

Percentile (%) uses discrete quantile semantics.

0% -> minimum.
100% -> maximum.
Interior -> smallest outcome whose CDF reaches the requested exact percentage.

No interpolation.

14. Exact Range Analysis

Numeric Custom Weighted range analysis supports:

Inclusive/exclusive lower bound.
Inclusive/exclusive upper bound.

Bounds do not snap to support.

15. Monte Carlo

Distribution Lab supports isolated Monte Carlo validation.

Monte Carlo does not use the isolated Lab stream.

It owns a temporary standalone Probability Director context/stream.

Modes:

Fixed Seed.
Secure.

Keyed Monte Carlo is not part of V1.

15.1 Trial Bounds

Trials:

1 ... 10,000,000

Runs are bounded, chunked, and cancellable.

16. Continuous Monte Carlo Projection

Continuous families use:

64 equal-width display bins

Empirical PDF density:

Count / (Trials * BinWidth)

CDF view reprojects the same aggregate.

Switching PDF/CDF does not resample.

17. Sample Distribution

Sample Distribution performs one sample against the Lab-owned isolated Sequential engine. It does not call the selected gameplay subsystem or consume a registered gameplay stream. This is different from Monte Carlo: Sample Distribution adds one local observation, while Monte Carlo owns a separate isolated simulation session.

18. Continuous Lab Sampling

Start Continuous and Stop sample only the Lab-owned isolated stream at 1–100 samples per second (default 10). Sampling is bounded and nonblocking. It never starts a gameplay-stream operation.

19. Lab Sample Aggregation

Successful observations accumulate in bounded Lab-local counts. Discrete outcomes retain counts and empirical probability. Continuous families reuse the display bins; samples outside the displayed range remain in the denominator and are reported as outside-range.

20. Live Distribution Probes

The Lab does not perform live Sequential or Keyed distribution samples. For an intentional live probe, use Probability Director Runtime Controls. The Live Stream Probe gate starts disabled. Sequential probes consume values and can change future gameplay outcomes. Keyed probes use the live subsystem’s keyed path without advancing its Sequential cursor, though diagnostics may capture them.

21. Chart Colors

Color	Meaning
Blue	Base / Theoretical
Green	Configured / Bias
Orange	Monte Carlo / Empirical
Red	Isolated Lab samples

22. PDF/CDF Switching

For one configuration:

Runtime aggregate remains the same.
Monte Carlo aggregate remains the same.
View switching changes projection only.

This keeps statistical interpretation coherent.

23. Chart Colors

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

Where all exist:

Blue -> Green -> Orange -> Red

24. Semantic Chart Titles

Titles preserve Family + View.

Runtime example:

Normal PDF - <StreamId>

Monte Carlo without Red:

Normal Monte Carlo PDF - Distribution Lab

Exact online:

Normal PDF

Exact offline:

Normal PDF - Offline

If Red and Orange coexist, Runtime title semantics win.

PIE/GameInstance/map identifiers are not included in the visible title.

25. Runtime Context / Stream Changes

Changing Runtime Context or Registered Stream clears the Runtime presentation session:

Red aggregate.
Last sample.
Old stream-tied chart state.
Old export snapshot.

It does not reset the gameplay Stream.

26. Authored Configuration Changes

Changing a meaningful family parameter:

Stops Continuous.
Clears stale theory.
Clears stale Orange.
Clears stale Red.
Clears export snapshot.
Returns to Guide/result-empty state.

Old empirical data must never be plotted against new theory.

27. Monte Carlo / Continuous Mutual Exclusion

Active Runtime Continuous sampling and active Monte Carlo are mutually exclusive.

Manual Sample is disabled while Continuous is active.

Monte Carlo and Runtime jobs do not run concurrently through one Lab session.

28. Keyed Runtime Sampling

For Keyed Streams:

Decision Key is explicit.
Occurrence Index is explicit.
No hidden counter exists.

Continuous options:

Fixed Occurrence.
Increment Occurrence.

The Lab may offer bounded recent Decision Keys from current Lab use or sanitized diagnostics.

This is not a Runtime key registry.

29. Exports

Distribution Lab supports:

CSV.
Markdown.
PNG.
SVG.
Report bundle.

Runtime aggregate export:

DistributionLab-RuntimeSamples.csv

29.1 Discrete Runtime CSV

Conceptual fields include:

Outcome
RuntimeStreamCount
RuntimeStreamProbability
RuntimeStreamSampleTotal
TheoreticalTargetProbability
AbsoluteProbabilityError

29.2 Continuous Runtime CSV

Conceptual fields include:

BinStart
BinEnd
RuntimeStreamCount
RuntimeStreamProbability
RuntimeStreamDensity
TheoreticalTargetProbability
RuntimeEmpiricalCDF
TheoreticalTargetCDF
RuntimeStreamSampleTotal

Outside-range accounting remains represented by the current export/result model.

30. Snapshot Coherence

Result summary, chart series, and export snapshot derive from the same current evaluation.

Changing configuration invalidates the old snapshot.

An export must never combine:

New parameters.
Old chart.
Old Runtime samples.

31. Export Security

Secure sampling/export does not expose:

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

Fixed Monte Carlo may report the intentionally authored Fixed Seed.

32. Failure Handling

Visible failures include:

Invalid family parameters.
Numerical failure.
Sampling-limit failure.
Missing Runtime Context.
Missing Stream.
Decision-mode mismatch.
Invalid Decision Key.
Invalid Custom Weighted entry.
Exact capacity failure.

The Lab displays failure instead of restoring stale prior results.

33. Recommended Workflows

Choose/tune a family

Select Family
-> read Family Guide
-> configure parameters
-> Evaluate

Compare Bias

Evaluate Base
-> set targets
-> set Distribution Bias
-> Evaluate
-> compare Blue vs Green

Validate empirically

Evaluate
-> Run Monte Carlo
-> compare Orange

Inspect gameplay Stream

Start PIE
-> select Runtime Context
-> select Registered Stream
-> Sample Distribution / Start Continuous
-> inspect Red

34. Common Mistakes

PDF height is exact point probability

No. It is density.

CDF switch resamples

No. It reprojects existing aggregate data.

Outside-range samples can be ignored

No. They remain part of the denominator.

Orange is gameplay sampling

No. Orange is isolated Monte Carlo; Red is isolated Lab sampling.

Old chart survives family change

No. Family changes invalidate prior state.

Custom Weighted gets arbitrary parameter Bias

No.

35. Quick Reference

Evaluate
    = theory

Monte Carlo
    = isolated repeated simulation

Sample Distribution
    = one isolated Lab stream sample

Start Continuous
    = repeated isolated Lab samples

Blue
    = Base

Green
    = Configured/Bias

Orange
    = Monte Carlo

Red
    = Lab Samples