1. The Simple Mental Model

Probability Director has three broad layers:

Public Gameplay API
    |
    |  Safe operations and results
    v
Probability Director Runtime
    |
    |  Internal deterministic / Secure state
    v
Private RNG and persistence internals

Developer tools can inspect selected safe information:

Runtime
    |
    +--> sanitized diagnostics
    +--> Probability Director Runtime Inspector
    +--> Lab results

They do not provide unrestricted access to internal RNG state.

---

2. What the Public API Is Allowed to Do

The public Blueprint and C++ APIs are designed around requesting probability operations.

Examples:

Roll Dice
Sample Probability
Sample Distribution
Generate Name
Use Sequential Stream
Use Keyed Stream

The public API returns the result of the operation.

It does not require gameplay code to manipulate:

• Raw random bytes.
• ChaCha state.
• Generator keys.
• Nonces.
• Secure campaign roots.
• Internal byte positions.

This is intentional.

Gameplay should ask Probability Director for a random decision instead of managing the generator directly.

---

3. Secure State Is Private

Probability Director Secure Streams use internal Secure state that is not exposed through normal public APIs.

Private Secure information includes items such as:

• Secure campaign/root material.
• Entropy bytes.
• Generator keys.
• Generator nonces.
• Raw generator state.
• Internal byte position/state needed to reconstruct the sequence.

These values are not Blueprint-visible.

They are also intentionally excluded from normal Editor diagnostics and the Probability Director Runtime Inspector.

---

4. Why Secure State Is Hidden

Suppose a developer tool exposed everything required to reconstruct a Secure Stream:

Key
Nonce
Generator State
Byte Position

A copied diagnostic report could then become enough information to recreate future output.

Probability Director avoids making ordinary debugging tools into a generator-state extraction interface.

Instead, diagnostics expose safe information such as:

Seed Source: Secure
Generator Algorithm: ProbabilityDirector.ChaCha20IETF
Generator Version: 1
Secure Entropy Source: ProbabilityDirector.SecureRandomBytes
Secure Entropy Version: 1

This tells you what implementation contract is active without exposing the state that produced the sequence.

---

5. Secure Does Not Mean Encrypted

This distinction is extremely important.

Secure RNG

and:

Encrypted save data

are different things.

A Secure Probability Director Stream means the random source follows Probability Director’s Secure RNG architecture.

It does not mean:

• Your .sav file is encrypted.
• Your persistence payload is encrypted.
• Your network traffic is encrypted.
• Your exported diagnostics are encrypted.
• Your game automatically protects all stored data.

---

6. Persistence Is Plaintext Unless the Host Encrypts It

Probability Director persistence data is plaintext unless the host application provides encryption at the storage layer.

Conceptually:

Probability Director persistence state
        |
        v
Host SaveGame system
        |
        +--> plaintext storage
        |
        OR
        |
        +--> host-provided encrypted storage

Probability Director does not automatically encrypt the save file.

If save confidentiality matters, encryption belongs to your game’s save/storage architecture.

---

7. Canonical SaveGame Contributor Exposure Is Not Encryption

The optional DirectorBridge Probability.SaveGame adapter marks the Probability contributor payload as Sensitive, so it is not exposed through ordinary Blueprint-facing document access.

That is an exposure-control boundary.

It is not file encryption.

Think of it as:

Sensitive storage
    =
"Do not expose this internal contributor payload through normal public editing/access APIs."

Not:

Sensitive storage
    =
"Encrypt these bytes on disk."

If the host SaveGame Director storage is plaintext, Probability Director contributor data remains part of plaintext save storage.

---

8. Fixed Seed Is Different from Secure State

A Fixed Seed is deterministic.

It is intended for reproducibility.

For example:

Fixed Seed:
12345

can intentionally reproduce the same compatible deterministic sequence.

A Fixed Seed is therefore not treated as cryptographic secret material.

However, the Probability Director Runtime Inspector and Runtime diagnostics still hide the actual Fixed Seed value.

They may show:

Seed Source:
Fixed

but not:

Fixed Seed:
12345

---

9. Why Hide Fixed Seed in Diagnostics?

The reason is primarily API and diagnostic hygiene.

The Inspector answers:

What kind of Stream is this?

not:

Give me every piece of state/configuration that could recreate it.

If a developer needs the authored Fixed Seed, inspect the configuration that created the Stream.

This keeps Runtime diagnostic exports consistent with the same redacted design used for Secure Streams.

---

10. Fixed Seed May Be Visible Where Reproducibility Is the Feature

Do not confuse Runtime diagnostic redaction with every Probability Director tool.

For example, a Fixed Monte Carlo experiment may intentionally display/export its Fixed Seed because reproducibility is the point of that experiment.

So the rule is contextual:

Runtime Inspector / diagnostics
    -> Fixed Seed value hidden

Fixed Monte Carlo experiment
    -> Fixed Seed may be intentionally visible

This is not a contradiction.

The two tools have different purposes.

---

11. Diagnostics Are Sanitized

Probability Director diagnostics are intended for debugging, not for full Runtime-state serialization.

Diagnostics can expose safe information such as:

• Stream ID.
• Seed Source identity.
• Decision Mode.
• Persistence Policy.
• Operation name.
• Status.
• Sequential Effect.
• Sanitized Decision Key metadata.
• Approved bounded generated scalar values.
• Deterministic contract version identity.
• Persistence Generation where applicable.

They intentionally exclude reconstructable generator state.

---

12. Generated Values: What Is Actually Captured

Older documentation may imply that all sampled/generated values are excluded.

That is no longer accurate.

The approved diagnostics contract can retain specific bounded scalar outputs for supported operations when successful-operation recording is enabled.

Examples can include:

• Boolean results.
• Signed integer results.
• Unsigned integer results.
• Floating-point results.
• A final numeric Dice outcome.
• A Dice Success Count.
• Supported scalar distribution samples.

Example:

Operation:
Resolve Sequential Numeric Dice Total

Status:
Success

Generated Value:
17

This is allowed because it is a bounded result value, not reconstructable RNG state.

---

13. What Generated Values Are Not Captured

Probability Director does not generically retain arbitrary output objects.

Examples intentionally outside the generic value contract include:

• Arbitrary UObject references.
• Arbitrary gameplay payloads.
• Arbitrary strings/text.
• Composite result structures without an approved bounded contract.
• Full Dice provenance/traces.
• Full Name-generation output where not explicitly approved.
• Arbitrary weighted payload objects.

The Inspector may show:

Generated Value:
Not captured for this operation

That does not mean the Runtime operation failed.

It means the result type is not part of the approved diagnostic value contract.

---

14. Status and Generated Value Are Separate

The Inspector keeps operation status separate from the generated result.

This matters because:

0

and:

false

can be valid generated values.

Example:

Status:
Success

Generated Value:
0

is different from:

Status:
Failure - StreamRuntime (2)

Generated Value:
Not captured

A zero result is not automatically an error.

---

15. Decision Keys Are Safe Semantic Identity

Keyed operations intentionally use semantic identity.

A Keyed Decision contains fields such as:

Namespace
Stable Subject ID
Decision
Occurrence

Example:

Namespace:
Loot

Stable Subject ID:
Chest.Region3.0042

Decision:
Rarity

Occurrence:
0

These fields describe what decision is being made.

They are not raw RNG state.

---

16. Why Keyed Identity Must Be Stable

A Keyed operation is deterministic for the same compatible semantic coordinate.

That means developers should choose identity based on stable game meaning.

Good example:

Namespace:
Loot

Stable Subject ID:
Chest.World01.Room12.Chest04

Decision:
Rarity

Occurrence:
0

Poor example:

Stable Subject ID:
Pointer_0x000001A482...

or another temporary Runtime identity that changes between sessions.

The key should describe the gameplay decision, not accidental process memory.

---

17. Occurrence Is Explicit

Keyed mode has no hidden persistent occurrence cursor.

If the same semantic decision needs multiple deterministic occurrences, the caller supplies the occurrence explicitly.

Example:

Loot
Chest.0042
Rarity
Occurrence 0

and:

Loot
Chest.0042
Rarity
Occurrence 1

represent two different deterministic coordinates.

---

18. Repeating the Same Key Is Expected to Repeat

If you make the same compatible Keyed request twice:

Namespace:
Loot

Stable Subject ID:
Chest.0042

Decision:
Rarity

Occurrence:
0

the same deterministic result is expected.

That is not an RNG failure.

If you want another deterministic occurrence, change the explicit occurrence according to your gameplay design.

---

19. Keyed Mode Has No Hidden Persistent Cursor

Sequential and Keyed Streams behave differently.

Sequential

Call
    -> consumes next Sequential random state

Call
    -> consumes next Sequential random state

Keyed

Decision Key + Occurrence
    -> deterministic coordinate

There is no secret internal Keyed counter that automatically advances after each call.

This is intentional because hidden occurrence state would make keyed determinism much harder to reason about.

---

20. Diagnostics Can Show Sanitized Keyed Metadata

For retained Keyed operations, the Inspector can show bounded sanitized fields such as:

• Namespace.
• Stable Subject ID.
• Decision.
• Occurrence.
• Decision Key Schema Version.

This helps answer:

Why did these two Keyed calls return the same result?

or:

Why did the result change?

without exposing internal derived generator keys/nonces.

---

21. Diagnostic Truncation

Some diagnostic text fields are bounded.

For example, a very long Stable Subject ID may be retained only as a bounded diagnostic copy with an explicit truncation marker.

This means:

The Inspector is showing a safe diagnostic representation.

It does not mean:

Probability Director changed the Runtime Decision Key to the shortened string.

Do not reconstruct gameplay identity from truncated diagnostics.

---

22. PDCS and PDPA Are Internal Persistence Formats

Internal Probability Director persistence representations such as PDCS and PDPA are not public gameplay-editing formats.

Normal Blueprint/API users should not:

• Parse them manually.
• Modify them.
• Treat them as configuration files.
• Build gameplay logic around their internal byte layout.

Use the approved persistence APIs and SaveGame integration instead.

Their internal representation may change according to the supported compatibility contract.

---

23. Persistence Payloads Are Not Inspector Data

The Runtime Inspector can show safe persistence metadata such as:

Persistence Policy
Persistence Generation

It does not expose the complete persistence payload.

This separation is intentional.

Inspector
    -> tells you what is happening

Persistence API
    -> carries the state needed to restore

An Inspector export is not a valid substitute for persistence state.

---

24. Sequential Position Is Intentionally Hidden

The Inspector does not expose a numeric Sequential cursor or raw byte position.

Instead, individual diagnostic operations can report:

Sequential Effect:
Advanced

Sequential Effect:
Did Not Advance

or:

Sequential Effect:
Not Applicable

That is enough to determine whether a retained operation consumed Sequential random state without exposing generator internals.

---

25. Example: Successful Operation That Does Not Advance

Suppose an operation has only one possible result.

Probability Director may be able to return that result without consuming random bytes.

The Inspector can legitimately show:

Status:
Success

Sequential Effect:
Did Not Advance

This is not automatically suspicious.

It means the operation did not require random state consumption.

---

26. Raw Random Bytes Are Not a Public Gameplay API

Probability Director does not expose a general Blueprint node such as:

Get Raw Random Bytes

for ordinary gameplay.

Developers should use semantic operations:

Resolve Dice
Sample Bernoulli
Sample Distribution
Choose Weighted Outcome
Generate Name

This gives Probability Director room to preserve:

• Validation.
• Deterministic contracts.
• Bounded behavior.
• Diagnostics.
• Security boundaries.

---

27. Dice Traces and Provenance Are Restricted

Detailed Dice trace/provenance remains an advanced native C++ capability.

The generic Runtime Inspector does not retain full Dice traces.

It may retain an approved bounded final scalar result, such as:

Final Outcome:
17

or:

Success Count:
4

but not every internal generated face, reroll relation, explosion relation, or arbitrary trace structure.

Use the specialized native API when full trace/provenance is required.

---

28. Lab Results and Runtime Diagnostics Are Different

Developer Labs are analysis/testing tools.

The Runtime Inspector is a diagnostic tool.

For example:

Dice Lab
    -> may show complete PMF
    -> may show Monte Carlo empirical counts
    -> shows isolated Lab Samples in its own experiment charts

The Runtime Inspector:

    -> shows selected retained Runtime operations
    -> may show approved generated scalar result
    -> does not expose complete RNG state

Do not assume every value visible in a Lab should also be available in Runtime diagnostics.

---

29. Monte Carlo Is Isolated

Monte Carlo uses an isolated temporary Probability Director Runtime context/Stream.

It does not use or advance a gameplay stream. Live stream probes are a separate, gated Runtime Controls action.

Therefore:

Run Monte Carlo

must not reveal or consume the Secure state of:

Combat.Damage
Loot.DropTable
AI.Decisions

or another registered gameplay Stream.

---

30. Monte Carlo Secure Mode Still Does Not Expose Secure State

Secure Monte Carlo may report:

Random Mode:
Secure

but it does not export reconstructable Secure generator state.

Fixed Monte Carlo can expose the intentionally authored Fixed Seed for reproducibility.

Secure Monte Carlo cannot be reproduced by extracting hidden Secure internals from its report.

---

31. Exports Follow the Same Boundaries

Probability Director exports are built from approved copied/redacted data.

Runtime diagnostic exports must not contain:

• Secure roots.
• Entropy bytes.
• Generator keys.
• Generator nonces.
• Raw RNG state.
• Byte position.
• Reconstructable Secure state.
• Raw persistence payloads.

They may contain safe diagnostic information such as:

• Stream IDs.
• Modes.
• Status.
• Sanitized Decision Key metadata.
• Approved generated scalar values.
• Contract/version metadata.

---

32. A Bug Report Should Be Useful Without Secrets

A useful Probability Director bug report can normally contain:

Stream ID:
Combat.Damage

Seed Source:
Secure

Decision Mode:
Sequential

Operation:
Resolve Sequential Numeric Dice Total

Status:
Success

Sequential Effect:
Advanced

Generated Value:
17

Generator Version:
1

It does not need:

Raw key
Raw nonce
Raw Secure root
Raw generator state

This is the intended diagnostic model.

---

33. Do Not Log Private State Yourself

Probability Director can protect its own public tools, but application code can still create a security problem if it manually logs private native state.

Avoid adding project logs such as:

UE_LOG(..., TEXT("SecureKey=%s"), ...);

or dumping persistence internals into human-readable debug output.

If you extend Probability Director native integration, preserve the same redaction boundary.

---

34. Save Files Need Their Own Threat Model

Probability Director does not determine whether your save data should be:

• Confidential.
• Tamper-resistant.
• Signed.
• Encrypted.
• Cloud-protected.

Those requirements depend on your game.

Examples:

Local single-player game

Plaintext storage may be acceptable.

Competitive or economy-sensitive game

You may need additional validation, signing, encryption, or server authority.

Those are application architecture decisions outside Probability Director’s RNG API boundary.

---

35. Secure RNG Is Not Anti-Cheat

Secure random generation and anti-cheat are different problems.

Probability Director’s Secure RNG architecture protects how Secure random decisions are generated.

It does not automatically prevent:

• Memory inspection.
• Save editing.
• Process modification.
• Network cheating.
• Game-code modification.

Those require separate game/security architecture.

---

36. Security Boundary by Feature

Feature	Exposed	Hidden
Stream configuration	ID, Seed Source, Mode, Persistence Policy	Fixed Seed value in Runtime diagnostics
Secure Stream	Safe algorithm/version identity	Root, entropy, key, nonce, raw state
Sequential diagnostics	Advanced / Did Not Advance	Numeric byte position/cursor
Keyed diagnostics	Sanitized semantic key fields	Derived generator key/nonce
Generated values	Approved bounded scalar values	Arbitrary/composite payloads
Persistence	Policy/generation metadata	Raw persistence payload in Inspector
SaveGame Director Sensitive storage	Contributor exposure control	Does not provide encryption
Monte Carlo Fixed	Fixed Seed may be visible	Internal generator state
Monte Carlo Secure	Mode/summary	Reconstructable Secure state

---

37. Common Mistakes

“Secure Stream means my save file is encrypted.”

Incorrect.

Secure RNG and storage encryption are separate systems.

---

“Sensitive SaveGame Director storage encrypts the contributor.”

Incorrect.

Sensitive storage controls API exposure.

It does not encrypt the stored bytes.

---

“The Inspector should show the Secure seed so I can debug.”

It intentionally does not.

Use safe metadata, operation status, and sanitized decision information.

---

“Fixed Seed is secret.”

Not inherently.

Fixed Seed is deterministic/reproducible.

Probability Director still redacts it from Runtime diagnostics by design.

---

“Diagnostics never contain sampled values.”

Not anymore.

Approved bounded scalar generated values can be retained for supported operations.

What remains excluded is unrestricted/arbitrary output and reconstructable RNG state.

---

“Keyed mode automatically increments something internally.”

Incorrect.

Occurrence is explicit.

There is no hidden persistent Keyed occurrence cursor.

---

“I can restore from an Inspector JSON export.”

Incorrect.

Inspector exports contain sanitized diagnostic information, not the persistence payload required for restore.

---

“If Sequential Effect says Advanced, I know the exact RNG position.”

Incorrect.

You only know that this operation consumed Sequential random state.

Numeric generator position remains hidden.

---

38. Recommended Developer Practices

For reproducible debugging

Use:

Fixed Stream

or:

Fixed Monte Carlo

where reproducibility is appropriate.

Do not attempt to extract Secure state.

---

For deterministic semantic decisions

Use Keyed mode with stable fields:

Namespace
Stable Subject ID
Decision
Occurrence

Choose values based on gameplay identity, not temporary memory/process identity.

---

For save security

Use Probability Director persistence normally, then protect the host save storage according to your game’s requirements.

If encryption is required:

Probability Director
    -> persistence data
        -> host encryption/storage layer

---

For Runtime debugging

Use:

Probability Director Runtime Inspector

and, when needed:

Record Successful Operations

Inspect safe statuses, Sequential Effect, sanitized keys, and approved results rather than trying to expose raw generator internals.

---

39. Quick Security Checklist

Before shipping an integration, verify:

• Gameplay uses public Probability Director APIs instead of raw RNG-state access.
• Secure roots/keys/nonces are never manually logged.
• Diagnostic exports contain no reconstructable Secure state.
• Persistence payloads are not exposed as editable Blueprint data.
• Save encryption, if required, is handled by the host storage layer.
• SaveGame Director Sensitive storage is not being treated as encryption.
• Keyed Stable Subject IDs are stable semantic identities.
• Keyed Occurrence is supplied intentionally.
• No system assumes a hidden Keyed cursor exists.
• Fixed Seeds used for reproducibility are managed by the application appropriately.
• Runtime Inspector redaction is not bypassed by project-specific debug code.

---

40. Quick Reference

Secure RNG
    = protects random generation architecture
    != encrypted save file

SaveGame Director Sensitive storage
    = limits contributor exposure
    != encryption

Fixed Seed
    = deterministic / reproducible
    = hidden from Runtime diagnostics
    != cryptographic secret

Keyed operation
    = stable semantic identity
    + explicit Occurrence
    = no hidden cursor

Runtime diagnostics
    = sanitized metadata
    + approved bounded results
    != raw RNG state
    != persistence payload

---

41. Related Documentation

• API Overview — public Blueprint/C++ API boundaries.
• Probability Director Runtime Inspector — sanitized Runtime diagnostics and generated-value capture.
• Diagnostics and Warnings — diagnostic retention, warning behavior, and redaction.
• Persistence and Save Game Integration — persistence ownership and plaintext-storage boundary.
• SaveGame Director Integration and Migration — retired product status and the optional canonical Sensitive contributor integration.
• Monte Carlo and RNG Health — Fixed/Secure experiment behavior and isolation.
• Known Limitations — current Version 1 public API boundaries.