Compilation

Overview

Loot Table Templates must be compiled before they can be instantiated at runtime. Compilation takes the authored data (seen in the Authoring Tab) and compiles it into optimized data visualized in the Built Table Tab.

Mechanics

References

Loot Table Templates reference data table rows or other loot table template rows using Ref Table and Ref Row Name. The references are resolved when they are compiled.

note

Referenced tables must share the same Row Struct, and (when referencing another template) the same Distribution Type.

Reference Mode

Ref Mode, or reference mode, determines what row(s) will be taken from the referenced table.

When set to row, only children of the row we are referencing will be included:

Data Table Fruits
Row Name	Display Name
Apple	Apple
Banana	Banana

Loot Table Template B (Unlimited)
Row Name	Ref Table	Ref Row Name	Weight	Ref Mode	Weight Inherit Mode
X	Fruits	Apple	200	(See Below)	Parent

Compiled Loot Table B (Ref Mode: Row)
Ref Table	Ref Row Name	Weight
Fruits	Apple	200

When set to sub table, all children of that table will be included:

Compiled Loot Table B (Ref Mode: Sub Table)
Ref Table	Ref Row Name	Weight
Fruits	Apple	100
Fruits	Banana	100

note

When set to Ref Mode: Sub Table, the Ref Row Name will be ignored.

Weight

Compiling weight depends on the Weight Inherit Mode of the authored row.

tip

It's recommended to set weights as multiples of at least 100. This gives you plenty of room for precise probabilities. It also makes using row modifiers much easier.

Count

note

The Count property is only visible for weighted bags and nested bags. For grab bags, count is always equal to weight.

Compiling count depends on the Count Inherit Mode of the authored row.

Weight Inherit Mode

Weight inherit mode determines what weight to use when compiling a sub-table. For example, suppose we had these tables:

Loot Table Template C (Unlimited)
Row Name	Ref Table	Ref Row Name	Weight	Ref Mode	Weight Inherit Mode
X	Fruits	-	200	Sub Table	Parent

Loot Table Template D (Unlimited)
Row Name	Ref Table	Ref Row Name	Weight	Ref Mode	Weight Inherit Mode
Y	Table C	X	100	Row	(See Below)

When set to Parent, the parent row's weight will be equally divided among all children. In case of rounding errors, the parent's weight will always be fully distributed. If set to Parent, Table D would be compiled as:

Compiled Loot Table D (Weight Inherit Mode: Parent)
Ref Table	Ref Row Name	Weight
Fruits	Apple	50
Fruits	Banana	50

When set to Child, all children of the row will not have their weights modified. If set to Child, Table D would be compiled as:

Compiled Loot Table D (Weight Inherit Mode: Child)
Ref Table	Ref Row Name	Weight
Fruits	Apple	100
Fruits	Banana	100

note

This output is the same as if we compiled Table C itself.

note

When Weight Inherit Mode is set to Child, Weight of the parent row is ignored.

caution

The row will be pruned if Weight Inherit Mode is set to 'Child' while referencing a Data Table.

Count Inherit Mode

Count inherit mode's Parent and Child options work the same as weight inherit mode. However, count can also be nested.

Nesting

All loot tables can reference each other, but only nested bags can be compiled into nested rows:

Nested rows will be compiled into:

• The parent row, which will have the count from the authored row.
• The child row(s), which will have their original count.

Nesting causes the count from the parent row(s) to limit the eligibility of child row(s). See Nested Bag for more details.

:::question" title="Why can't I nest weights? Weight Inherit Modes can do everything that nesting weights would enable. :::

General

Compile Results

Results from compilation can be seen in the Build Results tab.

Pruning

Warnings caused by compiling invalid rows will Prune, or ignore, the rows from the built table. Suppose we have this table:

Loot Table Template E (Unlimited)
Row Name	Ref Table	Ref Row Name	Weight	Ref Mode	Weight Inherit Mode
X	Fruits	Orange	100	Row	Parent

Table E, Row X will be pruned because it doesn't reference a valid row from the Fruits table.

note

Pruned rows will always be listed as warnings in the Build Results tab.

Errors

Compile errors are only emitted when compilation fails. If an error occurs, the built template will be empty. Errors are also displayed in the build results tab.

Options

Auto Compile

When auto-compile is enabled, any changes which can affect the compile results will automatically cause a compile.

Auto-Compilation can be toggled by clicking the dropdown button next to the compile button in the toolbar:

Combine Mode

info

The default of Merge (Strict) should be sufficient for most uses. Continue below for more detailed examples.

Combine mode defines how two compiled rows which reference the (Data Table, Row Name) pair will be handled when compiling the template.

note

Combine mode only affects the root table being compiled. Combine modes for sub-table(s) are ignored.

Suppose we have these tables:

Loot Table Template F (Unlimited)
Row Name	Ref Table	Ref Row Name	Weight	Ref Mode	Weight Inherit Mode
X	Fruits	Apple	100	Row	Parent
Y	Fruits	Banana	100	Row	Parent
Z	Fruits	Apple	100	Row	Parent

When we compile F, we must determine how to handle these tables:

Partial Compiled Table F (Row X)
Ref Table	Ref Row Name	Weight
Fruits	Apple	100
Fruits	Banana	100

Partial Compiled Table F (Row Z)
Ref Table	Ref Row Name	Weight
Fruits	Apple	100

When combine mode is Merge or Merge (Strict), these rows will be combined into:

Compiled Loot Table F (Merge or Merge (Strict))
Ref Table	Ref Row Name	Weight
Fruits	Apple	200
Fruits	Banana	100

The rows referencing table Fruits, row Apple are merged together, with their weights added together. If these rows had counts, that would also be added together.

note

Merging only occurs when the row being referenced is exactly the same. E.g., the reference to Banana is not merged.

note

Behavior is the same for Merge and Merge (Strict) for all distributions except nested bag.

When the combine mode is Append, these rows will be combined into:

Compiled Loot Table F (Append)
Ref Table	Ref Row Name	Weight
Fruits	Apple	100
Fruits	Banana	100
Fruits	Apple	100

Using Append, rows are always appended to the end of the table, even if they can be merged.

tip

We recommend to always use merge or merge (strict) combine mode when using distribution types of Unlimited or grab bag. There are no downsides to merging for these distributions.

Merging for Distributions with Counts

When merging rows from weighted bags and nested bags, merge does not lead to the same behavior as append. Suppose we have the following table:

Loot Table Template G (Weighted Bag)
Row Name	Ref Table	Ref Row Name	Weight	Count	Ref Mode	Weight Inherit Mode
X	Fruits	Apple	100	1	Row	Parent
Y	Fruits	Banana	100	1	Row	Parent
Z	Fruits	Apple	100	1	Row	Parent

Compiled Loot Table G (Merge or Merge (Strict))
Row Index	Ref Table	Ref Row Name	Weight	Count	Probability
0	Fruits	Apple	200	2	66%
1	Fruits	Banana	100	1	33%

Compiled Loot Table G (Append)
Row Index	Ref Table	Ref Row Name	Weight	Count	Probability
0	Fruits	Apple	100	1	33%
1	Fruits	Banana	100	1	33%
2	Fruits	Apple	100	1	33%

If we sampled Row 0 from the merged table, the probabilities would not change because count is still above 0 (2 -> 1):

Compiled Loot Table G (Merge, After Sampling Row 0)
Row Index	Ref Table	Ref Row Name	Weight	Count	Probability
0	Fruits	Apple	200	1	66%
1	Fruits	Banana	100	1	33%

However, if we sampled row 0 from the appended table, row 0 would become ineligible and thus the probabilities would change:

Compiled Loot Table G (Append, After Sampling Row 0)
Row Index	Ref Table	Ref Row Name	Weight	Count	Probability
0	Fruits	Apple	100	0	0%
1	Fruits	Banana	100	1	50%
2	Fruits	Apple	100	1	50%

Nested Merging

Nested bags handle Merge (Strict) differently than other distributions. Using Merge (Strict), only rows with equivalent references AND equivalent parents will be merged. Suppose we have these tables:

Loot Table Template H (Nested Bag)
Row Name	Ref Table	Ref Row Name	Weight	Count	Ref Mode	Weight Inherit Mode
X	Fruits	Apple	100	1	Row	Parent

Loot Table Template I (Nested Bag)
Row Name	Ref Table	Ref Row Name	Weight	Count	Ref Mode	Weight Inherit Mode
Y	H	X	100	1	Row	Parent
Z	Fruits	Apple	100	1	Row	Parent

Compiled Loot Table I (Merge)
Row Index	Ref Table	Ref Row Name	Weight	Count	Parents
0	Fruits	Apple	200	2	1 (H.X)
1	H	X	-	1

Compiled Loot Table I (Merge (Strict))
Row Index	Ref Table	Ref Row Name	Weight	Count	Parents
0	Fruits	Apple	100	2	1 (H.X)
1	H	X	-	1
2	Fruits	Apple	100	1

With Merge combine mode, rows with equivalent references are always merged. This results in parents being merged as well. Table C, Row X is merged with Table D, Row Z.

With Merge (Strict) combine mode, rows with equivalent references must have the same parents to be merged. Thus, Table C, Row X and Table D, Row Z cannot be merged.

Compilation Commandlet

Stoch includes the STCompileLootTablesCommandlet for compiling all loot tables. This commandlet ensures tables with dependencies are compiled in the correct order. We highly recommend running this commandlet before packaging your game to ensure your compiled data is up-to-date.

You can pass -RegenerateMasks to also regenerate masks.