Generic Bias and Ranked Selection
Probability Director can compose already-resolved bias contributions and select a candidate from a generic weighted set. Probability owns stream/key validation, deterministic selection, exact arithmetic, and the decision trace. It does not inspect gameplay Actors or resolve consumer-specific values.
Bias contributions
Section titled “Bias contributions”FProbabilityBiasContribution contains a caller-owned SourceTag and signed percentage points in [-100,+100]. FProbabilityBiasComposer::Compose preserves contribution order, sums with checked arithmetic, clamps the final value to [-100,+100], and reports raw/final totals and whether clamping occurred. Composition does not consume a stream or make a decision.
Candidates and ranks
Section titled “Candidates and ranks”FProbabilityRankedWeightedCandidate contains a unique, non-None CandidateKey, a nonnegative int64 BaseWeight, and an int32 SelectionRank. Requests support up to 4096 candidates. Duplicate identities and negative weights are invalid; zero-weight candidates are allowed but ineligible. At least one positive-weight candidate is required.
Candidate keys are sorted before resolving a weighted ticket, while the result reports the selected candidate’s original input index, key, and rank. Candidate ordering in the caller’s array therefore does not change the deterministic key outcome.
Ranks are ordinal: only tier ordering and ties matter. Rank gaps do not affect the result. At zero bias, selection is weighted by BaseWeight alone. Positive bias favors higher rank tiers; negative bias favors lower rank tiers. Bias attenuates each tier by its distance from the favored extreme using Probability’s exact wide-integer arithmetic. At +100 or -100, only the corresponding highest or lowest eligible tier survives; ties retain their relative base weights.
Sequential and Keyed selection
Section titled “Sequential and Keyed selection”Use TrySelectSequentialRankedWeighted with a registered Sequential stream or TrySelectKeyedRankedWeighted with a registered Keyed stream and a valid FProbabilityDecisionKey. Both accept either a signed bias value or an already-composed FProbabilityBiasBreakdown.
Stream, mode, seed-source, and key validity are checked even when the effective result is deterministic. If only one effective outcome remains, Probability returns it without requesting a random ticket, advancing a Sequential stream, or adding Keyed state. Invalid requests return the existing structured Stream failure domain.
Results provide the selected candidate identity/index/rank and a trace containing stream identity, keyed identity when present, bias breakdown, and selected candidate. PRNG internals are not exposed. Input validation failures use the Input domain; exact-arithmetic capacity failures use the Exact domain; stream/key failures use the Stream domain.
The API is neutral and suitable for consumers such as item-pool selection. Consumers retain ownership of their candidate data, rank meaning, source-value resolution, and mapping from the selected key/index to gameplay objects. Probability has no Inventory, Relationship, Dialogue, ActorComponents, DirectorBridge, or SaveGame dependency.