Skip to content

Box Asset Reference

The box asset is the data definition for every Steam Economy crate, mystery box, and limited-edition case in Unturned™. A box asset defines a container that a player can open - typically by consuming a Steam Economy key or by meeting a server-side unlock condition - to receive one or more cosmetic items drawn from a drop table. Box assets are the engine-side representation of the Steam inventory unboxing system; they control which items are displayed as potential rewards in the unboxing UI and which item is actually granted when the box is opened.

This article is the 57 Studios™ canonical reference for the box asset type. It covers every .dat field specific to the box asset subclass, the relationship between Generate and Destroy itemdef IDs, the Drop_# drop table system, the two probability models, and the Contains_Bonus_Items field that controls the bonus-item indicator. The shared fields that appear on every item asset (ID, GUID, Rarity, Slot, Size_X, Size_Y) are documented in Item Asset Anatomy; this article focuses on the fields that are unique to the box subclass.

The Unturned unboxing UI showing a mystery box with its contents displayed as item icons

Documentation source: This article references the official Smartly Dressed Games modding documentation for field definitions and game behavior. Shipped game file examples are drawn from the vanilla Unturned™ Bundles/Items/Boxes/ directory. Community-validated notes are marked where the official documentation is silent on a detail.

Who this article is for

This article is written for Unturned™ mod authors and server operators who are configuring a Steam Economy crate, mystery box, or custom unboxing container for their mod or server. Box assets are a niche use case within the broader modding ecosystem - most item mods do not require a box asset. The article is relevant primarily for workshop items that integrate with the Steam Economy system (cosmetic cases, seasonal crates, event boxes) and for server operators who deploy custom crate systems through the Unturned™ economy API.

If you are authoring a standard item mod (a gun, a magazine, a piece of clothing), you do not need a box asset. The box asset type is exclusively for the Steam Economy unboxing flow.

How the box system works

The box asset system is the server-side data layer that feeds the client-side Steam Economy unboxing UI. When a player right-clicks a box item in their Unturned™ inventory and selects Open, the game reads the box's .dat file, opens the Steam Economy overlay (if configured), and displays the box's contents as a grid of item icons. The player can then click to unbox, which consumes the key item (if the box requires one) and grants one random item from the drop table.

The box asset does not control the probability of receiving each drop. The probability is handled by the Steam Economy system's backend, which reads the item's rarity values and the economy configuration. The box asset controls only the UI display (which items are shown as potential drops, how many items are shown, whether the probability model is equalized or original, and the localized button text).

The sequence above shows the interaction between the client, the box asset, and the Steam Economy API. The box asset is read at the moment the unboxing UI opens; the actual item grant is handled by the Steam Economy backend.

The box asset is for Steam Economy crates only

The official Smartly Dressed Games documentation states that boxes are "used to visualize certain information from the game's Steam Economy integration" and that this asset type "is not useful to modders." This is an accurate characterization for most modding scenarios. Box assets are only relevant when a mod or server deploys items through the Steam Economy system, which requires Valve partnership-level access to the game's economy asset backend.

For standard modding purposes (workshop items that are spawned via commands or loot tables), the box asset type is not applicable. The documentation in this article is provided for completeness and for the small subset of modders who are integrating with the Steam Economy system through the official Valve economy tooling.

File structure for a box asset

A box asset folder follows the same pattern as any item asset:

MyBox/
├── Asset.dat           ← box asset definition (fields documented here)
└── English.dat         ← display name and description

The box asset does not typically require a Unity prefab because the UI representation is a grid of item icons, not a 3D model in the game world. However, the box item itself (the crate case in the player's inventory) does need an inventory icon, which is provided through the standard item icon system.

Complete .dat field reference

Identity and shared fields

The following shared fields are required on every item asset, including boxes. See Item Asset Anatomy for full documentation of these fields.

FieldTypeExampleNotes
IDuint16494Unique item ID. Vanilla boxes use IDs 400-600 range.
GUIDuint128 hex571f0e17d4bd416e8d2e6828299c0499128-bit globally unique identifier.
TypeenumBoxMust be Box for this asset type.
RarityenumLegendaryBoxes are typically Legendary to indicate their special status.
SlotenumNoneBoxes are non-equippable. They are consumed from inventory on use.
Size_Xuint81Inventory grid width. Most boxes are 1.
Size_Yuint81Inventory grid height. Most boxes are 1.

Economy linkage fields

FieldTypeRequiredExamplePurpose
Generateint32Yes21001The Steam Economy itemdef ID that is granted when the box is opened. This is the item the player receives - typically a cosmetic item, a currency item, or another container.
Destroyint32Yes20000The Steam Economy itemdef ID that is removed when the box is opened. This is typically the box itself or the key item required to open it.

The Generate and Destroy fields reference itemdef IDs from the Steam Economy system, not the Unturned™ item IDs used in .dat files. The itemdef ID is a separate identifier assigned through the Steam Economy backend. The relationship between a box's Generate value and the granted item is not a simple one-to-one mapping with the Unturned™ item system; it passes through the Steam Economy API which has its own item definition registry.

Economy itemdef IDs are not the same as Unturned item IDs

The Generate and Destroy fields take Steam Economy itemdef IDs, which are assigned through the Valve partner economy tools. They are not the same as the ID field in an Unturned™ .dat file. A common source of confusion for new economy integrators is assuming that Generate 50001 will grant the item with Unturned™ ID 50001; the economy system uses its own ID space that maps through the Steam Economy configuration.

Drop table fields

The drop table fields control which items are displayed as potential rewards in the unboxing UI. They do not control the actual probability of receiving each item - that is handled by the Steam Economy backend.

FieldTypeRequiredExamplePurpose
Dropsint32Yes13The total number of items displayed in the unboxing UI. Determines how many UI element slots are rendered.
Drop_#int32DependsDrop_0 -1The itemdef ID of an item displayed as a potential drop. The # is a zero-indexed number from 0 to Drops - 1. A value of -1 represents an empty slot.

The Drops field defines the visible count of reward slots in the unboxing UI. Each Drop_# field corresponds to one UI slot. The slots are displayed in order from Drop_0 to Drop_{Drops - 1}. A value of -1 for a Drop_# field leaves that slot empty - the UI displays a blank or placeholder position.

The official game files confirm the drop table pattern. The Mystery Box 0 (Mystery_Box_0.dat) has Drops 13 and defines Drop_0 through Drop_12. The first drop is Drop_0 -1 (an empty slot used for UI layout), and the remaining twelve slots display itemdef IDs from the Steam Economy item registry.

Real box drop table from Mystery_Box_0.dat:

  Drops 13
  Drop_0 -1
  Drop_1 49200
  Drop_2 53300
  Drop_3 49500
  Drop_4 54500
  Drop_5 52300
  Drop_6 56000
  Drop_7 50200
  Drop_8 53100
  Drop_9 56100
  Drop_10 40900
  Drop_11 49900
  Drop_12 57000

UI behavior fields

FieldTypeRequiredExamplePurpose
Item_OriginenumNoItem_Origin UnboxThe localization key for the unboxing or unwrapping button text. Valid values: Unbox, Unwrap. Controls which localization string is used for the action button in the unboxing UI.
Probability_ModelenumNoProbability_Model EqualizedThe visual presentation of drop probability in the UI. Valid values: Equalized, Original. When set to Equalized, the UI displays all items with equal visual weight regardless of backend probability. When set to Original, the UI reflects the actual probability distribution.
Contains_Bonus_ItemsboolNoContains_Bonus_Items TrueWhen true, adds a UI element indicating the box contains bonus items beyond the displayed drops. Used for boxes that have hidden bonus reward slots.

The Item_Origin field determines the verb used in the unboxing UI button. Unbox is the default and most common value, used for crates and cases. Unwrap is used for gift-style containers where the visual metaphor is unwrapping rather than unboxing.

The Probability_Model field controls only the UI presentation of drop chances, not the actual probabilities. Equalized mode displays all drops with the same card size and layout, hiding rarity asymmetries from the player's first glance. Original mode displays drops with sizes or positions that reflect their rarity tier, giving the player a visual cue about which items are more or less likely.

The Contains_Bonus_Items field adds a small indicator in the unboxing UI that extra items beyond the displayed set are possible. This is used for promotional crates that sometimes grant bonus cosmetics as a loyalty reward.

Pro field

FieldTypeExamplePurpose
ProboolProWhen present (as a bare flag in many shipped boxes), marks the box as PRO/Gold-tier. Non-PRO players can see the box but cannot open it. Most vanilla mystery boxes are marked as Pro.

All mystery boxes in the shipped game files carry the Pro flag, meaning they are restricted to Gold/PRO players. This is intentional - the Steam Economy unboxing system is designed to be a Gold-tier feature. Workshop mods that implement box assets should be aware that non-PRO players will be unable to open them.

Worked example: standard mystery box

The following .dat example represents a standard mystery box with 13 displayed drops (one placeholder slot and twelve item slots). This example mirrors the structure of the shipped Mystery Box 0.

ID 49000
GUID a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d
Type Box

Rarity Legendary
Slot None
Size_X 1
Size_Y 1

Generate 49001
Destroy 49000

Drops 13
Drop_0 -1

Drop_1 49002
Drop_2 49003
Drop_3 49004
Drop_4 49005
Drop_5 49006
Drop_6 49007
Drop_7 49008
Drop_8 49009
Drop_9 49010
Drop_10 49011
Drop_11 49012
Drop_12 49013

Pro True

Companion English.dat:

Name Mystery Crate v1
Description A standard mystery crate containing twelve possible cosmetic rewards. Requires a Steam Economy key to open.

Worked example: box with equalized probability display

The following .dat example demonstrates a box that uses Probability_Model Equalized and Contains_Bonus_Items True, mirroring the structure of the CC24 Craftable Box from the shipped game files.

ID 49014
GUID b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e
Type Box

Rarity Legendary
Slot None
Size_X 1
Size_Y 1

Generate 49015
Destroy 49014

Item_Origin Unwrap
Probability_Model Equalized
Contains_Bonus_Items True

Drops 17
Drop_0 -1
Drop_1 49016
Drop_2 49017
Drop_3 49018
Drop_4 49019
Drop_5 49030
Drop_6 49031
Drop_7 49032
Drop_8 49033
Drop_9 49034
Drop_10 49035
Drop_11 49036
Drop_12 49037
Drop_13 49038
Drop_14 49039
Drop_15 49040
Drop_16 49041

Pro True

Companion English.dat:

Name Season Event Gift
Description A seasonal gift box containing seventeen possible cosmetic items. Bonus items may be awarded beyond the displayed contents.

Worked example: box with Unbox origin and Original probability

The following .dat example demonstrates a box using Item_Origin Unbox and Probability_Model Original, with six drops and no placeholder slot.

ID 49050
GUID c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f
Type Box

Rarity Legendary
Slot None
Size_X 1
Size_Y 1

Generate 49051
Destroy 49050

Item_Origin Unbox
Probability_Model Original

Drops 6
Drop_0 49052
Drop_1 49053
Drop_2 49054
Drop_3 49055
Drop_4 49056
Drop_5 49057

Pro True

Companion English.dat:

Name Mini Crate
Description A compact crate containing six possible rewards. Uses original probability display.

Field type reference

FieldData typeValid valuesDefaultInvalid input behavior
Generateint32Any valid economy itemdef IDNone (required)Box fails to grant item; unboxing returns no reward
Destroyint32Any valid economy itemdef IDNone (required)Box fails to consume the container; item persists in inventory
Dropsint320 or greaterNone (required)UI displays no drop slots
Drop_#int32Economy itemdef ID or -1 for emptyNoneEmpty icon shown in UI for -1; unrecognized ID shows placeholder
Item_Originenum stringUnbox, UnwrapUnboxFalls back to Unbox
Probability_Modelenum stringEqualized, OriginalOriginalFalls back to Original
Contains_Bonus_ItemsboolTrue, FalseFalseParse error; field ignored
Probool or flagTrue, False, or bare flagFalseFalls back to False

Box asset subtypes in the shipped game files

The shipped game files contain two principal subtypes of box asset. Both use the same .dat field set but serve different UI and gameplay purposes.

Standard mystery box

The standard mystery box is the most common box type. It has a fixed drop count, uses the Unbox origin, and is restricted to PRO players. The drop table typically includes twelve items (with Drop_0 set to -1 as a placeholder). The Mystery_Box_0 through Mystery_Box_13 series in the shipped files follows this pattern with different drop item selections.

FileDropsDrop_0Probability_ModelContains_Bonus_Items
Mystery_Box_0.dat13-1Original (default)False
Mystery_Box_2.dat14-1Original (default)False
CC24_Craftable_Box.dat17-1EqualizedTrue

Event or limited-edition box

Event boxes share the same field set but typically use Item_Origin Unwrap and Probability_Model Equalized to signal a different visual treatment in the unboxing UI. The Contains_Bonus_Items flag is sometimes set to true for event boxes to indicate bonus reward potential. The CC24_Craftable_Box is an example of this event-oriented subtype.

Diagnostic table

SymptomMost likely causeResolution
Box appears in inventory but cannot be openedPro True set; player does not have Gold upgradeRemove Pro flag or inform players that the box requires Gold
Unboxing UI shows no itemsDrops field missing or set to 0Set Drops to the number of visible slots
Specific drop items not visible in UIDrop_# field not defined for that indexAdd Drop_# field (e.g., Drop_5) for the missing index
UI shows empty slots where items should beDrop_# value is -1Set Drop_# to the correct economy itemdef ID
Item not granted after unboxingGenerate field wrong or missingConfirm Generate value is the correct economy itemdef ID
Box not consumed after unboxingDestroy field wrong or missingConfirm Destroy value references the box's own economy itemdef ID
Unboxing UI shows wrong item countDrops does not match the number of defined Drop_# fieldsAdjust Drops to match the actual number of defined drops
Button says "Unwrap" when "Unbox" is expectedItem_Origin Unwrap setChange to Item_Origin Unbox or remove the field
Probability display looks wrongProbability_Model set incorrectlyMatch Equalized or Original to the intended UI treatment
Bonus items indicator not showingContains_Bonus_Items not set to TrueAdd Contains_Bonus_Items True
Box cannot be given via @give commandID above 2000 without Bypass_ID_LimitAdd Bypass_ID_Limit True

Frequently asked questions

Do I need a box asset for a standard workshop mod?

No. Box assets are exclusively for Steam Economy integration. If you are publishing a standard workshop item (a gun, a magazine, a piece of clothing) that is distributed through the Steam Workshop, you do not need a box asset. Box assets are only relevant for items that are distributed through the Steam Economy system.

What is the difference between Drop_# and the actual drop probability?

The Drop_# fields control which items are displayed as possible rewards in the unboxing UI. They do not control the probability of receiving each item. The probability of receiving a specific item is controlled by the Steam Economy backend configuration, which uses rarity tiers and weight values defined outside the Unturned™ .dat system.

Can I have more than 13 drops?

Yes. The Drops field accepts any positive int32 value. The CC24 Craftable Box uses Drops 17 with 17 defined Drop_# fields. The practical limit is governed by the UI layout - too many drops will produce a cluttered unboxing interface.

What does Drop_0 -1 do?

Drop_0 -1 creates an empty slot in the first position of the unboxing UI grid. Many mystery boxes use this pattern to leave a visual gap in the top-left position of the item icon grid, producing a visually balanced layout. The -1 value is a special sentinel meaning "no item in this slot."

Why are all vanilla mystery boxes Pro-only?

The Steam Economy unboxing system in Unturned™ is designed as a Gold-tier feature. Vanilla mystery boxes carry the Pro flag to restrict unboxing to players who own the Gold upgrade. This is an enforced design decision by Smartly Dressed Games. Mod authors who use box assets should be aware that non-PRO players will not be able to open their boxes.

Can I make a box that does not require a key?

The Steam Economy system handles key requirements at the backend level, not the .dat level. The box .dat does not have a field that controls whether a key is required. If the economy system is configured to allow unboxing without a key, the box can be opened freely. If a key is required by the economy configuration, the unboxing flow will prompt the player to provide one.

Can I configure different probability weights for each drop?

No. Probability weights are not configured in the box's .dat file. They are configured in the Steam Economy backend through the Valve partner tools. The box asset only controls the UI display of available drops, not the probabilities.

What does Probability_Model Equalized look like in practice?

When Probability_Model Equalized is set, every item in the drop grid is displayed with the same size card and visual weight. The player cannot visually distinguish rare items from common items by card size alone. This produces a more uniform UI presentation. When Probability_Model Original is used, the UI may display items with different card sizes or positions to reflect rarity differences.

Should I use Item_Origin Unbox or Unwrap?

Use Unbox for crates, cases, and standard containers. Use Unwrap for gift-styled containers where the visual metaphor involves unwrapping. The choice affects only the button text in the unboxing UI; the underlying behavior is identical.

Does Contains_Bonus_Items grant actual extra items?

The field only adds a UI indicator that bonus items are possible. Whether bonus items are actually granted depends on the Steam Economy backend configuration. The field is purely a UI signal to the player.

Can a box have zero drops?

Setting Drops 0 produces a box that opens to an empty UI. This is not a practical configuration. Always set Drops to at least 1 and define the corresponding Drop_# fields.

What happens if I omit the Pro flag on a workshop box?

The box becomes openable by both PRO and non-PRO players. This is generally acceptable for workshop items, but note that the vanilla mystery boxes all use the Pro flag, so players may expect boxes to require Gold. If your box does not require Gold, document this in the workshop description.

Are box assets compatible with non-Economy servers?

Box assets require the Steam Economy API to function for unboxing. On servers that do not have Steam Economy configured (most community servers), the unboxing flow will not work. The box item still exists as an inventory item and can be given, dropped, or traded, but it cannot be opened.

Can I make a box that contains other boxes?

Yes. A box's Generate field can reference another box's economy itemdef ID. This creates nested crates (a mystery box that grants another mystery box). Nested crates are unusual in practice because they frustrate players - opening one crate to receive another crate feels unrewarding. Use nested crates only for multi-stage unboxing events with clear communication to the player.

How do I test a box without spending real Steam Economy keys?

In single-player or on a local server with economy integration disabled, the box can be spawned with @give <boxID> and opened without consuming a key. The unboxing UI opens but the grant may fail if the economy backend is unreachable. For full key-based testing, a test environment with the Steam Economy configuration set to test mode is required.

What file encoding should I use for box .dat files?

Unturned™ .dat files use UTF-8 encoding with BOM (byte order mark). The shipped mystery box files all begin with the UTF-8 BOM (EF BB BF). The cohort recommendation is to save all .dat files with UTF-8 BOM encoding to match the vanilla format. UTF-8 without BOM may also work but is not consistent with the shipped game files.

Can I use the same economy itemdef ID across multiple boxes?

No. Each box should have a unique Generate and Destroy economy itemdef ID. Sharing economy IDs across boxes produces incorrect unboxing behavior because the economy system cannot distinguish which box granted which item. Each box variant requires its own dedicated economy itemdef registration.

Best practices

  • Only use the Box asset type when you have a specific Steam Economy integration requirement. For standard workshop items, use the appropriate item type (Gun, Magazine, Clothing, etc.) without a box wrapper.
  • Document clearly in the workshop description whether the box requires Gold (PRO) status to open. Players who purchase or find a box they cannot open will leave negative feedback.
  • Use Drop_0 -1 when the number of drops does not produce a visually balanced grid. The placeholder slot prevents a lopsided layout.
  • Set Probability_Model explicitly even when using the default. An explicit field documents the author's intent for future maintainers.
  • Set Contains_Bonus_Items True only when the Steam Economy backend is actually configured to grant bonus items. Misleading the player with an inaccurate bonus indicator erodes trust.
  • Match the Item_Origin value to the visual design of the box. A gift-wrapped box that the player "unwraps" fits Unwrap. A military-grade crate that the player "unboxes" fits Unbox.
  • Test the box on a non-PRO account if the box does not carry the Pro flag, to confirm that non-PRO players can open it correctly.
  • Verify the Generate and Destroy economy itemdef IDs in the Steam Economy backend before finalizing the box configuration. An incorrect Generate ID will grant the wrong item; an incorrect Destroy ID will fail to consume the box.

Appendix A: Box .dat field quick reference

FieldTypeRequiredDefaultPurpose
IDuint16Yes-Unique item ID
GUIDuint128Yes-Globally unique identifier
TypeenumYes-Must be Box
Generateint32Yes-Economy itemdef ID granted on open
Destroyint32Yes-Economy itemdef ID consumed on open
Dropsint32Yes-Number of items displayed in unboxing UI
Drop_#int32Depends-Economy itemdef ID of a displayed drop
Item_OriginenumNoUnboxUI button localization key
Probability_ModelenumNoOriginalUI probability display mode
Contains_Bonus_ItemsboolNoFalseShow bonus items indicator
ProboolNoFalseRestrict to Gold/PRO players

Appendix B: Shipped box file reference

The following table documents the configuration of every mystery box and craftable box in the vanilla Unturned™ game files at the time of this writing. Mod authors can use this table as a reference for their own box configurations.

FileDropsHas Drop_0 -1Probability_ModelContains_Bonus_ItemsPro
Mystery_Box_0.dat13YesOriginal (implied)-Yes
Mystery_Box_1.datUnknown---Yes
Mystery_Box_2.dat14YesOriginal (implied)-Yes
Mystery_Box_3.datUnknown---Yes
Mystery_Box_4.datUnknown---Yes
Mystery_Box_5.datUnknown---Yes
Mystery_Box_6.datUnknown---Yes
Mystery_Box_7.datUnknown---Yes
Mystery_Box_8.datUnknown---Yes
Mystery_Box_9.datUnknown---Yes
Mystery_Box_10.datUnknown---Yes
Mystery_Box_11.datUnknown---Yes
Mystery_Box_12.datUnknown---Yes
Mystery_Box_13.datUnknown---Yes
CC24_Craftable_Box.dat17YesEqualizedTrueYes
CC24_Premium_Box.datUnknown---Yes
Cali2_Blue_Box.datUnknown---Yes
Cali2_Red_Box.datUnknown---Yes

Appendix C: External references

Advanced considerations

Box assets and the Steam Economy API integration

The box asset is the Unturned™ client-side representation of a Steam Economy container. The actual integration with the Steam Economy API requires:

  • A Steam Economy configuration set up through the Valve partner tools
  • Item definition IDs (itemdefs) assigned to each cosmetic or reward item in the economy backend
  • An economy bundle configuration that maps Unturned™ item IDs to Steam itemdef IDs
  • The Generate and Destroy values in the box .dat must match itemdef IDs from the economy configuration, not the Unturned™ item IDs

The economy configuration pipeline is owned by the server operator or the workshop item publisher who has Steam Economy access. The box .dat fields documented in this article are the data entry point; the economy backend configuration is a separate process that is outside the scope of this article.

Box assets without Steam Economy

On servers that do not have Steam Economy integration, the box asset's unboxing functionality does not execute. The box item exists as a standard inventory item and can be manipulated like any other item (given, dropped, destroyed) but the right-click Open action produces no result. If a mod author wants a crate-like item that can be opened on non-Economy servers, the correct approach is a custom barricade or storage item that simulates opening through the barricade interaction system, not a box asset.

Event box lifecycles

Event boxes (seasonal crates, promotion boxes) have the same field set as standard boxes but typically use Item_Origin Unwrap and Probability_Model Equalized to create a distinct visual identity in the unboxing UI. The lifecycle of an event box (when it is available, when it expires, which items are in its drop pool) is controlled by the Steam Economy backend configuration. The .dat file does not have expiration date fields or seasonal availability controls.

Cross-references

Document history

VersionDateAuthorNotes
1.02026-07-2657 StudiosInitial publication. Full box asset .dat field reference, Steam Economy integration notes, drop table system, probability models, shipped file reference.