Probability Director Data Assets

Probability Director Data Assets hold reusable authored configuration. They are not active gameplay RNG state and may be shared by many callers.

1. What a Data Asset Is

A Data Asset is a reusable Runtime definition authored in the Unreal Editor. Gameplay should not mutate a shared asset to supply per-call values; use the separate Runtime context and override structures instead.

2. Common Data Asset Boundaries

Data Assets do not contain:

• Active Stream state or a Sequential cursor.
• An actual gameplay FProbabilityDecisionKey identity.
• Secure entropy, roots, keys, nonces, or generator state.
• Probability Director persistence snapshots.

Runtime context supplies registered Streams and decision identity when needed.

3. Name Model Assets

UProbabilityNameModel is the existing authored name-generation model asset. It supports authored N-Gram Markov data and Weighted Syllables. Sequential or Keyed name generation still uses Runtime Streams separately; the model asset does not contain RNG state. See MarkovAndNames.md.

4. Resolution Rules Family

The V1.11 Resolution Rules family is:

UProbabilityResolutionRules (abstract)
    -> UNumericDiceResolutionRules
    -> future sibling card/deck rules asset

UNumericDiceResolutionRules is the implemented numeric/dice rules asset. No card/deck implementation exists in V1.11.

5. Numeric Rule Modes

• HomogeneousPipeline: one die and quantity with explosion, reroll, ordered keep/drop selection, Flat Modifier, and Dice Bias.
• HeterogeneousExpression: multiple ordered terms with per-term quantity and standard or explicit numeric faces, plus Flat Modifier and Dice Bias. V1.11 does not add heterogeneous explosion, reroll, or selection algorithms.
• SuccessCount: the existing homogeneous success-count path with die, quantity, explosion, reroll, success predicate, and Dice Bias. It has no Flat Modifier or ordered selection.

6. Die Authoring

Each authored die uses StandardSides or ExplicitNumericFaces.

Standard presets are D4, D6, D8, D10, D12, D20, D100, and Custom. Custom means standard faces 1..CustomSides.

Explicit numeric faces use existing Value and positive Multiplicity rows. Existing Runtime validation remains authoritative for legal arbitrary, non-contiguous, negative, repeated, and weighted outcomes.

7. Homogeneous Rules

Homogeneous authoring provides quantity, optional explosion, optional reroll, optional ordered Keep/Drop Selection, Flat Modifier, and signed Dice Bias Percent. These fields materialize into the existing FProbabilityNumericDicePipelineDefinition and authoritative Dice pipeline.

8. Heterogeneous Rules

Heterogeneous authoring is an ordered array of terms. Each FProbabilityNumericResolutionRulesTerm has a die definition, either standard or explicit numeric faces, and quantity. The expression also supports Flat Modifier and Dice Bias Percent.

V1.11 does not add heterogeneous explosion, reroll, or ordered selection algorithms.

9. Success Count

Success Count authoring uses a homogeneous die/pool, quantity, optional explosion, optional reroll, the existing Probability Director success predicate, and Dice Bias Percent. Flat Modifier and ordered selection are not applicable.

10. Signed Bias Percent

V1.11 Data Assets expose DiceBiasPercent; per-call overrides expose AdditionalDiceBiasPercent. Each is an int32 in the inclusive range -99..+99:

• Positive favors higher canonical numeric outcomes.
• Negative favors lower canonical numeric outcomes.
• Zero is neutral.

Each percentage converts exactly as Percent/100, without floating-point approximation. Authored and optional runtime contributions compose exactly, then clamp internally to [-1,+1]. This is the V1.11 Data Asset/override UX; existing lower-level exact FProbabilityDiceBias APIs remain unchanged.

11. Runtime Overrides

FProbabilityNumericResolutionOverrides contains:

int64 AdditionalFlatModifier = 0;
bool bHasAdditionalDiceBias = false;
int32 AdditionalDiceBiasPercent = 0;

The asset remains unchanged. Effective Flat Modifier is checked additive composition of authored and runtime values. When bHasAdditionalDiceBias is false, no runtime bias contribution is applied.

12. Decision and Source Policies

Decision policy is separate from source policy:

• Decision: Sequential or PersistentKeyed authoring policy. PersistentKeyed maps to existing Keyed Stream behavior.
• Source: InheritConfiguredStream, RequireFixed, or RequireSecure constraints on the registered Stream.

These policies do not create Streams, select seeds, or contain runtime RNG state. See StreamsAndDecisionKeys.md.

13. C++ Usage

FProbabilityResolutionContext Context;
Context.StreamId = RegisteredStreamId;

FProbabilityNumericResolutionOverrides Overrides;
Overrides.AdditionalFlatModifier = RuntimeModifier;

FProbabilityNumericDiceResolution Resolution;
const FProbabilityResolutionRulesStatus Status =
    Probability->TryResolveNumericRulesTotal(Rules, Context, Overrides, Resolution);

Check Status.IsSuccess() before reading Resolution.FinalOutcome. Use the Success Count resolver and result type for a Success Count asset. See Quickstart_CppUsage.md.

14. Blueprint Usage

Create a normal Data Asset as Numeric Dice Resolution Rules, then call Resolve Sequential Numeric Rules Total or the appropriate Persistent Keyed/Success Count node. See Quickstart_BlueprintUsage.md.

15. Example Assets

These are ordinary data definitions:

• D20 Normal: 1xD20.
• D20 Advantage: 2xD20, Keep Highest 1.
• D20 Disadvantage: 2xD20, Keep Lowest 1.
• Exploding 3D8: 3xD8, explosion enabled.
• 4D6 Reroll 1 / Keep Highest 3: 4xD6, reroll 1, Keep Highest 3.

There is no special runtime Advantage or Disadvantage mode.

16. Validation

Normal Data Asset validation checks invalid custom sides, empty or invalid explicit faces/multiplicity, invalid quantities or terms, invalid explosion/reroll/selection/predicate data, incompatible mode fields, and invalid bias percentages. Invalid configuration remains invalid; it is not silently replaced with another rule. Validation does not consume RNG or access Stream state.

17. Data Assets Versus Persistence

Data Asset = reusable authored definition.

Stream/persistence state = Runtime or campaign state.

Saving a reference to a rules asset is not the same as saving Probability Director Stream state. See SaveGameIntegration.md and PersistenceComplexity.md.

18. Future Data Asset Families

The only future seam is the abstract UProbabilityResolutionRules family with sibling rule assets. No speculative card/deck mechanics or APIs are defined in V1.11.