Item Asset Anatomy

Intermediate40-60 minutesWindowsUnity EditorBlenderNotepad++

Every item in Unturned™ — guns, magazines, clothing, food, medical supplies, melee weapons, traps, and tools — is defined by a set of plain-text .dat files that the game reads at load time. Understanding the structure of these files is the single most leveraged skill in Unturned modding: it applies to every item type, every slot, and every mod category on the Steam Workshop.

This article is the 57 Studios™ canonical reference for item asset anatomy. It covers the shared fields that appear across every item asset type, the relationship between meta.dat and the per-item .dat, the parse order Unturned uses to read these files, and the enum values for every standard field. The article also provides an ASCII syntax diagram of a well-formed .dat file, a full per-field type table, the complete Rarity tier enum reference, and the Slot enum with all valid values.

This is the reference article for modders who need to understand the structure of .dat files from first principles. Modders building a specific item type (gun, magazine, clothing) should additionally read the item-type-specific articles that extend this shared field set with type-specific fields.

Background: what is an item asset?

An Unturned™ item asset is the data definition that makes a gameplay object — a gun, a shirt, a can of beans — exist in the game world. The asset defines the item's identity (its numeric ID and GUID), its appearance (which prefab the engine loads from the bundle), its inventory behavior (how many grid cells it occupies, which slot it occupies), and its gameplay properties (rarity, useable behavior, damage, weight).

The asset is not code. It is a configuration file. The Unturned engine reads the .dat file, constructs an in-memory asset object from the fields it finds, and registers that object with the item registry. The gameplay code then reads properties from the registry whenever it needs them — when a player picks up the item, when the item is dragged to a slot, when the item is used.

This configuration-driven architecture is why Unturned modding is accessible: modders do not need to compile or modify the game's C# source. They author text files, bundle a Unity prefab, and the engine handles the rest.

Why this matters for modders

Every hour spent understanding shared .dat fields returns value across every item mod you author. A field learned in the context of a gun mod applies identically in a clothing mod, a food mod, or a medical supply mod. The shared fields documented in this article are the foundation layer under every item type.

The item asset file structure

An item asset lives in a folder. The folder name is the item's internal name. The minimum folder contents for a functional item mod are:

MyItem/
├── Asset.dat           ← the primary asset definition (fields documented here)
├── English.dat         ← display name and description (localization)
└── MyItem.unity3d      ← the master bundle (prefab, textures, materials)

Some items use additional files:

MyItem/
├── Asset.dat
├── English.dat
├── MyItem.unity3d
├── meta.dat            ← optional: metadata consumed by the map editor and legacy systems
└── Icon.png            ← optional: overrides the auto-generated inventory icon

Naming convention

The cohort convention for 57 Studios™ mods is to name the primary asset file Asset.dat rather than the item's internal name. This matches the pattern used by Smartly Dressed Games in the vanilla asset set and in the official Unturned modding documentation.

ASCII .dat syntax diagram

The .dat format is a flat key-value text format. Each line is one field. The key and value are separated by a single space. There is no hierarchy, no nesting, no quoting, and no trailing delimiters. Comments are not natively supported; modders sometimes use // prefixes as a convention, but the parser reads them as field names and silently ignores them.

┌─────────────────────────────────────────────────────────┐
│  Unturned .dat file — flat key-value format             │
│─────────────────────────────────────────────────────────│
│                                                         │
│  FIELD_NAME VALUE                                       │
│  ──────┬── ──┬──                                        │
│        │     └─ Value: string, uint8, uint16, uint32,   │
│        │           float, bool, or enum string.         │
│        │           Separated from the key by ONE space. │
│        └─ Key: uppercase, underscore-separated.         │
│              Case-sensitive in most parsers.            │
│                                                         │
│  ID 3001                                                │
│  GUID f47ac10b58cc4372a5670e02b2c3d479                  │
│  Type Gun                                               │
│  Rarity Uncommon                                        │
│  Slot Primary                                           │
│  Size_X 4                                               │
│  Size_Y 1                                               │
│  Weight 0.5                                             │
│  Useable Gun                                            │
│  Pro True                                               │
│                                                         │
│  Rules:                                                 │
│  • One field per line. No blank lines required.         │
│  • No trailing whitespace (causes parse errors on       │
│    some fields).                                        │
│  • Enum values are case-sensitive.                      │
│  • Boolean values are True or False (capitalized).      │
│  • Float values use period (.) as decimal separator.    │
│  • uint fields do not accept negative values.           │
│  • Unknown fields are silently ignored by the parser.   │
│                                                         │
└─────────────────────────────────────────────────────────┘

Case sensitivity

Enum values are case-sensitive. Rarity uncommon will not parse correctly; the correct form is Rarity Uncommon. Field names are also case-sensitive in the Unturned parser — id is not recognized; the field must be ID. Always author .dat files in Notepad++ or another editor that preserves exact casing.

How Unturned parses item assets

Unturned reads item assets at startup (or on Workshop content reload). The parse sequence is:

┌─────────────────────────────────────────────────────────────┐
│  Unturned item asset parse sequence                         │
└─────────────────────────────────────────────────────────────┘

1. Engine scans all known bundle/content directories.
2. For each directory, engine finds every Asset.dat (or <name>.dat).
3. Parser reads Type field first — determines which asset subclass to instantiate.
4. Parser reads ID field — registers the asset ID in the global item registry.
5. Parser reads GUID field — registers the GUID in the global asset registry.
6. Parser reads all remaining fields in document order.
7. Unknown fields are silently skipped.
8. Required fields that are absent cause the asset to fail to load (error in console).
9. Asset is added to the registry; items with duplicate IDs: last-loaded wins.
10. meta.dat is read separately by the map editor and legacy spawn table systems.

Duplicate IDs

If two mods define the same numeric ID, the last-loaded mod's item silently replaces the earlier one in the registry. Players on servers with conflicting mods will receive unexpected items when the conflicting ID is spawned. The cohort recommendation is to choose IDs in the 50000+ range, where vanilla and most established Workshop mods do not operate. See Project Folder Structure and GUIDs for the GUID workflow that prevents GUID collisions independently of numeric IDs.

The meta.dat file

meta.dat is a secondary file consumed by the Unturned map editor and by the game's legacy spawn table and economy systems. It is separate from the primary asset .dat and is not loaded by the same parser. Not all items require a meta.dat; it is most relevant for items that appear in spawn tables, economy bundles, or map editor palettes.

Common meta.dat fields:

Field	Type	Purpose
Exclude_From_Sandbox	bool	Prevents the item from appearing in sandbox editor mode.
Economy_Bundle	string	Associates the item with a Steam economy bundle.
Map_Editor_Category	string	Controls which palette category the item appears in.
Spawn_Table_Group	string	Assigns the item to a spawn table group for loot generation.

meta.dat is optional

Most Workshop item mods do not need a meta.dat. The primary use case is items that must appear in specific spawn tables or economy systems. If you are building a standalone mod item that is spawned via commands or given to players directly, you can omit meta.dat entirely.

Shared .dat fields: complete reference

The fields in this section appear across every item asset type. Every item — regardless of whether its Type field is Gun, Magazine, Shirt, Food, Medical, or any other type — reads these shared fields first before reading type-specific fields.

Identity fields

Field	Type	Required	Example	Purpose
ID	uint16	Required	3001	Numeric item ID. Unique within a mod. Must not collide with vanilla (0–2000) or other mods. Cohort recommendation: 50000+.
GUID	uint128 hex	Required (modern)	f47ac10b58cc4372a5670e02b2c3d479	128-bit globally unique identifier. The GUID is the stable cross-reference used by maps, spawn tables, and other mods. Generate with uuidgen or the cohort GUID tool.
Type	enum	Required	Gun	The item asset type. Controls which subclass the parser instantiates. See Type enum reference below.
Name	string	Optional	MyRifle	Internal name. Not shown to players; used in editor palettes and console commands.

Rarity field

Field	Type	Required	Example	Purpose
Rarity	enum	Optional (defaults to Common)	Uncommon	The item's rarity tier. Controls the color of the item name in UI and the probability weight in some spawn tables. See Rarity enum reference below.

Inventory slot and size fields

Field	Type	Required	Example	Purpose
Slot	enum	Required for equippable items	Primary	The inventory slot the item occupies when equipped. See Slot enum reference below. Non-equippable items (food, medical) use None.
Size_X	uint8	Optional (defaults to 1)	4	The width of the item in inventory grid cells. A value of 4 means the item spans four columns.
Size_Y	uint8	Optional (defaults to 1)	1	The height of the item in inventory grid cells. A value of 1 means the item occupies one row.
Size_Z	float	Optional	0.5	The depth used by the item's world-space collision box when dropped on the ground. Rarely needed; defaults to the mesh bounds.

Size_X and Size_Y in practice

An assault rifle is typically Size_X 4, Size_Y 1 (four columns wide, one row tall). A backpack is typically Size_X 2, Size_Y 3 (two columns wide, three rows tall). A pill bottle is typically Size_X 1, Size_Y 1. The cohort recommendation is to match the visual footprint of the item as it would appear in the inventory — a longer item should have a higher Size_X, a taller item should have a higher Size_Y.

Useable and item behavior fields

Field	Type	Required	Example	Purpose
Useable	enum	Optional	Gun	The behavior script applied when the item is equipped and used. Determines which Useable* script runs. Matches Type for most item types.
Item	string	Optional	MyRiflePrefab	The name of the prefab in the master bundle. If omitted, the engine uses the item name from the Name field.
Bypass_ID_Limit	bool	Optional	False	Allows IDs above the legacy 2000 ceiling. Always set to True for Workshop mods with IDs above 2000.
Should_Drop_On_Death	bool	Optional	True	Controls whether the item is dropped on player death. Default is True.
Count_Min / Count_Max	uint8	Optional	1 / 5	Min and max item count when this item spawns in a loot table.

Physical and interaction fields

Field	Type	Required	Example	Purpose
Weight	float	Optional	0.5	The item's weight contribution to the player's carry weight. Higher weight slows movement more.
Allow_Damage	bool	Optional	True	Whether the item can be damaged (for items that have durability).
Durability	float	Optional	100	Starting durability. Requires Allow_Damage True.
Wear	float	Optional	0.05	Durability loss per use event.
Should_Delete_At_Zero	bool	Optional	True	If True, the item is destroyed when durability reaches zero. If False, it persists at zero durability.
Equipable	bool	Optional	True	Whether the item can be moved to an equip slot. Default is True for equippable types.

Economy and Pro fields

Field	Type	Required	Example	Purpose
Pro	bool	Optional	False	If True, the item is a Gold/PRO-tier item available only to players with Unturned gold (PRO) status. The cohort recommendation is to leave this False for Workshop mods unless the mod is explicitly gating content.
Reward	uint16	Optional	0	The economy reward ID associated with this item. Consumed by the Steam economy system.

Localization and display fields

Field	Type	Required	Example	Purpose
Description	string	Discouraged in asset .dat	—	Description text. Prefer English.dat for localization. The Description field in the primary .dat is a legacy pattern; new mods should use English.dat.

Rarity tier enum reference

The Rarity field accepts the following enum values. The values are listed in ascending tier order.

Enum value	UI color	Spawn table weight convention	Notes
Common	White / default	High weight; spawns frequently	Default value when Rarity is omitted. Most tool, food, and clothing items.
Uncommon	Green	Medium-high weight	Mainstream firearms, functional armor.
Rare	Blue	Medium weight	High-tier firearms, specialized equipment.
Epic	Purple	Low weight	Exceptional firearms, full-set armor.
Legendary	Gold/Yellow	Very low weight	Endgame tier. Military-grade hardware.
Mythical	Animated/special	Typically zero spawn weight	Economy-exclusive cosmetics. Not used in standard loot.

Rarity and spawn tables

The Rarity field does not directly control spawn probability. Spawn probability is controlled by spawn table configuration (weight values in spawn table .dat files). The Rarity field controls the display color of the item name in the inventory UI and in tooltips. Some spawn table generators use Rarity as a shorthand for weight tiers, but the field itself is purely cosmetic at the engine level.

Slot enum reference

The Slot field accepts the following enum values. Each value maps to a specific inventory panel slot.

Enum value	Inventory panel	Typical item types	Notes
Primary	Primary weapon slot	Assault rifles, sniper rifles, shotguns, LMGs, bows	Only one Primary item equipped at a time.
Secondary	Secondary weapon slot	Pistols, PDWs, crossbows	Only one Secondary item equipped at a time.
Tertiary	Tertiary / melee slot	Melee weapons, some specialized tools	Melee weapons typically use this slot.
Hat	Hat slot	Hats, helmets, headgear	Replaces or layers with mask depending on item.
Mask	Mask / face slot	Gas masks, faceguards, scarves
Glasses	Glasses slot	Goggles, visors, sunglasses
Shirt	Shirt slot	Shirts, jackets, upper-body armor
Pants	Pants slot	Pants, lower-body armor
Vest	Vest / chest slot	Tactical vests, armor plates	Separate from shirt layer.
Backpack	Backpack slot	Backpacks, pouches	Capacity defined by Backpack-type asset fields.
None	No equip slot	Food, medicine, materials, misc items	Item remains in storage; is used from inventory directly.

Slot and inventory organization

When authoring a new item type, select the Slot value that matches how players will interact with the item. A deployable trap might use None (deployed from inventory, not equipped to a slot). A melee weapon uses Tertiary. Clothing uses the appropriate clothing slot. Incorrect Slot assignments cause items to fail to equip or to appear in the wrong inventory panel.

Type enum reference

The Type field determines the asset subclass. The parser uses this field to decide which additional fields to read beyond the shared set documented in this article.

Enum value	Asset subclass	Extends with
Gun	ItemGunAsset	Caliber, Firemode, Recoil, Ballistic, Attachment slot fields
Magazine	ItemMagazineAsset	Amount, Caliber_Reference, Speed, Pellets, Explosion fields
Sight	ItemSightAsset	Zoom, Nightvision fields
Tactical	ItemTacticalAsset	Laser, Light, Rangefinder fields
Grip	ItemGripAsset	Recoil modifier fields
Barrel	ItemBarrelAsset	Volume, Durability modifier fields
Clothing	ItemClothingAsset	Armor, Movement, Warmth, Rain fields
Hat	ItemHatAsset	Extends Clothing fields
Mask	ItemMaskAsset	Extends Clothing fields; Gas filter fields
Shirt	ItemShirtAsset	Extends Clothing fields
Pants	ItemPantsAsset	Extends Clothing fields
Vest	ItemVestAsset	Extends Clothing fields
Backpack	ItemBackpackAsset	Width, Height capacity fields
Glasses	ItemGlassesAsset	Extends Clothing fields; Vision type fields
Food	ItemFoodAsset	Food, Water, Virus, Stamina, Bleeding restore fields
Medical	ItemMedicalAsset	Health, Bleeding, Broken restore fields
Melee	ItemMeleeAsset	Damage, Attack speed, Range fields
Fuel	ItemFuelAsset	Fuel amount field
Tool	ItemToolAsset	Quality modifier fields
Barricade	ItemBarricadeAsset	Barricade ID, Structure health fields
Structure	ItemStructureAsset	Structure ID, Structure health fields
Supply	ItemSupplyAsset	Generic supply fields
Trap	ItemTrapAsset	Damage, Radius, Explosive fields
Grower	ItemGrowerAsset	Plant growth modifier fields
Optic	ItemOpticAsset	Zoom, Color filter fields
Refill	ItemRefillAsset	Refill amount, target item fields
Fisher	ItemFisherAsset	Fishing reward table fields
Cloud	ItemCloudAsset	Reserved for future use
Map	ItemMapAsset	Chart and map reveal fields
Key	ItemKeyAsset	Economy key fields
Box	ItemBoxAsset	Economy box unbox reward table fields
Arrest_Start	ItemArrestStartAsset	Handcuff bind target fields
Arrest_End	ItemArrestEndAsset	Handcuff release target fields
Vehicle_Repair_Tool	ItemVehicleRepairToolAsset	Vehicle repair amount fields
Vehicle_Paint_Tool	ItemVehiclePaintToolAsset	Vehicle paint fields
Generator	ItemGeneratorAsset	Generator power fields

Type drives everything downstream

The Type field is the most important field in any .dat file. It determines which asset subclass the parser instantiates, which additional fields are read, and which gameplay script is applied at runtime. Setting Type incorrectly (e.g., Type Magazine on a gun asset) causes the wrong subclass to be instantiated, and almost every field beyond the shared set will either be silently ignored or misread.

Per-field type table

The table below documents the data type of every shared field, its valid range, its default value when omitted, and parse behavior on invalid input.

Field	Data type	Valid range	Default	Invalid input behavior
ID	uint16	1–65535	None (required)	Asset fails to load
GUID	32-char hex string	Valid 128-bit hex	None (required for modern assets)	Asset fails GUID registration; falls back to ID-only lookup
Type	enum string	See Type enum reference	None (required)	Asset fails to load
Name	string	Any printable string	Empty string	Accepted silently
Rarity	enum string	Common, Uncommon, Rare, Epic, Legendary, Mythical	Common	Falls back to Common
Slot	enum string	See Slot enum reference	None	Falls back to None
Size_X	uint8	1–8	1	Values out of range clamp to nearest valid
Size_Y	uint8	1–8	1	Values out of range clamp to nearest valid
Size_Z	float	> 0	Mesh bounds	Ignored if negative
Weight	float	≥ 0	0	Negative values treated as 0
Useable	enum string	See Type enum reference	Matches Type	Falls back to None
Item	string	Prefab name in bundle	Matches Name	Engine cannot find prefab; item renders as invisible
Pro	bool	True / False	False	Parse error; field ignored
Reward	uint16	0–65535	0	Ignored if invalid
Allow_Damage	bool	True / False	Depends on type	Parse error; field ignored
Durability	float	0–100	100	Clamped to 0–100
Wear	float	0–1	0	Clamped to 0–1
Should_Delete_At_Zero	bool	True / False	True	Parse error; field ignored
Bypass_ID_Limit	bool	True / False	False	Parse error; field ignored
Should_Drop_On_Death	bool	True / False	True	Parse error; field ignored
Count_Min	uint8	1–255	1	Clamped to 1–255
Count_Max	uint8	1–255	1	Clamped to 1–255
Equipable	bool	True / False	True	Parse error; field ignored

The English.dat localization file

Every item asset should have a companion English.dat file in the same folder. The English.dat provides the display name and description that players see in the inventory UI and tooltips.

Name My Rifle
Description A custom rifle mod authored for the Unturned community.

Unturned supports additional localization files (French.dat, German.dat, etc.) in the same folder. When the game is running in a language that has a matching localization file, that file takes precedence over English.dat for display strings. When no matching language file is found, English.dat is the fallback. The cohort recommendation for Workshop mods is to author English.dat first and to add additional languages only when community translation contributors are available.

Do not put Name and Description in the primary asset .dat

The Description field in the primary asset .dat is a legacy pattern from early Unturned versions. Modern Unturned reads display strings from English.dat. Putting Name and Description only in the primary .dat may cause them not to display correctly on all platforms or game versions. Always author English.dat.

How Unturned resolves the prefab from the bundle

When Unturned loads an item asset, it needs to find the visual prefab in the master bundle. The resolution sequence is:

1. Read the Item field from the .dat. If present, use this string as the prefab lookup key.
2. If Item is absent, use the Name field as the prefab lookup key.
3. Open the master bundle file (.unity3d) associated with this asset folder.
4. Look up the prefab by the key from step 1 or 2.
5. If the prefab is found, instantiate it and cache the instance.
6. If the prefab is not found, log a console error. The item is registered in the asset registry but renders as invisible when equipped or dropped.

Prefab not found errors

If an item appears in the inventory after @give but is invisible when equipped, the most likely cause is a prefab name mismatch. The Item field in the .dat does not match the prefab name in the bundle. Open Unity, confirm the exact name of the prefab in the bundle, and update the Item field or the Name field accordingly.

A complete minimal item .dat example

The following is a complete, minimal .dat for a non-equippable supply item — a crafting component. It demonstrates every required shared field and the most common optional fields.

ID 50001
GUID a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6
Type Supply
Name CraftingCopperPlate

Rarity Common
Slot None
Size_X 1
Size_Y 1

Weight 0.2

Bypass_ID_Limit True
Should_Drop_On_Death True
Count_Min 1
Count_Max 3

Companion English.dat:

Name Copper Plate
Description A worked copper plate used in advanced crafting recipes.

A complete minimal equippable item .dat example

The following is a complete, minimal .dat for an equippable vest item. It demonstrates how Slot and Rarity interact for clothing.

ID 50002
GUID b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7
Type Vest
Name TacticalVest

Rarity Uncommon
Slot Vest
Size_X 2
Size_Y 2

Weight 1.2
Allow_Damage True
Durability 100
Wear 0.02
Should_Delete_At_Zero False

Bypass_ID_Limit True
Should_Drop_On_Death True

Note that the vest-specific fields (armor rating, movement penalty, warmth) are defined in the ItemVestAsset subclass and are documented in the clothing asset article, not here. The shared fields above apply to any vest regardless of its armor rating.

Field authoring checklist

Use this checklist when authoring a new item asset from scratch.

• [ ] ID is in the 50000+ range and does not conflict with other mods in the project.
• [ ] GUID was generated fresh with uuidgen or the cohort GUID tool; it does not appear in any other .dat in the project.
• [ ] Type matches the intended item gameplay behavior.
• [ ] Name is a valid prefab lookup key or the Item field explicitly names the prefab.
• [ ] Rarity reflects the intended tier for this item in the loot economy.
• [ ] Slot is correct for the item category.
• [ ] Size_X and Size_Y match the visual footprint of the item in the inventory grid.
• [ ] Bypass_ID_Limit True is present for all items with IDs above 2000.
• [ ] English.dat is authored in the same folder with both Name and Description.
• [ ] The master bundle (.unity3d) is present in the same folder.
• [ ] The bundle contains a prefab whose name matches the Item field or the Name field.

Visualizations

Visualization 1: item asset resolution flowchart

┌──────────────────────────────────────────────────────────┐
│  Item asset resolution — startup load sequence           │
└──────────────────────────────────────────────────────────┘

Engine scans bundle dirs
         │
         ▼
Finds Asset.dat or <name>.dat
         │
         ▼
    Reads Type field
         │
    ┌────┴────────────────────────────────┐
    │  Type known?                        │
    │  Yes → instantiate asset subclass   │
    │  No  → log error, skip asset        │
    └────┬────────────────────────────────┘
         │ Yes
         ▼
    Reads ID field
         │
    ┌────┴────────────────────────────┐
    │  ID already registered?         │
    │  Yes → overwrite (last wins)    │
    │  No  → new registry entry       │
    └────┬────────────────────────────┘
         │
         ▼
    Reads GUID field
         │
    Reads all remaining shared fields
         │
    Reads type-specific fields
         │
         ▼
  Asset registered and available

Visualization 2: Slot enum to inventory panel mapping

┌───────────────────────────────────────────────────────┐
│  Player inventory panel — Slot enum mapping           │
│                                                       │
│  ┌─────────────┐  ┌────────────────┐                  │
│  │  Hat        │  │  Glasses       │                  │
│  │  Slot.Hat   │  │  Slot.Glasses  │                  │
│  └─────────────┘  └────────────────┘                  │
│  ┌─────────────────────────────────┐                  │
│  │  Mask          Slot.Mask        │                  │
│  └─────────────────────────────────┘                  │
│  ┌─────────────────────────────────┐                  │
│  │  Shirt         Slot.Shirt       │                  │
│  └─────────────────────────────────┘                  │
│  ┌─────────────────────────────────┐                  │
│  │  Vest          Slot.Vest        │                  │
│  └─────────────────────────────────┘                  │
│  ┌─────────────────────────────────┐                  │
│  │  Pants         Slot.Pants       │                  │
│  └─────────────────────────────────┘                  │
│  ┌──────────┐   ┌──────────┐                          │
│  │ Primary  │   │Secondary │  ← Weapon slots          │
│  │Slot.Prim │   │Slot.Sec  │                          │
│  └──────────┘   └──────────┘                          │
│  ┌─────────────────────────────────┐                  │
│  │  Backpack      Slot.Backpack    │                  │
│  └─────────────────────────────────┘                  │
│                                                       │
│  Items with Slot.None remain in storage/hotbar only.  │
└───────────────────────────────────────────────────────┘

Visualization 3: Rarity tier visual reference

Rarity tier ladder (ascending)

Common     ──  White text   ──  Most food, tools, standard clothing
Uncommon   ──  Green text   ──  Mainstream firearms, functional armor
Rare       ──  Blue text    ──  High-tier firearms, specialized gear
Epic       ──  Purple text  ──  Exceptional firearms, set-completion armor
Legendary  ──  Gold text    ──  Endgame military hardware
Mythical   ──  Animated     ──  Economy cosmetics only; zero loot weight

Visualization 4: Size_X / Size_Y grid footprint examples

Inventory grid — Size_X (columns) × Size_Y (rows)

  1×1   ■           Pill bottle, small key
  2×1   ■ ■         Pistol magazine, compass
  4×1   ■ ■ ■ ■     Assault rifle, sniper rifle
  2×2   ■ ■         Medical kit, binoculars
        ■ ■
  2×3   ■ ■         Small backpack, vest with large storage
        ■ ■
        ■ ■
  3×3   ■ ■ ■       Medium backpack
        ■ ■ ■
        ■ ■ ■

Visualization 5: meta.dat vs Asset.dat — responsibilities

┌──────────────────────┬──────────────────────────────────┐
│  Asset.dat           │  meta.dat                        │
├──────────────────────┼──────────────────────────────────┤
│  Item gameplay data  │  Editor and economy metadata     │
│  ID, GUID, Type      │  Spawn table group               │
│  Rarity, Slot, Size  │  Economy bundle association      │
│  Damage, Weight      │  Map editor category             │
│  Useable behavior    │  Sandbox exclusion flag          │
├──────────────────────┼──────────────────────────────────┤
│  Read by: game       │  Read by: map editor, economy    │
│  runtime parser      │  system (not the item parser)    │
├──────────────────────┼──────────────────────────────────┤
│  Required for all    │  Optional; omit for most         │
│  item mods           │  Workshop mods                   │
└──────────────────────┴──────────────────────────────────┘

Visualization 6: field parse failure modes at a glance

Field missing (required)    → Asset fails to load. Console error logged.
Field missing (optional)    → Default value applied silently.
Field value wrong type      → Field ignored silently; default applied.
Enum value wrong case       → Enum not recognized; default applied.
Enum value not in list      → Enum not recognized; default applied.
Duplicate ID across mods    → Last loaded wins; earlier item unreachable.
Duplicate GUID across mods  → Conflict logged; behavior undefined.

Appendices

Appendix A: shared field quick-reference card

Copy this template into a new item's Asset.dat and fill in the values. Delete fields that are not relevant to your item type.

ID <50000+>
GUID <generated-uuid-no-hyphens>
Type <see Type enum reference>
Name <InternalName>

Rarity <Common|Uncommon|Rare|Epic|Legendary>
Slot <see Slot enum reference>
Size_X <1>
Size_Y <1>

Weight <0.0>
Allow_Damage <True|False>
Durability <100>
Wear <0.05>
Should_Delete_At_Zero <True|False>

Bypass_ID_Limit True
Should_Drop_On_Death True
Count_Min 1
Count_Max 1

Pro False

Appendix B: common parse errors and fixes

Symptom	Probable cause	Fix
Item does not appear after @give <ID>	ID or GUID conflict; Type field wrong; Bypass_ID_Limit missing for ID > 2000	Confirm ID is unique; confirm Bypass_ID_Limit True; check console for load errors
Item is invisible when equipped	Prefab lookup failure; Name or Item field does not match prefab name in bundle	Confirm prefab name in Unity matches Item or Name field in .dat
Item has wrong display name	English.dat missing or Name field in English.dat is wrong	Author English.dat in the same folder as Asset.dat
Item appears in wrong inventory slot	Slot field wrong	Correct Slot to the appropriate enum value
Item cannot be picked up	Slot set to an equip slot but no matching slot available	Use Slot None for non-equippable items
Item drops on death when it should not	Should_Drop_On_Death not set	Add Should_Drop_On_Death False
Item takes too many grid cells	Size_X or Size_Y too large	Reduce to match visual footprint
Item durability not depleting	Allow_Damage is False or not present for items that should degrade	Add Allow_Damage True and Wear <value>
Console logs "duplicate ID" warning	Two mods share the same numeric ID	Change one mod's ID to a non-conflicting value in the 50000+ range

Appendix C: external references

The following official and community references supplement this article.

Resource	URL	Notes
Smartly Dressed Games modding documentation	https://docs.smartlydressedgames.com/en/stable/	Official reference. Check here for fields added in recent Unturned updates that may postdate this article.
Unturned on Steam	https://store.steampowered.com/app/304930/Unturned/	The game's Steam store page; changelog notes often mention asset format changes.
Project Folder Structure and GUIDs	/items/project-folder-structure-and-guids	The prerequisite article covering folder layout and GUID generation.
Master Bundle Export	/items/master-bundle-export	The next article in this series; covers packaging the Unity prefab.

Frequently asked questions

What is the minimum set of fields required to load an item?

The minimum required fields are ID, GUID, and Type. Without these three fields, the asset either fails to load or fails to register correctly. Name is strongly recommended because it is used as the prefab lookup key when Item is absent, but it is not strictly required if Item is specified.

Do I need a GUID if my item has a valid numeric ID?

In legacy Unturned versions, GUIDs were optional. In modern Unturned (3.x and above), GUIDs are the stable cross-reference used by maps, spawn tables, and inter-mod references. A mod without a GUID can still function in practice, but the item cannot be reliably referenced by ID-independent systems (maps, spawn tables authored by other mods). The cohort recommendation is to always generate and include a GUID.

What happens if two of my own mod items share the same ID?

The last-loaded item with that ID overwrites the first in the registry. The first item becomes unreachable by numeric ID; players who had that first item in inventory may experience item replacement or loss on server restart. Always verify that all items in a mod project have unique IDs before publishing.

Can I use IDs below 2000?

IDs 1–2000 are used by vanilla Unturned items. Using an ID in that range will replace the corresponding vanilla item in the registry. This is almost never the desired behavior. The cohort recommendation is to use IDs in the 50000+ range. If you do use an ID below 2000, the Bypass_ID_Limit True field is not required (it is only required for IDs above 2000 in the legacy parser).

What does Size_Z do and do I need it?

Size_Z controls the depth of the item's world-space collision box when the item is dropped on the ground. For most items, omitting this field is correct — the engine uses the mesh bounds. Size_Z is useful for items whose mesh bounds do not accurately represent their pickup footprint (e.g., a flat item that sinks into terrain if its bounds are too thin).

Can the same item appear in multiple inventory slots?

No. The Slot field is a single enum value. An item occupies exactly one slot category. However, a player can equip the item in that one slot and also carry additional units of the same item in storage (backpack, vest pockets). If you need an item that functions differently in different contexts, the correct approach is to create separate item assets with different Slot values.

What is the difference between Useable and Type?

Type determines the asset subclass — it controls which additional .dat fields are read. Useable determines the gameplay script applied at runtime — it controls which Useable* MonoBehaviour is attached to the prefab in-game. For most item types, Type and Useable are the same value, and the Useable field can be omitted. They differ only for legacy compatibility cases or specialty items where the asset structure differs from the runtime behavior.

How do I make an item that is not droppable?

Set Should_Drop_On_Death False. Note that this prevents the item from being dropped on player death, but players can still manually drop the item from inventory unless further restrictions are applied via server-side plugin configuration. The .dat field alone does not prevent manual dropping.

What does Pro True actually do in practice?

Items with Pro True are restricted to players who own Unturned Gold (the PRO upgrade on Steam). Non-PRO players can see and pick up PRO items but cannot equip them; the equip action is blocked at runtime. The cohort recommendation for Workshop mods is to leave Pro False unless the mod is explicitly designed for PRO-only servers, because restricting items to PRO players significantly reduces the addressable player base for the mod.

Can I add fields that Unturned does not recognize?

Yes, and they are silently ignored. Adding documentation comments (lines starting with //) or custom metadata fields to the .dat is harmless — the parser skips unknown keys without error. Some modders use this for version tracking or authoring notes embedded directly in the .dat.

How does Unturned handle a missing English.dat?

If English.dat is absent, the item uses the Name field from the primary .dat as the display name and has an empty description. The item is functional but its tooltip will show only the internal name, which is typically not user-friendly. Always author English.dat for any item that players will encounter.

Does the order of fields in the .dat file matter?

No. Unturned's parser reads all fields regardless of order. The cohort convention is to group related fields (identity fields together, inventory fields together, gameplay fields together) for readability, but the engine does not enforce any ordering.

What is the maximum value for Size_X and Size_Y?

The inventory grid in Unturned is 10 columns wide (for most storage types). Items with Size_X 10 fill the full width of the inventory. Items with Size_X greater than the storage container's width cannot be placed in that container. In practice, the cohort recommendation is to cap Size_X at 6 and Size_Y at 4 for Workshop items, as very large items are difficult for players to fit into standard containers.

Advanced authoring patterns

Authoring non-equippable crafting components

Many mod projects include crafting components — raw materials, intermediate parts, and manufactured components — that players collect and combine at a crafting station. These items use Slot None and are stored in inventory without occupying an equipment slot. The primary authoring concern for crafting components is inventory footprint: items that stack (multiple units of the same ID in one cell) should have Size_X 1, Size_Y 1 to maximize storage density.

Crafting component example field set:

ID 50050
GUID e1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6
Type Supply
Name CopperWire

Rarity Common
Slot None
Size_X 1
Size_Y 1
Weight 0.05

Bypass_ID_Limit True
Should_Drop_On_Death True
Count_Min 1
Count_Max 5

The Count_Min and Count_Max fields control how many units of this item spawn when a loot table generates it. A crafting component with Count_Max 5 may grant up to five units in a single loot event, improving the player's material acquisition rate without requiring multiple loot rolls.

Authoring durability-based consumable items

Some items are designed to degrade with use and eventually break. Medical kits, repair tools, and reusable utility items typically follow this pattern. The key fields are Allow_Damage True, Durability, Wear, and Should_Delete_At_Zero.

Durable repair tool example:

ID 50051
GUID f2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7
Type Tool
Name RepairKit

Rarity Uncommon
Slot None
Size_X 2
Size_Y 1

Weight 0.8
Allow_Damage True
Durability 100
Wear 0.1
Should_Delete_At_Zero True

Bypass_ID_Limit True

With Wear 0.1 and Durability 100, this item has ten uses before its durability reaches zero (each use consumes 10 durability points). Should_Delete_At_Zero True destroys the item when fully depleted, requiring the player to find or craft a replacement.

Authoring items with inventory stacking

Unturned's item system supports stacking — multiple units of the same item ID sharing a single inventory cell. Stacking is controlled by the game's item registry and is not directly authored in the .dat file. However, items with Size_X 1, Size_Y 1 and Slot None are the candidates that the engine considers for stacking. Items with larger footprints do not stack. The practical implication for modders is that small consumable items (ammo, food, medicine) should use the minimum 1×1 footprint to allow stacking, while large items (weapons, backpacks) use a larger footprint that prevents stacking.

Authoring items for specific loot table groups

When a mod item needs to appear in a specific loot table (e.g., military crates, forest spawns, hospital loot), the relevant configuration lives in the spawn table .dat files — not in the item asset .dat. The item asset needs only a valid ID and GUID. The spawn table references the item by ID. The cohort recommendation is to maintain a separate spawn table configuration document per mod that maps item IDs to their intended loot tables and weights.

GUID generation workflow

Every new item asset requires a fresh GUID. The cohort workflow for 57 Studios™ mods is:

1. Open PowerShell.
2. Run: [guid]::NewGuid().ToString("N") to generate a GUID without hyphens (the format Unturned expects).
3. Copy the output.
4. Paste into the GUID field of the new item's Asset.dat.
5. Verify the GUID does not appear in any other .dat file in the project (search the project folder with grep -r <guid>).

Never reuse a GUID from a previously deleted item. Deleted item GUIDs should be tracked in the project's GUID registry document to prevent accidental reuse on a future item.

Working with the Bypass_ID_Limit field

The Bypass_ID_Limit True field is required for all items with numeric IDs above 2000 in the legacy Unturned parser. Without it, the legacy parser may reject the item or log a warning. As of modern Unturned 3.x, the limit enforcement is softer than in legacy builds, but the cohort practice is to include Bypass_ID_Limit True on every Workshop mod item as a defensive measure.

Items with IDs 1–2000 do not need Bypass_ID_Limit True. However, using IDs in that range replaces vanilla items in the registry, which is almost never the correct behavior for a Workshop mod.

Item asset versioning and mod compatibility

When publishing a mod to the Steam Workshop and subsequently updating it, the GUID is the stable cross-reference that other mods, maps, and spawn tables use to reference your items. The numeric ID can theoretically be changed without breaking GUID-based references, but changing the ID breaks any console commands, legacy spawn tables, or older server plugins that reference the item by numeric ID.

The cohort recommendation for maintaining backward compatibility across mod updates:

Action	Impact	Recommendation
Change Name field	Visual only; no gameplay impact if Item field is explicit	Safe to change
Change Rarity	Changes UI color; no gameplay impact	Safe to change
Change Slot	Changes equipped behavior; may break existing player inventories	Change with caution
Change ID	Breaks numeric-ID references (console commands, legacy tables)	Avoid; use new ID for new item
Change GUID	Breaks all GUID-based references; maps, spawn tables, other mods	Never change after publishing
Add new field	Additive; existing saves unaffected	Safe
Remove field	Defaults applied; may change gameplay	Change with caution

The GUID is permanent once a mod is published. Changing a GUID on a published mod effectively creates a new item that is incompatible with any map or spawn table that referenced the old GUID. If a breaking change is required, the cohort recommendation is to create a new item asset with a new GUID and to retire the old asset by removing it from loot tables.

Item asset relationships in multi-item mods

A mod that ships multiple items — a gun, its magazines, its attachment options, and supporting crafting components — must manage the relationships between those assets carefully. The shared fields that create those relationships are:

• Caliber linkage — the gun's Caliber field and each magazine's Caliber_Reference field must carry a matching value. Documented fully in Magazine Asset.
• Attachment slot linkage — the gun declares which attachment types it accepts; each attachment asset declares its slot type. The linkage is by slot type enum, not by numeric ID.
• Spawn table linkage — spawn tables reference items by numeric ID. If an item ID changes between mod versions, spawn tables must be updated to match.
• GUID-based cross-references — maps and other mods reference items by GUID, not by numeric ID. GUIDs must be stable across mod versions.

The cohort recommendation for multi-item mods is to maintain a project manifest document (a simple .md or .txt file in the project root) that lists every item in the mod with its ID, GUID, type, and relationships. This manifest makes cross-reference errors visible at a glance and serves as the source of truth when debugging caliber mismatches or attachment incompatibilities.

Example project manifest entry format:

Item: Scout Carbine
  ID:   50100
  GUID: a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6
  Type: Gun
  Caliber: 5010
  Magazines: 50110 (10-rd box), 50111 (20-rd box), 50112 (30-rd box), 50113 (60-rd drum)
  Attachments: 50120 (scope), 50121 (suppressor), 50122 (foregrip)

Item: 20-Round Box Magazine
  ID:   50111
  GUID: b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7
  Type: Magazine
  Caliber_Reference: 5010
  Amount: 20

This format makes it immediately clear which items belong together and which caliber IDs connect them.

Testing shared field changes in single-player

After authoring or modifying shared fields in a .dat file, the cohort workflow for verifying the change in single-player is:

1. Copy the updated .dat file to the mod folder in the local Unturned install.
2. Launch Unturned in single-player.
3. Open the in-game console with ~.
4. Spawn the item: @give <itemID>.
5. Verify the item appears in inventory with the correct Size_X / Size_Y footprint.
6. Verify the item's display name and description match English.dat.
7. Verify the item's rarity color in the inventory tooltip matches the Rarity field.
8. For equippable items: drag the item to the expected equipment slot. Confirm it accepts the slot.
9. For clothing: equip the item and confirm it renders on the player model.
10. For weapons: proceed to the weapon-specific testing steps in Gun Mod Tutorial.

If the item does not appear after @give, check the console for asset load errors. The most common load errors are:

• Failed to parse asset: <path> — a required field is missing or malformed.
• Duplicate ID: <id> — the ID conflicts with another loaded asset.
• Unknown type: <value> — the Type field value is not recognized.

Document history

Version	Date	Author	Notes
1.0	2025-05-18	57 Studios	Initial publication. Complete shared field reference, Rarity and Slot enums, parse sequence, meta.dat relationship, advanced authoring patterns, versioning guidance.

Frequently asked questions about the parse sequence

In what order does Unturned load content directories?

Unturned loads content in the following priority order, from lowest to highest (higher priority overrides lower for duplicate IDs):

1. Vanilla game content (bundled with the game install).
2. Local Workshop content (downloaded from the Steam Workshop to the client).
3. Server-side Workshop content (loaded from the server's Workshop directory on join).

Items loaded later in this sequence with the same numeric ID replace earlier items in the registry. This means a server-side mod can intentionally override a vanilla item's fields by giving a mod item the same ID as the vanilla item. This technique is occasionally used for server balance patches but carries the risk of desync if the client does not have the same override loaded.

What is the recommended workflow for verifying all items in a mod loaded correctly?

Open the Unturned in-game console with ~ after loading a server or single-player session. The console logs asset load errors. Scroll through the log or filter for errors related to the mod's item IDs. A clean load produces no asset parse errors. Any Failed to parse or Duplicate ID entries require investigation.

For large mods with many items, the cohort recommendation is to author a test script that spawns every item in the mod via @give commands and verifies each appears in inventory. This script can be run as a startup routine on a local test server.

Can I change a field in a published mod's .dat without breaking existing player saves?

Most field changes are safe for existing player saves because item saves store the item's ID (and sometimes GUID), not the full field set. When the player reconnects after the mod update, the engine reads the updated .dat and applies the new field values to the existing item instance. Exceptions:

• Changing Slot may cause an item to fail to re-equip in the slot it was in at save time.
• Changing Size_X or Size_Y to a larger value may cause the item to not fit in the container it was saved in.
• Deleting an item asset entirely causes existing instances to become invalid; the engine typically drops the item on next load.

For safety, always test mod updates on a test server with a player save file before publishing to production.

How do I add a new item asset type that the engine does not natively support?

The Unturned engine's native item asset types are the values in the Type enum reference above. There is no mechanism for a Workshop mod to register a new Type value — that requires modifying the game's source code, which is outside the Workshop modding scope. Workshop mods are limited to the native Type values. The closest available approach for a novel item concept is to select the native Type that most closely matches the intended behavior and to configure the type-specific fields to approximate the desired gameplay, combined with server-side plugin code (where the server allows plugins) to add behavior that the native type does not support.

The cohort recommendation for novel item concepts that do not fit neatly into the native Type list is to prototype using the nearest native Type and to document the approximation clearly in the mod's Workshop description so that players understand what behavior the item has and what it does not have.

Glossary of terms used in this article

Term	Definition
Asset	A configuration object that defines an in-game entity. In Unturned, items are assets.
.dat file	A plain-text key-value file used by Unturned to define asset properties.
GUID	Globally Unique Identifier. A 128-bit value generated to uniquely identify an asset across all mods and all time. Never repeat or reuse a GUID.
Enum	An enumerated type; a field that accepts one of a fixed set of named string values.
uint8	An unsigned 8-bit integer. Valid range: 0–255.
uint16	An unsigned 16-bit integer. Valid range: 0–65535.
uint32	An unsigned 32-bit integer. Valid range: 0–4,294,967,295.
float	A 32-bit floating-point number. Uses a period (.) as the decimal separator.
bool	A boolean value. Valid values: True or False (capitalized).
Prefab	A Unity asset that defines a reusable scene-graph template. The in-game 3D model of an item.
Master bundle	A Unity .unity3d archive file that contains one or more prefabs and their dependencies.
Spawn table	A configuration file that defines the probability weights for items appearing as loot in a specific zone or container.
Caliber	A numeric ID used to link guns and magazines that are compatible with each other.
Subclass	An asset type that extends the shared item asset with type-specific fields. Determined by the Type field.
Texel density	The ratio of texture resolution to mesh surface area. Higher texel density means more texture detail per unit of surface area.
NLA track	Non-Linear Animation track in Blender. Used to push individual animation actions into a sequence that the FBX exporter captures as separate clips.
Loot table	A configuration that maps items to spawn probability weights. Separate from item .dat files; controls where and how often items appear in the world.
Workshop	The Steam Workshop; the platform through which Unturned mods are published and subscribed to by players. Accessible at the Unturned Steam store page.

Cross-references

• Project Folder Structure and GUIDs — prerequisite article covering folder layout and GUID generation workflow.
• Master Bundle Export — next article; Unity prefab packaging workflow.
• Gun Mod Tutorial — the gun item type, which extends the shared fields documented here with gun-specific fields.
• Magazine Asset — the magazine item type reference.
• Smartly Dressed Games Modding Documentation — official modding documentation; authoritative for fields added in recent game updates.
• Unturned on Steam — the game's Steam page; changelog notes sometimes reference asset format changes.