Skip to main content

Upgrade to 1.4.0

Stoch 1.4.0 includes many notable features and it overhauls many aspects of the plugin. We understand changing existing code might be frustrating for some users, but after reading Rationale, we hope you will understand why these overhauls greatly improve the plugin.

We've broken up the guide into multiple parts:

Prerequisites​

  • You have an existing project which you would like to update to 1.4.0.

Rationale​

Performance Concerns​

Applying row filters and composing loot tables could be costly on performance. Most of this came from blueprint overhead, so it wasn't really something we could improve. When looking at possible fixes, we realized that most of the data being filtered is completely available at design time; this means we can run the row filter in the editor and store the results to be accessed at runtime. This is exactly what Mask Generators do. They apply row filters1 and write the results in a float mask that's stored in the loot table template. These masks can be accessed at runtime, granting the benefits of blueprint row filters without the runtime costs.

Composition was also costly (mainly because of row filters), but also due to merging rows. As such, we refactored composition:

  • Composition doesn't include row filters or row modifiers anymore.
  • Composition now always appends tables together (no merging).
  • Composition can compose float masks.

With these changes, composition is mainly used for combining multiple tables (and float masks) together, rather than modifying loot table weights or counts. Its performance should be substantially better.

Deprecating Nested Bags​

Nested bags added a lot of complexity to loot tables; moreover, when reassessing them, we determined their uses can be handled better elsewhere. Nested Bags' most prominent feature, mutual exclusion, is handled more cleanly by applying float masks instead. Moreover, trying to modify nested bags manually can be difficult because nested parent rows are represented by a loot table reference rather than a data table or data asset. As such, nested bags have been deprecated. We recommend using float masks instead for most cases.

Changes​

Recompile All Loot Tables​

All loot tables must be recompiled after updating, due to changes in internal data. You can do this manually or use the new STCompileAllLootTablesCommandlet to automatically compile all loot tables.

Replace Row Filters with Float Masks​

  1. How you create the mask depends on whether your row filter needs runtime data:
    • No Runtime Data: Add a Row Filter float mask generator2 and add your row filter.
    • Runtime Data: Call FilterToMask on your row filter.
  2. Call ApplyMaskToWeights with mode Multiply.

Replace Restocking with Float Masks​

  1. Add a Loot Table Count float mask generator to your loot table; this will copy the counts of each row into a float mask.
  2. When you want to restock, get this mask and call ApplyMaskToCounts on your loot table with mode Assign.

Remove Nested Bags​

Nested bags have been deprecated for the reasons above. All uses for nested bags can be replaced with other methods:

  • We updated the example map and changed all nested bags to other distributions.
  • Mutual Exclusion: If you were using nested bags for mutual exclusion, instead apply a float mask after sampling: check which row was sampled, and filter out mutually exclusive rows. The ARPG Loot Generation example does this for affixes.
  • Shared Ownership: If you were using nested bags for shared ownership, we recommend you handle this outside of the loot table / distribution.
  • Nesting: Most of the uses for nesting can be covered by float masks.

Update Loot Table Composition​

The existing ComposeLootTables function has been deprecated and replaced with a new version. The new version excludes row filters and row modifiers, and includes float masks instead. Moreover, the new version always appends the tables in the order it receives them, making composition faster.

Instead of applying row filters or row modifiers during composition, you can store the changes into a float mask and apply that instead. If you're not composing multiple tables, you can even avoid composition altogether: just instantiate the table and apply the float mask to it.

With these changes, composition isn't mandatory for changing weights/counts at runtime anymore; its purpose is solely to combine multiple tables / float masks together.

Update Loot Registration​

Because we changed composition, the LootRegistrationComponent needs to be updated as well. The new registration struct uses the new composition method (see above).

  1. Or other operations; see the options for built-in mask generators.↩
  2. Or replace your row filter with one of the built-in mask generators.↩