HOW-TO: Use containers and generate loot

Containers are placed to generate Loot the player acquires to upgrade equipment and enhance their combat ability.

Find out more about Loot definitions, Container Templates, Quest / Script Methods & actions, and more.

Loot Definitions

By choosing the appropriate Loot Definition, we are able to reward the player with items and gear that best represent the container's environment and the level of challenge required to obtain it. This value can range from junk items and common crafting components to high quality swords and armor to flawless gems and legendary relics.

Loot Entries

A Loot Definition is defined by a specific set of Loot Entries. Each Loot Entry represents a specific Item that may be spawned based on the player's level and the chance the item will spawn. Combining these factors allows the user to control when specific types of items are allowed to enter the player's inventory and the rate at which they may be received.

Table of contents:

1 Loot Definitions
- 1.1 Loot Entries
- 1.2 Loot definition setup
- 1.3 Loot entry setup
2 Container Templates
3 Loot Parameters
4 Quest Script Methods
5 Scene Script Actions
6 Scene Timeline Events

Loot definition setup

By designing a unique Loot Definition, we are able to present the player with items and gear that best represent the container's type and the player's level of progression through the game.

To generate a Loot Definition in XML, define the following parameters accordingly.

Name	When creating a Loot Definition, make sure to use a unique name that adequately describes how the definition will be used.
Player Level Min	Level requirement the player must reach before definition is available.
Player Level Max	Level requirement that restricts the definition from being available if the player is over the specified level.
Quantity Min	The minimum number of loot entries that will be generated.
Quantity Max	The maximum number of loot entries that will be generated.
Respawn Time	This is the time in seconds before Loot will be regenerated. A respawn time of zero means no loot will regenerate.

Example

<loot
name="_herbalist area_nml"
player_level_min="0"
player_level_max="0"
quantity_min="2"
quantity_max="5"
respawn_time="0"
>

Loot entry setup

A Loot Definition is defined by a specific set of Loot Entries. Each Loot Entry represents a specific Item that may be spawned based on the player's level and the chance the item will spawn. Combining these factors allows the designer to control when specific types of items are allowed to enter the player's inventory and the rate at which they may be received.

Name	When creating a loot entry, make sure to use the name of the item the entry will generate.
Player Level Min	Level requirement the player must reach before this item entry is available. If not minimum exists, the value should be set to zero.
Player Level Max	Level requirement that restricts the item entry from being available if the player is over the specified level. If not maximum exists, the value should be set to zero. If a minimum value has been set, the maximum value must be larger than the minimum.
Quantity Min	The minimum number of this item type that will be available for purchase.
Quantity Max	The maximum number of this item type that will be available for purchase.
Chance	This is the percent chance (1 - 100) that the item will spawn. A chance of -1 forces the item to spawn every time.

Example

< loot_entry
name="Fish"
player_level_min="0"
player_level_max="0"
quantity_min="15"
quantity_max="20"
chance="100"
/>

Container Templates

Using the Entity Editor, pre-defined Container Templates can be created for quickly placing Loot in the world.

Found through the Asset Browser, we can choose from an existing template or create a new one based on the needs of the current level.

For The Witcher 3, Templates were sorted into the following basic categories:

Barrel
Bundle
Casket
Chest
Corpse
Crate
Sack
Shelf
Skeleton

Loot Parameters

Double clicking a Container Template opens the content within the Entity Editor.

Node Properties

In the Entity Editor, we can adjust the various Node properties including settings for W3Container and W3AnimatedContainer.

For instance, a container can be made inactive by setting the disableLooting to true.

Gameplay Properties

In the Entity Editor, we can also view and adjust Gameplay properties to create and customize a Container's specific Loot Parameters.

To Create a Loot Parameter:

Left-click the Gameplay params Add Item (Plus Button).
Select CR4LootParam to create a Loot Parameter.
Type the name of the new Loot Parameter and press Enter.

To Adjust the Loot Parameter:

Select the desired Loot Parameter from the list of Gameplay params.
To Add a Loot Container Parameter:
- Select the containers array and press the Green Plus button.

Containers with multiple Loot Container Parameters must set usedContainersMin / Max accordingly.

to Expand the Containers Array:
- Press the Tree Expand button listed under the CR4LootParam properties sheet.
to Remove a Loot Container Parameter:
- Select the specific Loot Container Parameter and press the Red X button.

To Adjust a Loot Container Parameter:

Expand the Containers Array and select the desired CR4LootContainerParam.
To Set the Loot Definition:
- Select the Name property field, expand the list of loot definitions and select the desired loot definition.

Quest Script Methods

Action	Description

Action	Description
AddItemQuest	Main function for adding items in quest structures.
AddItemQuestExt	Similar to the first one, just uses item selector instead of a name field, allowing for a search among all valid item definitions.
AddAndEquipItemsRandomlyQuest	Kinda custom function, selects a group of NPCs, adds and equips one random item from the array on them.
AddAndEquipItemsRandomlyQuestExt	The same with selector.
CollectItemsQuest	Technically it's used to have the player give item to something/someone, but if parameter keepItemsInContainer is true, we can take those items back, so it could be used for giving items theoretically.
TransferItemQuest	Allows for transferring items between two inventory components, works back and forth.
TransferPlayerItemsQuest	Specific function for transfering targeted player item to a container and returning them from that container.
GiveMerchantRandomGwintCardToPlayer	Used in Gwent implementation, gives random gwent card from the pool, if the pool is empty gives crafting components.
GiveSpecificGwentCardViamerchantQuest	Similar to the last one, but you can give a specific item. Also gives random crafting components.
Reward block from quest	If selected reward has an item defined it will give this item alongside other defined rewards (exp, money).

Scene Script Actions

Action	Description

Action	Description
CollectItems	The same as CollectItemsQuest, but launched from a scene.
GiveRewardToPlayer	Gives reward to a player during scene, works the same as Reward block from quest.
AddItemOnNPC_S	Similar to AddItemQuest, but in scene.
ShopQuestItemManager	A special script fired before some merchant shops, that adds / removes quest specific items to the shop on the fly based on facts.

Scene Timeline Events

Event	Description

Event	Description
RewardToPlayer	Timeline event that allows for selecting a reward or a specific item to be given mid dialogue section.