Nested Bag

caution

Nested bags have been deprecated. See the upgrade guide for alternatives.

Nested bags are similar to weighted bags, but they allow nesting distributions within each other. They associate integer weights, counts, and parents for each item.

Example 1: General

Nested bags make the most sense when nesting distributions together. Suppose we have two Weighted Bags, each pointing at colored items:

Distribution A (Weighted Bag)
Row Name	Count	Weight	Probability
Red	3	100	50% (100 / 200)
Blue	2	100	50% (100 / 200)

This is great, but what if we want a second distribution which references A:

Distribution B (Invalid)
Row Name	Count	Weight	Probability
Dist A	10	-	-

We might want this because it makes distributions more modular. Uses of this distribution are detailed in Loot Tables.

By referencing another distribution with a row, we are saying two things:

1. We want all rows in the referenced distribution to be included in our new distribution.
2. When sampling, we want a maximum of Count items from the referenced distribution.

When taken together, these conditions allow powerful control over how items are sampled: mutual exclusion and multiple parents, for example.

While our intent is clear, Distribution B is not a valid Nested Bag. Nested bags require:

• All rows which can be sampled must be in the same distribution.
• All distributions being referenced must have their own item.
• Items with children cannot have weights.
  • As a result, items with children are never sampleable on their own. E.g., invoking 'Sample' on B will never return A.

We could reconstruct distribution B so it's properly formed:

Distribution C (Nested Bag)
Color	Count	Weight	Probability	Parents
Red	3	100	33% (100 / 300)	Dist A
Blue	2	100	33% (100 / 300)	Dist A
Dist A	10	-	-

note

You may be wondering why we can't change the weights of rows we reference. This is possible with loot tables.

Example 2: Count

Sampling an item decreases its count and the count of all parents. Suppose we sample Red from Distribution C:

Distribution C (After Sampling Red)
Color	Count	Weight	Probability	Parents
Red	2	100	33% (100 / 300)	Dist A
Blue	2	100	33% (100 / 300)	Dist A
Dist A	9	-	-
Green	5	100	33% (100 / 300)	Dist B
Dist B	10	-	-

Both Red's count and A's count are decreased, because A is a parent of Red.

Example 3: Eligibility

Children's eligibility depends on parents' count being greater than 0:

Distribution D (Nested Bag)
Row Name	Count	Weight	Probability	Parents
Green	5	100	100% (100 / 100)
Red	3	100	0% (Ineligible)	Dist A
Blue	2	100	0% (Ineligible)	Dist A
Dist A	0	-	-

Both Red and Blue are ineligible because their parent, Distribution A, has a count of 0. However, Green is still eligible because it doesn't have any parents.

Example 4: Mutual Exclusion

Items can be made mutually exclusive by sharing a common parent. With the distribution below, we can sample up to 5 items, either Red or Blue:

Distribution E (Nested Bag)
Row Name	Count	Weight	Probability	Parents
Red	5	100	50% (100 / 200)	Dist A
Blue	5	100	50% (100 / 200)	Dist A
Dist A	5	-	-

Example 5: Multiple Parents

Items can have multiple parents. In the distribution below, Red's count is limited by both A and B.

Distribution F (Nested Bag)
Row Name	Count	Weight	Probability	Parents
Red	5	100	100% (100 / 100)	Dist A, Dist B
Dist A	1	-	-
Dist B	3	-	-

Suppose we sample Red:

Distribution F (After Sampling Red)
Row Name	Count	Weight	Probability	Parents
Red	4	100	0% (Ineligible)	Dist A, Dist B
Dist A	0	-	-
Dist B	2	-	-

All parents (A and B) have their count decreased when Red is sampled. Red becomes ineligible because A has count = 0.

Advanced

Eligibility

Weight > 0, Count > 0, and Count of all parents > 0.