Skip to main content

Loot Registry

The STLootRegistrySubsystem can be used to store loot tables for re-use. To start out this guide, we'll go through the most common usage: World Settings.

Registration​

World Settings​

Most commonly, you will want to store a list of loot tables for a specific world. That is, maybe your loot in level 1 is different from the loot in level 10. Using the STWorldSettings, you may set a list of loot tables to automatically create when the world is loaded, and optionally destroy when the world is destroyed. These tables can then be accessed from the STLootRegistrySubsystem.

Setup​

Before we start, we have to set our world settings object in the project settings. In the top menu bar, go to Edit > Project Settings. In the project settings window, find Engine > General Settings and update the World Settings class to STWorldSettings:

A prompt will pop up asking you to restart the editor. You must restart the editor before continuing this guide.

note

If you have your own world settings class already, instead add the STLootRegistrationComponent to your world settings actor.

Using the World Settings​

Now we may define the loot tables we want to automatically register for each world. Open a level of your choice, and navigate to the world settings tab (Window > World Settings). You may add a list of loot tables to be automatically registered:

When defining loot tables you want to register, there are a few key points:

  1. The "Table Name" field will be used to reference this table later. Each table name MUST be unique or else it will fail to register.
  2. The "Templates", "Row Filters", "Row Modifiers", and "Combine Mode" fields are used to compose the loot table which we register.
  3. The "Table Tags" field attaches tags to this table in the registry.
    1. You may search for loot tables in the registry which match a gameplay tag query.
  4. The "Lifetime Mode" field determines when the table will be automatically unregistered.
    1. If you select "World", the table will be unregistered when the world is cleaned up (i.e., when you switch worlds).
    2. If you select "Component", the table will be unregistered when the registering component is uninitialized. For the world settings, this is mostly the same as selecting "World".
    3. If you select "Manual", the table will not be unregistered automatically. It is your responsibility to unregister the table, or else it will stay in memory as long as your game is running.

After you have defined the loot table, it will be composed and registered with the STLootRegistrySubsystem when this world is loaded during gameplay.

info

The STLootRegistrationComponent ONLY registers loot tables when the net mode is a server (Standalone, Listen Server, or Dedicated Server).

STLootRegistrationComponent​

You may attach the STLootRegistrationComponent to any actor. It will compose and register its loot tables when the actor is initialized.

Accessing Stored Loot Tables​

Direct​

You may access the loot tables stored in the STLootRegistrySubsystem by name. In the example above, we can access the loot table named "Fruits":

You may also search for registered loot tables using a Gameplay Tag Query or Gameplay Tag Requirements:

See the unreal engine documentation for info on gameplay tags and gameplay tag queries.

STLootRegistryHandle​

You may also use an STLootRegistryHandle to reference a loot table in the registry. If added to an actor or component that is placed in a level, you can choose from any loot tables defined in STLootRegistrationComponents for that level:

Otherwise, you may input the loot table's name directly.

You can use the "GetLootTableFromRegistry" function for registry handles:

note

If you are using World Partition, the actors owning STLootRegistrationComponents must be loaded to be referenced by an STLootRegistryHandle.

Recommendations​

Recommendations for using the loot registry:

  • Our primary goal was to provide a place to store loot tables for objects with shorter lifetimes than the loot tables they use. For example, multiple actors can access the same table from the loot registry even though the actors might be destroyed at any time. We believe in most cases like this, the actors will have enough context to know the table name they're accessing.
  • The registry can't store STLootTableTemplates. This is by design; templates don't need to be instanced, so they don't need to be stored in this way.
    • While we would like to provide a place to organize your templates, this isn't feasible for a plugin because a good solution would need to rely on the data access patterns for your specific project.
  • Accessing based on tags can be very slow. It searches through all tables in the registry, so use it sparingly. We recommend using names whenever you can.
  • Names are preferable over Gameplay Tags because names can also be created at runtime; you could potentially store tables using procedural names.
  • If you want to store tables based on a single gameplay tag, you can convert the tag to a name using the function GetTagName and use that instead.
  • We don't recommend modifying your tables after accessing them from the registry. You should store the fully modified tables in the registry directly.
  • As of 1.3.0, we have added functions for finding the tables' names from a tag query instead. This way your systems which read from the registry can store the tables' names if they need to reaccess tables based on tags.