Loot

Summary

Loot are a "recipe" or "script" with instructions for how to modify a player's inventory.

Loot Schema

Name	Required	Description
loot_id	Yes	Unique ID (within the sandbox) for this Loot
vendor_id	Yes	Parent Vendor of this Loot
name	No	Name of the resource
description	No	Description of the resource
custom_data	No	Game-specific metadata about this loot. RallyHere does not modify/interact with this as part of fulfilling the loot (or considering it for randomly sampled), but it is included in catalog requests from the environment.
item_id	No	Optional Item that will be granted to the player if Sub Vendor ID is not specified. Items of type `recipe` or `recipe_with_price_reduction` are never granted to player inventory. If left empty, Loot will fulfill as if there was an item of type `recipe_with_price_reduction`. If the item is of type `entitlement`, this Loot MUST be configured with the same Sub Vendor as all other Loot with the same item.
sub_vendor_id	No	Optional Vendor ID that will be used to fulfill the Loot instead of granting the Item. If the item is of type `recipe_with_price_reduction`, price reduction occures for this Loot based on the player's inventory ownership of the Item's on this sub Vendor's Loot, and the configured price of that Loot. If there is no item, or the item is of type `recipe` or `recipe_with_price_reduction`, the Sub Vendor is filled - all loot are filled for `recipe` subvendors, and quantity "samples" are taken from `randomly_sampled` subvendors.
quantity	No	The quantity of the Item or Sub Vendor to fulfill. This will be multiplied by the quantity of fulfilled Loot and the parent Loot if quantity_type is relative. See Inventory Selector Type for more info.
inventory_selector_type	Yes	See schema
inventory_operation	Yes	See schema
active	No	If the loot will be fulfilled when included in an order
sort_order	No	Lower sort order will be fulfilled first. Inventory Operation is used as a tie breaker when sort_order is the same
drop_weight	No	When considering for a randomly sampled vendor, higher drop weight will be more likely to be fulfilled.
fill_in_new_order	No	When dropped in a randomly sampled vendor, will this create a new order or fill inline?. The primary use case for this is when you want the same loot to be dropped multiple times in a randomly sampled vendor.
allow_partial_bundles	No	When dropped in a randomly sampled vendor, will the sub vendor allow dropping part of the the bundle? False means it will only drop if the entire sub vendor can be given to the player
required_item_id	No	When considering for a randomly sampled vendor, item required to be owned/rented to drop this loot
required_item_count	No	When considering for a randomly sampled vendor, amount of the required_item_id to be owned/rented to drop this Loot
stack_limit	No	When considering for a randomly sampled vendor, amount of owned/rented of this Loot's item that will prevent this Loot from dropping
quantity_type	No	See schema
quantity_multi_inventory_item_id	No	Quantity of this Loot will be multiplied by the count of this Item in the Player's Inventory.
is_claimable_by_client	No	Determines if the Loot can be claimed by the client. This is dangerous without the correct loot confiuration as a client could claim Loot multiple times.
time_frame_id	No	Time Frame that calculates the expiration time of inventory selected by this Loot when Inventory Selector Type is `rent_timeframe_locked`.
use_inventory_bucket	No	If the Item is configured with a "Inventory Bucket Use Rule Set", setting this field will force this Loot to update inventory only with the corresponding bucket. See Platform Rule Sets for Cross Progression/Commerce for more info.
xp_quantity_transform_type	No	Quantity of this Loot (calculated from the `quantity`, `quantity_type`, and `quantity_multi_inventory_item_id` is modified using the selected transformation See schema. Requires an Item be assigned on the Loot to determine the Level XP Table.
current_price_point_id	No	The current price point id. Optional Price Point ID that will be used to determine the price of the Loot when it is fulfilled.
pre_sale_price_point_id	No	The pre sale price point id. Optional Price Point ID that will be used to show the previous price of the Loot.
hard_quantity_maximum	No	Hard cap on quantity of an item this Loot can give. Disabled with 0

Inventory_selector_type Enum Values

Value	Description
own	"persistent" ownership across Inventory Sessions. Will not expire. Quantity modification will modify the inventory's count.
rent	"persistent" ownership across Inventory Sessions. Will expire after a period of time. Quantity modification will modify the inventory's expiration time.
rent_timeframe_locked	"persistent" ownership across Inventory Sessions. Will expire at the time_frame_id's next end time. Quantity modification will modify the inventory's count.
own_transient	"transient" ownership that will be deleted when the player begins their next Inventory Session. Will not expire. Quantity modification will modify the inventory's count.
inherit_entitlement_inventory	Loot fulfilled will look for a parent Entitlement and then grant the Item as transient Inventory with the rental expiration matching the parent's expiration. e.g. Parent entitlement is owned, this will be `own_transient` e.g. Parent entitlement has 3 days left on rental, this will add transient rental for 3 days. NOTE: This selector type is highly-specialized, and should only be used with Inventory Operation `add`.

Inventory_operation Enum Values

Value	Description
add	Add to the quantity or expiration of the Inventory. (negative quantities are identical to `subtract`)
subtract	Subtract from the quantity or expiration of the Inventory. (negative quantities are identical to `add`)
set	Set the quantity or expiration of the Inventory.
check_greater_than_or_equal	Check if the quantity or expiration of the Inventory is greater than or equal to the value.
check_less_than	Check if the quantity or expiration of the Inventory is less than the value.
check_greater_than_or_equal_and_subtract	Check if the quantity or expiration of the Inventory is greater than or equal to the value and subtract the value from the quantity or expiration.

Quantity_type Enum Values

Value	Description
relative	Loot will be fulfilled using the quantity defined on the record, and traverse up the loot/vendor hierarchy multiplying parent loot quantities. If a parent loot is quantity type `absolute` this process will short-circuit. If all parent loot are also quantity type `relative`, the order entry's quantity is also multiplied in.
absolute	Loot will be fulfilled using EXACTLY the quantity defined on the record, ignore the order context.

Use_inventory_bucket Enum Values

Value	Description
free	Inventory given away for free.
sweat	Inventory earned by players through in game activities.
none	Inventory that doesn't belong to any known platform.
anon	Inventory assigned to the Anonymous platform.
amazon	Inventory assigned to the Amazon platform.
steam	Inventory assigned to the Steam platform.
psn	Inventory assigned to the playstation platform.
xbox_live	Inventory assigned to the Xbox platform.
google	Inventory assigned to the Google platform.
twitch	Inventory assigned to the Twitch platform.
nintendo_switch	Inventory assigned to the Nintendo Switch platform.
apple	Inventory assigned to the Apple platform.
nintendo	Inventory assigned to the Nintendo platform.
epic	Inventory assigned to the Epic platform.
google_play	Inventory assigned to the Google Play platform.
nintendo_ppid	Inventory assigned to the Nintendo PPID platform.

Xp_quantity_transform_type Enum Values

The quantity calculated from the provided quantity, LTI quantity, quantity type, and quantity mult inventory item is modified using the selected transformation. Requires the item on the Loot has an Level XP Table, otherwise this value is ignored.

Value	Description
none	Quantity will be treated as XP and will not be transformed.
from_current_xp_to_target_additional_level_min_xp	Quantity will be treated as level to fulfill and will be transformed to the amount of XP required to reach the min xp of the fulfilled levels.
from_current_level_min_xp_to_target_additional_level_min_xp	Quantity will be treated as levels to fulfill and will be transformed to the amount of XP required to reach the min xp of the fulfilled levels from the min xp of the current level.
from_zero_to_target_exact_level_min_xp	Quantity will be treated as levels to fulfill and will be transformed to the amount of XP required to reach the min xp of the fulfilled levels from zero xp.

Examples

Provided here are some pseudo configurations of loot and what they could be used for. Some of these are basics, and some are showing more complex interactions.

Add to inventory

When this loot is included in an order for a player, that player's inventory will add 1 of the item "avatar". If they don't have any existing "avatar" inventory, a new inventory record will be created.

Vendor "test"
- Loot "give avatar"
  - Item: "avatar"
  - Inventory Selector Type: own
  - Inventory Operation: add
  - Quantity: 1
  - Active: true

Set currency

When this loot is included in an order for a player, that player's "Cool Bucks" item will be set to 100.

Vendor "test"
- Loot "set cool bucks"
  - Item: "cool bucks"
  - Inventory Selector Type: own
  - Inventory Operation: set
  - Quantity: 100
  - Active: true

Add to inventory - only if that item is not already owned

When this loot is included in an order for a player, it will check if they have less an 1 "avatar" item. If they do, it will add 1 "avatar" item to their inventory. Otherwise it will fail to fill.

Vendor "test"
- Loot "give avatar, if the player doesn't already have the avatar"
  - Item: no item
  - Quantity: 1
  - Active: true
  - Sub Vendor: "give avatar, if the player doesn't already have the avatar"
    - Loot: "Check that player doesn't have avatar"
      - Item: "avatar"
      - Inventory Selector Type: own
      - Inventory Operation: check_less_than
      - Quantity: 1
      - Active: true
      - Sort order: 1
    - Loot: "give avatar"
      - Item: "avatar"
      - Inventory Selector Type: own
      - Inventory Operation: add
      - Quantity: 1
      - Active: true
      - Sort order: 2

Add to inventory - only if the player has never received this loot before (same as above, but works with items that can be consumed)

When this loot is included in an order for a player, it will check if the player has a "receipt" item. If they do, it will fail to fill. If they don't, it will add 300 "MyCoolCurrency" item to their inventory.

Vendor "test"
- Loot "Give 300 currency if the player has never received this loot before"
  - Item: no item
  - Quantity: 1
  - Active: true
  - Sub Vendor: "Give 300 currency if the player has never received this loot before"
    - Loot: "Check if player has receipt"
      - Item: "Receipt for MyCoolCurrency rewards"
      - Inventory Selector Type: own
      - Inventory Operation: check_less_than
      - Quantity: 1
      - Active: true
      - Sort order: 1
    - Loot: "Give receipt"
      - Item: "Receipt for MyCoolCurrency rewards"
      - Inventory Selector Type: own
      - Inventory Operation: add
      - Quantity: 1
      - Active: true
      - Sort order: 2
    - Loot: "Give 300 currency"
      - Item: "MyCoolCurrency"
      - Inventory Selector Type: own
      - Inventory Operation: add
      - Quantity: 300
      - Active: true
      - Sort order: 3

Add to inventory - up to a quantity maximum

When this loot is included in an order for a player, it will fill up to a quantity maximum (500 in this case), anything over that will be reset back to 500.

Vendor "test"
- Loot "give currency up to 500"
  - Item: no item
  - Quantity: 1
  - Active: true
  - Sub Vendor: "give avatar, if the player doesn't already have the avatar"
    - Loot: "give currency"
      - Item: "MyCoolCurrency"
      - Inventory Selector Type: own
      - Inventory Operation: add
      - Quantity: 1
      - Active: true
    - Loot: "Ensure currency is less than 500"
      - Item: no item
      - Quantity: 1
      - Active: true
      - Sub Vendor: "Ensure currency is less than 500"
        
        Loot: "Check that player doesn't have more than 500"
        
        Item: "MyCoolCurrency"
        
        Inventory Selector Type: own
        
        Inventory Operation: check_greater_than_or_equal
        
        Quantity: 500
        
        Quantity Type: absolute
        
        Active: true
        
        Sort order: 1
        
        Loot: "Set the player's currency to 500"
        
        Item: "MyCoolCurrency"
        
        Inventory Selector Type: own
        
        Inventory Operation: set
        
        Quantity: 500
        
        Quantity Type: absolute
        
        Active: true
        
        Sort order: 2

Client Claimable Loot

This loot is configured to be "claimable by client", meaning that it can be used with the FillLoot order entry type, even by orders with a source of Client. This allows clients to submit this order. Since most clients are untrusted, this flag defaults to off. When we set it, we should take care that the loot is idempotent - and will not apply multiple times if the client submits it multiple times.

Vendor "test"
- Loot "Give Tutorial Rewards if never received before"
  - Item: no item
  - Quantity: 1
  - Quantity Type: Absolute
  - Active: true
  - Is Claimable By Client: true
  - Sub Vendor: "Give Tutorial Rewards if never received before"
    - Loot: "Check if player has completed the tutorial before"
      - Item: "Receipt for completed tutorial"
      - Inventory Selector Type: own
      - Inventory Operation: check_less_than
      - Quantity: 1
      - Active: true
      - Sort order: 1
    - Loot: "Give receipt"
      - Item: "Receipt for completed tutorial"
      - Inventory Selector Type: own
      - Inventory Operation: add
      - Quantity: 1
      - Active: true
      - Sort order: 2
    - Loot: "Give 500 Player XP"
      - Item: "Player XP"
      - Inventory Selector Type: own
      - Inventory Operation: add
      - Quantity: 500
      - Active: true
      - Sort order: 3

Set player to a specific "level"

When this loot is included in an order for a player, it will set the player's level to 5. This is done by setting the player's XP to the minimum XP required to reach level 5. See XP Tables for configuring level thresholds.

Vendor "test"
- Loot "set level to 5"
  - Item: "Player XP"
  - Inventory Selector Type: own
  - Inventory Operation: set
  - Quantity: 5
  - Active: true
  - XP Quantity Transform Type: from_zero_to_target_exact_level_min_xp

Add 1 level to a player

When this loot is included in an order for a player, it will add 1 level to the player. This is done by adding the minimum XP required to reach the next level to the player's XP. This works even if the leveling is non-linear. See XP Tables for configuring level thresholds.

Vendor "test"
- Loot "add 1 level"
  - Item: "Player XP"
  - Inventory Selector Type: own
  - Inventory Operation: add
  - Quantity: 1
  - Active: true
  - XP Quantity Transform Type: from_current_xp_to_target_additional_level_min_xp

Add to inventory - only if the player is level 10

When this loot is included in an order for a player, it will first check that the player is at least level 10. If so, it will add 300 currency to the player's inventory This is done by treating the quantity on the loot as a "level", and calculating how much XP is required to reach the minimum of that level. This works even if the leveling is non-linear. See XP Tables for configuring level thresholds.

Vendor "test"
- Loot "Give 300 currency if the player is level 10"
  - Item: no item
  - Quantity: 1
  - Active: true
  - Sub Vendor: "Give 300 currency if the player is level 10"
    - Loot: "Check if player is Level 10"
      - Item: "Player XP"
      - Inventory Selector Type: own
      - Inventory Operation: check_greater_than_or_equal
      - Quantity: 1
      - Active: true
      - Sort order: 1
      - XP Quantity Transform Type: from_current_xp_to_target_additional_level_min_xp
    - Loot: "Add 300 Currency"
      - Item: "MyCoolCurrency"
      - Inventory Selector Type: own
      - Inventory Operation: add
      - Quantity: 300
      - Active: true
      - Sort order: 2

Example "Fixup" Loot

This loot is an example of a "Fixup" to apply to players that might be in a broken state.

If a player owns MyCoolSkin, it will take it away and give 1000 MyCoolCurrency.
If a player has 15 MyTreasureChests, it will take them away and give 100 MyCoolCurrency.

Vendor "test"
- Loot "Special Fixup"
  - Item: no item
  - Inventory Selector Type: own
  - Inventory Operation: check_greater_than_or_equal
  - Quantity: 1000
  - Active: true
  - Sub Vendor: "Special Fixup"
    - Loot: "Big Spender Fixup"
      - Item: no item
      - Quantity: 1
      - Active: true
      - Sort order: 1
      - Sub Vendor: "Big Spender Fixup"
        
        Loot: "Consume MyCoolSkin if possible"
        
        Item: "MyCoolSkin"
        
        Inventory Selector Type: own
        
        Inventory Operation: check_greater_than_or_equal_and_subtract
        
        Quantity: 1
        
        Active: true
        
        Sort order: 1
        
        Loot: "Refund currency"
        
        Item: "MyCoolCurrency"
        
        Inventory Selector Type: own
        
        Inventory Operation: add
        
        Quantity: 1000
        
        Active: true
        
        Sort order: 2
    - Loot: "Small Spender Fixup"
      - Item: no item
      - Quantity: 1
      - Active: true
      - Sort order: 2
      - Sub Vendor: "Small Spender Fixup"
        
        Loot: "Consume 15 MyTreasureChests if possible"
        
        Item: "MyTreasureChests"
        
        Inventory Selector Type: own
        
        Inventory Operation: check_greater_than_or_equal_and_subtract
        
        Quantity: 15
        
        Active: true
        
        Sort order: 1
        
        Loot: "Refund currency"
        
        Item: "MyCoolCurrency"
        
        Inventory Selector Type: own
        
        Inventory Operation: add
        
        Quantity: 100
        
        Active: true
        
        Sort order: 2

Summary​

Loot Schema​

Inventory_selector_type Enum Values​

Inventory_operation Enum Values​

Quantity_type Enum Values​

Use_inventory_bucket Enum Values​

Xp_quantity_transform_type Enum Values​

Examples​

Add to inventory​

Set currency​

Add to inventory - only if that item is not already owned​

Add to inventory - only if the player has never received this loot before (same as above, but works with items that can be consumed)​

Add to inventory - up to a quantity maximum​

Client Claimable Loot​

Set player to a specific "level"​

Add 1 level to a player​

Add to inventory - only if the player is level 10​

Example "Fixup" Loot​