ProbabilityList<T>
If you are learning RNGNeeds from the top down, start with the guides and conceptual docs first, then come back here when you want the exact runtime shape of the main list type.
ProbabilityList<T> is the core runtime type in RNGNeeds.
It stores a list of ProbabilityItem<T> entries and provides the APIs for:
- adding and removing items
- managing probabilities and weights
- picking one or many values
- preventing repeats
- working with seeds and pick history
- supporting depletable lists
- connecting influence providers
Important concepts first
Base probability vs evaluated probability.
GetItemBaseProbability(...) returns the stored baseline. GetItemProbability(...) returns the effective probability currently used during selection, including influence.
Locked is not the same as disabled.
Disabled items are ignored during selection. Locked items can still be picked, but certain list operations will not redistribute their probability.
Some pick methods return shared lists.
Properties like LastPickedValues and methods returning shared lists are optimized to avoid extra allocations. If you need stable ownership, copy the data into your own list.
Common workflow
var lootTable = new ProbabilityList<string>();
lootTable.AddItem("Potion", 0.5f);
lootTable.AddItem("Gold", 0.3f);
lootTable.AddItem("Rare Gem", 0.2f);
string reward = lootTable.PickValue();
Core properties
Core properties
ListNameOptional display name for the list. This becomes especially useful when the list is used inside a PLCollection<T>, where the collection can look up and manage lists by name.
ItemCountNumber of items in the list.
UnlockedItemsCountNumber of items that are not locked.
EnabledItemsCountNumber of enabled items.
IsListInfluencedReturns true when at least one item is affected by an influence provider.
Selection behavior
Selection settings
SelectionMethodIDIdentifier of the selection method used by this list. The identifier is resolved through RNGNeeds Core.
PreventRepeatControls how repeated picks are handled.
ShuffleIterationsNumber of shuffle passes used by PreventRepeatMethod.Shuffle. Clamped between 1 and 5.
PickCountMinMinimum number of values selected by multi-pick methods.
PickCountMaxMaximum number of values selected by multi-pick methods.
LinkPickCountsWhen true, the effective pick count is fixed to PickCountMin.
MaintainPickCountIfDisabledKeeps trying to reach the desired pick count even when disabled items interfere. This can change the resulting distribution and has built-in fail-safe checks for pathological cases.
PickCountCurveControls the bias used when the pick count is randomly chosen between min and max.
Picking values
Pick methods
PickValuePicks one value and returns it. If selection fails, the default value of T is returned.
TryPickValueSafest single-pick method when you need to distinguish failure from a valid default value.
PickValuesPicks multiple values and returns a shared list of results.
PickValueWithIndexPicks one value and also returns the selected item index.
TryPickValueWithIndexSafer version of PickValueWithIndex() when you need explicit success/failure.
RunTestRuns a selection test using the current configuration and returns diagnostic results.
Working with items
Item management
AddItemAdds an item using a value, explicit probability, explicit weight, or an already-created ProbabilityItem<T>.
AddItemsAdds multiple values at once.
RemoveItemRemoves an item by value or item reference.
RemoveItemAtIndexRemoves an item by index.
ClearListRemoves all items and clears history.
GetProbabilityItemGets the item at a specific index.
TryGetProbabilityItemSafely retrieves an item by index or value.
Probability operations
Probability operations
GetItemProbabilityReturns the effective probability currently used during selection.
GetItemBaseProbabilityReturns the raw stored base probability.
AdjustItemBaseProbabilityAdds a value to an item's base probability.
SetItemBaseProbabilitySets an item's base probability, optionally normalizing the rest of the list.
ResetAllProbabilitiesEvens out probabilities of all unlocked items.
NormalizeProbabilitiesNormalizes unlocked items so the list sums to 1.
Weights
Weight-based distribution helpers
TotalWeightSum of all item weights in the list.
BaseWeightReference weight used by helper methods. Clamped between 1 and 10000.
WeightsPriorityWhen enabled, probabilities snap back to weight-derived fractions during certain operations.
GetItemWeightReturns an item's current weight.
SetItemWeightSets an item's weight and redistributes or recalculates as needed.
CalculatePercentageFromWeightsRebuilds probabilities from weights.
ResetWeightsRebuilds weights from the current probability distribution.
RecalibrateWeightsRebalances unlocked-item weights while preserving total weight where possible.
Item state and influence
Item state and influence helpers
SetItemPropertiesUpdates several core item properties together.
SetItemEnabled / SetAllItemsEnabledEnables or disables one item or the whole list.
SetItemLocked / SetAllItemsLockedLocks or unlocks one item or the whole list.
SetItemInfluenceProviderAssigns an external influence provider to an item.
SetItemInfluenceSpreadControls the minimum and maximum probability range allowed under influence.
SetItemInvertInfluenceReverses how influence affects that item.
For the conceptual walkthrough of influence, see Probability Influence.
Seeding and history
Seeding and history
CurrentSeedThe seed currently stored on the list.
SeedReturns or sets the list seed. When KeepSeed is false, RNGNeeds regenerates it before each pick.
KeepSeedKeeps the same seed between picks when enabled.
PickHistoryAccess to the stored history of recent picks.
LastPickCount / LastPickedIndex / LastPickedValueConvenience accessors for the most recent selection.
LastPickedIndices / LastPickedValuesShared result lists representing the last pick operation.
GetLastPickedIndices / GetLastPickedValuesFills your own list instead of using the shared internal lists.
SetHistoryCapacityChanges the history size.
ClearHistoryClears the list's pick history.
See also PickHistory.
Depletable lists
Depletable list helpers
IsDepletableEnables depletion behavior for the list.
RefillItemsRefills all item units back to their max values.
SetAllItemsUnitsSets the current units of all items.
SetAllItemsMaxUnitsSets the maximum units of all items.
SetAllItemsDepletable / SetAllItemsDepletablePropertiesConfigures depletion behavior across all items.
SetItemDepletableConfigures depletion for one item.
GetTotalUnits / GetTotalMaxUnitsReturns aggregate depletion information for enabled depletable items.