Archmage.WeightedPool

Items with selection weights, the type of a wtpool field, for drawing an item with a probability proportional to its weight.

Inherits: RefCounted

The total weight must be from 1 to 1,000,000,000 when an item is drawn.

Properties

items

var items: Array = []

The items, of the item type of the field. An item that references a config entry holds the entry.

weights

var weights: Array[int] = []

The weight of each item in items. A weight is not negative.

Methods

from_json()

static func from_json(d: Variant, conv: Callable, e: Archmage.ParseError = null, refs: bool = false) -> Archmage.WeightedPool

Returns the pool in d, a parsed JSON object, converting each item with conv.call(item, e), or null when d is null. When conv records an error in e, returns null. When refs is true, the converted items are config IDs: they go to _ref_ids, and items holds null for each of them until the generated code resolves them.

When d is not an object, items or weights is not an array, or a weight is not a number, the type mismatch is recorded in e (see Archmage.ParseError.report_mismatch()). The value of the wrong type is then treated as null.

to_json()

func to_json() -> Dictionary

Returns the pool as a JSON object. An item that references a config entry is written as its config ID.

size()

func size() -> int

Returns the number of items.

duplicate()

func duplicate() -> Archmage.WeightedPool

Returns a shallow copy of the pool. The copy has its own items and weights arrays, so changing them does not change this pool, but the items themselves, such as config entries, are shared.

sample()

func sample(rng: RandomNumberGenerator = null) -> Variant

Returns an item drawn with a probability proportional to its weight, using rng, or the global random number generator, which seed() affects, when rng is null. When the pool is empty or the total weight is not from 1 to 1,000,000,000, reports an error and returns null.

sample_index()

func sample_index(rng: RandomNumberGenerator = null) -> int

Returns the index of an item drawn as sample() draws it, or -1 when sample() reports an error.

sample_with()

func sample_with(value: float) -> Variant

Returns the item that value maps to, so that a call with the same value always returns the same item. The values from 0 to 1 are divided among the items in proportion to their weights. A value below 0 maps to the first item with a non-zero weight, and a value of 1 or more maps to the last. Reports an error and returns null in the same cases as sample().

sample_index_with()

func sample_index_with(value: float) -> int

Returns the index of the item that sample_with() returns, or -1 when it reports an error.