# new RezList()
Represents a list of values with multiple selection strategies. Lists provide various ways to retrieve values - from simple indexed access to sophisticated random selection algorithms that prevent repetition or starvation.
Basic Access
values- The underlying array of valueslength- Number of values in the listat(idx)- Get value at index (supports negative indices)lookup(value)- Find index of a value
Selection Strategies
RezList provides multiple strategies for selecting values:
Random with Replacement
randomElement()- Simple random selection, same value can appear consecutively
Random without Starvation
randomWithoutStarvation(poolId)- Ensures all values appear with roughly equal frequencywarmStarvationPool(poolId)- Pre-populates the pool to avoid initial bias
Cycle
nextForCycle(cycleId)- Returns values in sequence, wrapping at the end
Bag (Random without Replacement)
randomFromBag(bagId)- Removes and returns a random value; bag empties over time- Useful when you want each value exactly once before any repeats
Walk (Random without Replacement, Auto-Reset)
randomWalk(walkId)- Like bag, but automatically refills when empty- Guarantees all values appear once before any can repeat
Multiple Named Instances
Cycle, bag, walk, and starvation pool methods accept an optional ID parameter, allowing multiple independent instances of the same strategy on one list.
List Includes
Lists can include values from other lists via the includes attribute.
Included values are prepended to the list's own values during initialization.
Extends
Methods
# at(idx) → {*}
Gets the value at the specified index. Supports negative indices where -1 is the last element, -2 is second-to-last, etc.
Parameters:
| Name | Type | Description |
|---|---|---|
idx |
number
|
the index to retrieve (supports negative indices) |
the value at the specified index
*
# constructor(id, attributes)
Creates a new list instance
Parameters:
| Name | Type | Description |
|---|---|---|
id |
string
|
unique identifier for this list |
attributes |
object
|
list attributes from Rez compilation |
- Overrides:
# createBag(bagId) → {Array}
Creates a new bag as a copy of the list's values.
Parameters:
| Name | Type | Description |
|---|---|---|
bagId |
string
|
identifier for the bag |
the newly created bag
Array
# elementInitializer()
Called during initialization to merge values from included lists.
If the list has an includes attribute, collects values from all referenced
lists and prepends them to this list's own values.
if an included list does not exist
Error
# getBag(bagId) → {Array}
Gets the bag's current contents, creating it if it doesn't exist.
Parameters:
| Name | Type | Description |
|---|---|---|
bagId |
string
|
identifier for the bag |
the current contents of the bag
Array
# getWalk(walkId) → {Array}
Gets the current walk state, creating it if it doesn't exist.
Parameters:
| Name | Type | Description |
|---|---|---|
walkId |
string
|
identifier for the walk |
array of remaining indices to visit
Array
# length() → {number}
Returns the count of values in this list
the number of values in the list
number
# lookup(value) → {number}
Finds the index of the specified value in the list
Parameters:
| Name | Type | Description |
|---|---|---|
value |
*
|
the value to find |
the index of the value, or -1 if not found
number
# nextForCycle(cycleIdopt) → {*}
Treats the list as a repeating cycle, returning values in order and wrapping back to the start after reaching the end. Each named cycle maintains its own position, allowing multiple independent cycles on the same list.
Parameters:
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
cycleId |
string
|
<optional> |
"$default" | identifier for this cycle |
the next value in the cycle
*
# randomElement() → {*}
Returns a random element of the list with replacement. The same value can be returned on consecutive calls.
a randomly selected value from the list
*
# randomFromBag(bagIdopt) → {*}
Removes and returns a random value from the bag. The bag starts as a copy of the list's values and empties over time. Returns undefined when the bag is empty. Use this when you want each value exactly once.
Parameters:
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
bagId |
string
|
<optional> |
"$default" | identifier for this bag |
a randomly selected value, removed from the bag
*
# randomRemaining(bagId) → {*}
Low-level method that returns a random element from the bag without removing it. Prefer using randomFromBag() for typical use cases.
Parameters:
| Name | Type | Description |
|---|---|---|
bagId |
string
|
identifier for the bag |
a random value from the bag without removing it, or undefined if empty
*
# randomWalk(walkId) → {*}
Returns a random element without replacement. No item will be returned twice in any given walk. When all items have been returned, a new walk automatically begins with a fresh shuffle. Unlike bag, walk never returns undefined - it automatically resets when exhausted.
Parameters:
| Name | Type | Description |
|---|---|---|
walkId |
string
|
identifier for this walk |
the next random value in the walk
*
# randomWithoutStarvation(poolIdopt) → {*}
Returns a random element while ensuring no element goes too long without being selected. Each element tracks how many selections have passed since it was last chosen. When an element exceeds the starvation threshold (approximately length + length/3), it becomes a priority candidate. Algorithm credit: jkj yuio from intfiction.org
Parameters:
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
poolId |
string
|
<optional> |
"$default" | identifier for the starvation pool |
a randomly selected value that hasn't been "starving"
*
# resetWalk(walkId) → {Array}
Resets the walk to a fresh shuffled order of all indices. Uses Fisher-Yates shuffle for unbiased randomization.
Parameters:
| Name | Type | Description |
|---|---|---|
walkId |
string
|
identifier for the walk |
the newly shuffled array of indices
Array
# setBag(bagId, bag)
Sets the bag's contents directly.
Parameters:
| Name | Type | Description |
|---|---|---|
bagId |
string
|
identifier for the bag |
bag |
Array
|
the new bag contents |
# takeFrom(bagId, value)
Low-level method that removes the specified value from the bag. Prefer using randomFromBag() for typical use cases.
Parameters:
| Name | Type | Description |
|---|---|---|
bagId |
string
|
identifier for the bag |
value |
*
|
the value to remove from the bag |
# warmStarvationPool(poolIdopt)
Pre-populates the starvation pool by running 2*length iterations. This avoids initial bias where early selections might favor certain indices. Call this once before using randomWithoutStarvation if you want more uniform distribution from the start.
Parameters:
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
poolId |
string
|
<optional> |
"$default" | identifier for the starvation pool |