Asset Definitions Reference ​

Intermediate40-60 minutesWindowsNotepad++Unity Editor

An asset definition is the bridge between a .dat configuration file and a Unity AssetBundle. Every item, vehicle, animal, object, and effect in Unturned™ is represented by an asset definition, a .dat or .asset file that carries the asset's identity (GUID and Type), its body properties (the fields that define its behavior), and the metadata that links it to the Unity bundle containing its 3D model and textures. A modder who understands asset definitions completely can trace every asset from its .dat file through to its in-game appearance; a modder who does not will encounter "invisible item" bugs, GUID collision failures, and master bundle resolution errors that a definitions reference would prevent.

This article is the 57 Studios™ canonical reference for asset definitions. It documents the GUID and Type header that every asset carries, the two structural formats (Format A with Metadata and Asset blocks, and Format B with a simple root-level identity), the master bundle linkage fields, the asset loading order the game follows, the inheritance hierarchy that determines which fields an asset type recognizes, and the redirector asset type that remaps asset references. The reference is built from the official Smartly Dressed Games documentation and validated against the shipped .asset and .dat files in the Unturned™ Bundles directory.

Asset definition file structure diagram showing the GUID, Type, and body fields

Documentation source: This article references the official Smartly Dressed Games modding documentation for the asset definitions specification. Game-file evidence was sampled from the Unturned™ Bundles/Items/ and Bundles/Assets/ directories.

Who this article is for ​

This article is written for Unturned™ mod authors who have already read the Data File Format Reference and understand the .dat syntax grammar. It presupposes familiarity with GUID generation and the master bundle export workflow. If you are new to Unturned™ modding, start with Project Folder Structure and GUIDs and Master Bundle Export from Unity before returning here.

What you'll learn ​

  • What an asset definition is and how it bridges .dat configuration data to Unity AssetBundle content
  • The GUID property: its format, its role in linking assets together, and the auto-generation behavior
  • The Type property: how the type string determines which C# class reads the asset's fields
  • The ID property: the legacy numeric identifier and its uniqueness constraint
  • The two structural formats of .asset files, Format A with Metadata and Asset blocks, and Format B with root-level identity
  • When each format is used and which asset types default to which format
  • The master bundle linkage fields that control which .unity3d or .masterbundle file the asset loads from
  • The asset loading order: how the game decides which file in a folder defines an asset
  • The inheritance hierarchy: how asset types form a class tree and which fields are inherited
  • Editor Asset Redirectors: the special .asset files that remap GUID and legacy ID references
  • Worked examples of both formats from shipped game files

Background: what an asset definition is ​

An asset definition is a structured text file that associates game data with Unity content. The definition contains two categories of information: identity data (the GUID, Type, and optionally the ID) that tells the game engine what this asset is and how to reference it, and body data (the key-value fields specific to the asset type) that defines the asset's behavior at runtime. The definition also contains bundle-linkage data, fields that tell the game which Unity AssetBundle contains the prefab, texture, mesh, or audio clip that the asset uses for its visual and audible representation.

The asset definition does not contain the 3D model, texture, or audio data itself. Those binary assets reside inside Unity AssetBundles (.unity3d or .masterbundle files). The asset definition tells the game which bundle to load, which path within that bundle to find the prefab at, and which version of Unity the bundle was built for. This separation, text definition file plus binary bundle file, means the modder can edit the text configuration without rebuilding the bundle, and can rebuild the bundle without editing the text configuration, as long as the identity fields (GUID, Type, Name) remain consistent.

As shown in the flowchart above, the asset definition and the binary bundle are separate inputs to the game engine. The engine reads the definition to understand what the asset is and how it behaves, then loads the binary content from the bundle to render the asset visually in the game world.

The GUID property ​

The GUID field is a 128-bit globally unique identifier written as a 32-character lowercase hexadecimal string with no hyphens. Every asset in Unturned™, every item, vehicle, animal, object, resource, effect, and NPC, has a unique GUID. The GUID is the primary mechanism by which assets reference each other: a gun's Magazine field contains the ID (not the GUID) of the magazine asset, but a blueprint's CategoryTag field contains the GUID of the tag asset. Cross-references between asset types use GUIDs; within-type references (gun to magazine) use IDs.

Evidence from shipped files: every .dat and .asset file in the Bundles directory begins with a GUID line. The format is consistent across every file inspected:

GUID 92b49222958d4c6fbeca1bd00987b0fd
GUID characteristicRuleNotes
LengthExactly 32 charactersNo exceptions in shipped files
Character set0-9, a-f (lowercase)Uppercase is parsed identically but never used in vanilla
SeparatorsNoneNo hyphens, no braces, no spaces
GenerationUUID v4 (random)Generated by tools; hyphens removed before writing
UniquenessMust be globally unique across all modsDuplicate GUIDs cause assets to overwrite each other
Auto-generationIf left empty, the game prepends a random GUID at startupOnly when GUID is in the root dictionary, not in Metadata block

GUID placement ​

The GUID field can appear in the root dictionary or in a Metadata sub-dictionary. Both placements are valid and produce identical behavior, with one important difference:

  • Root dictionary: If the GUID field is empty (e.g., GUID on its own line with no value), the game automatically generates a random GUID during startup. This is the standard placement for items, vehicles, and most asset types.
  • Metadata sub-dictionary: If the GUID field is inside a Metadata block, the game does not auto-generate a new GUID when the field is empty (as of the 2023-04-13 parser update). The asset will load with an empty GUID, which will cause reference-resolution failures.

Common mistake

Placing the GUID field inside a Metadata block and leaving it empty, expecting the game to auto-generate it. The auto-generation only triggers when the GUID is specified in the root dictionary. If you are using the Metadata block structure, always provide an explicit GUID value.

The Type property ​

The Type field is a string that tells the game which C# class to use when reading the asset's body fields. The type string determines the entire set of fields the asset recognizes, fields whose names match properties on the type's class are read; fields whose names do not match any property are silently discarded. The type string also determines the asset's inheritance chain: a Type Gun asset inherits from the ItemAsset class, which inherits from the Asset base class, and the properties from every class in the chain are available.

Evidence from shipped files shows a wide variety of type strings:

  • Type Melee, melee weapon assets
  • Type Gun, ranged weapon assets
  • Type Magazine, ammunition container assets
  • Type Mask, wearable mask and headgear assets
  • Type Tag, blueprint category and crafting tags
  • Type SDG.Unturned.AirdropAsset, Assembly-CSharp, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null, fully qualified type reference
Type specificationFormatUse case
Short nameType MeleeStandard for built-in asset types (Melee, Gun, Magazine, Item, Vehicle, Animal, etc.)
Fully qualified nameType Namespace.ClassName, AssemblyUsed for custom or less-common asset types that do not have a short-name alias

The fully qualified name format includes the namespace, class name, and assembly reference. This format is used when the short-name alias is not available (either because the asset type is not one of the built-in types with a registered alias, or because the modder is referencing a type from a specific assembly). The assembly reference includes the version, culture, and public key token, matching the standard .NET assembly-qualified name format.

The ID property ​

The ID field is a uint16 numeric identifier (range 0 to 65,535). Unlike the GUID, which is globally unique across the entire asset system, the ID is unique only within the asset's category. The game enforces that no two items share the same ID, no two vehicles share the same ID, and so on, but an item and a vehicle can share the same ID because they are in different categories. Objects are the exception from this legacy restriction because they have been upgraded to fully use GUIDs.

The ID serves two purposes: it is the value used in console commands (@give 107 spawns the item with ID 107), and it is the value used for within-category cross-references (a gun's Magazine 108 field references the magazine with ID 108). Modders should assign IDs in the 50,000+ range to avoid collision with vanilla items and with established community mods.

ID characteristicRuleRecommendation
Typeuint16 (0 to 65,535)Whole-number integer; no decimal
Uniqueness scopePer category (items, vehicles, animals)No two items can share an ID
Vanilla range1 through approximately 2,000Avoid using IDs below 50,000
Mod range50,000+Assign from a documented range per mod project
Cross-reference useReferenced by other assets via IDGun references magazine by ID, not GUID

Asset type inheritance hierarchy ​

The asset type system in Unturned™ is organized as a C# class hierarchy. Every asset type inherits from a base Asset class, and specialized types inherit from intermediate classes that add category-specific fields. The modder does not need to understand the full inheritance tree to author .dat files, but understanding which fields come from which level of the hierarchy helps explain why certain fields appear on certain asset types and not on others.

As shown in the diagram above, the ItemAsset class is the intermediate base class for every item type. Fields defined on ItemAsset, such as ID, Size_X, Size_Y, Rarity, and Slot, are available on every item subclass. Fields defined on ItemGunAsset, such as Caliber, Firerate, and Recoil, are available only on gun assets. A magazine asset shares the ItemAsset fields with a gun asset but does not have the Caliber field (the magazine has Caliber_Reference instead, which is a different field on a different class).

Format A: the structured definition ​

Format A is the standard asset definition structure used by most item and object .dat and .asset files. It is characterized by having the GUID and Type fields at the root level (or inside a Metadata block), with the body fields optionally organized inside an Asset sub-dictionary.

Root-level Format A ​

In the most common variant, the GUID, Type, and body fields are all at the root level of the dictionary. This is the format used by every vanilla item .dat file:

GUID 92b49222958d4c6fbeca1bd00987b0fd
Type Gun
Rarity Uncommon
Useable Gun
Slot Secondary
ID 107

Size_X 2
Size_Y 2
Size_Z 0.35

Magazine 108

Hook_Barrel

Safety
Semi

Caliber 6

Range 100
Firerate 10
Action Trigger

Player_Damage 50
Zombie_Damage 99
Durability 0.08

This variant places all fields in the root dictionary. The parser treats the root level as the implicit dictionary, and the C# asset class reads the fields directly from that dictionary. There is no Metadata or Asset block.

Metadata-and-Asset Format A ​

An alternative variant places the identity fields in a Metadata sub-dictionary and the body fields in an Asset sub-dictionary:

Metadata
{
    GUID 229440c249dc490ba26ce71e8a59d5c6
    Type SDG.Unturned.AirdropAsset, Assembly-CSharp, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null
}
Asset
{
    Landed_Barricade
    {
        GUID fe71781c60314468b22c6b0642a51cd9
    }
    Carepackage_Prefab
    {
        MasterBundle core.masterbundle
        AssetPath Level/Carepackage.prefab
    }
}

This variant is used by assets that benefit from explicit structural separation between identity fields and body fields, or by assets whose type is specified as a fully qualified assembly name. As documented in the SDG specification, the Metadata block and root-level placement are functionally equivalent, the parser resolves both to the same internal representation.

Evidence from DefaultAirdrop.asset in the Bundles/Assets/Airdrops/ directory confirms this variant is used in shipped files.

Format A: master bundle linkage fields ​

Format A assets can include any of the following bundle-linkage fields, which control how the game resolves the asset's Unity content:

FieldTypePurposeExample
Master_Bundle_OverridestringName of a master bundle to use instead of the hierarchy-located bundleMaster_Bundle_Override core.masterbundle
Exclude_From_Master_BundleflagIf present, the asset looks for an individual .unity3d bundle instead of a master bundleExclude_From_Master_Bundle
Bundle_Override_PathstringPath within the master bundle to load, overriding the default path derived from the file locationBundle_Override_Path /Objects/Medium/Furniture/Note
Bundle_Path_Include_FilenameboolIf true, the path within the master bundle appends the asset file name as a subdirectoryBundle_Path_Include_Filename true
Asset_Bundle_VersionintUnity version indicator for the .unity3d bundleAsset_Bundle_Version 6

Format A: Asset_Bundle_Version values ​

ValueUnity versionNotes
1Unity 5.5Earliest supported version
2Unity 2017.4 LTS
3Unity 2018.4 LTS / 2019.4 LTS
4Unity 2020 LTS
5Unity 2021 LTS
6Unity 2022 LTSLatest as of the current Unturned™ release

When Unturned™ upgrades Unity versions, it attempts to maintain backward compatibility based on this number. Mods built against older Unity versions may continue to function after a game update if the version number is correct.

Format B: the simple definition ​

Format B is the minimal asset definition structure. It consists of a GUID line and a Type line at the root level, with no Metadata or Asset sub-dictionaries, and typically no master bundle linkage fields. Format B is used for assets that do not require a bundle, their identity alone is the entire asset definition, or their content is resolved through other means (the file system hierarchy, a .dat companion file, or a default prefab).

Evidence from shipped files: the BlueprintCategoryTag_Ammo.asset file in Bundles/Assets/Tags/BlueprintCategory/Ammo/ uses Format B:

GUID d739926736374e5ba34b4ac6ffbb5c8f
Type Tag

HasIcon true
IconPath UI/BlueprintCategoryTagIcons/Ammo.png

The GUID and Type are at the root level. There is no Metadata block, no Asset block, and no bundle-linkage fields. The body fields (HasIcon, IconPath) are also at the root level, after the identity fields. This file is a complete and valid asset definition.

When to use Format B ​

Format B is used by asset types that are self-contained, their definition does not need to reference a 3D model prefab, a texture, or any other binary content from a Unity bundle. The following asset types consistently use Format B across the vanilla installation:

Asset typeDirectoryEvidence
Blueprint category tagsBundles/Assets/Tags/BlueprintCategory/All tag .asset files use Format B
Crafting tagsBundles/Assets/Tags/Crafting/Same pattern as blueprint tags
Miscellaneous tagsBundles/Assets/Tags/Misc/Same pattern
Editor redirectorsEditor/Redirectors/ (in Unity project, not in game Bundles)Same pattern per SDG documentation

Did you know?

Format B .asset files are structurally identical to root-level Format A .asset files except for the absence of bundle-linkage fields. The distinction between the two formats is a convention (based on what the asset type requires) rather than a syntactic requirement. A Format B file can include bundle-linkage fields if needed; the format label describes typical usage, not a hard parser constraint.

Asset loading order ​

When the game scans a folder for assets, it checks for definition files in a specific priority order. Understanding this order is essential for diagnosing "asset not found" bugs and for planning the file structure of a mod project.

The loading order, highest priority first:

  1. A .asset file with the same name as the folder. If the folder is Eaglefire/ and the folder contains Eaglefire.asset, that file is loaded as the asset definition.
  2. A .dat file with the same name as the folder. If the folder is Eaglefire/ and the folder contains Eaglefire.dat (but no Eaglefire.asset), that file is loaded.
  3. An Asset.dat file. If no same-name .asset or .dat file exists, the game looks for Asset.dat in the folder.
  4. Otherwise, load all .asset files in the folder. Every .asset file in the folder is loaded as a separate asset definition. This is the catch-all behavior for folders that contain multiple independent asset definitions.
PriorityFile checkedExample pathWhen used
1<FolderName>.assetEaglefire/Eaglefire.assetWhen the folder and file share a name
2<FolderName>.datEaglefire/Eaglefire.datWhen no same-name .asset exists
3Asset.datEaglefire/Asset.datGeneric fallback for single-asset folders
4All *.asset filesTags/BlueprintCategory/TagA.asset, TagB.assetFor multi-asset definition folders

Pro tip

Most item mods use priority 2, a .dat file with the same name as the folder. The Melee/Axe_Camp/Axe_Camp.dat file and the Guns/Ace/Ace.dat file both follow this pattern. The Asset.dat fallback (priority 3) is used by mods that follow the Asset.dat convention in their folder structure.

Master bundle resolution chain ​

The master bundle resolution chain determines which .masterbundle or .unity3d file the game loads for a given asset. The chain resolves in the following order:

As shown in the flowchart above, the master bundle is the preferred content source for most asset types. Individual .unity3d bundles are the fallback for legacy assets and for assets that explicitly opt out of the master bundle system via the Exclude_From_Master_Bundle flag.

The master bundle hierarchy search works upward from the asset's directory. Starting at the asset's folder, the game checks for a MasterBundle.dat file. If none is found, it moves up to the parent directory and checks again. This continues until a MasterBundle.dat is found or the root of the Bundles/ directory is reached. The first MasterBundle.dat found in this upward search is the one used, this is the "nearest master bundle in the file hierarchy" rule.

Editor Asset Redirectors ​

A redirector asset is a special asset type that remaps asset references. When an asset reference (GUID or legacy ID) points to a redirector, the asset system returns the asset pointed to by the redirector's TargetAsset field instead of the redirector itself. Redirectors are used primarily during level editing in the Unity Editor; they allow a level designer to change which asset a placed object refers to without modifying every instance of that object in the level.

Redirector .asset structure ​

A redirector is a Format B .asset file with Type Redirector (or a fully qualified redirector type name). The body fields define the redirector's behavior:

FieldTypeRequiredPurpose
AssetCategoryenumNoIf set, the redirector also remaps legacy ID references within the specified category (e.g., AssetCategory Item means @give 4 resolves through this redirector)
TargetAssetGUIDYesThe GUID of the actual asset to return when an asset reference points to this redirector

Redirector behavior notes ​

Most features in Unturned™ save the original asset reference, not the resolved asset. When a level is saved after a redirector remapped some object references, the original redirector GUIDs, not the resolved target GUIDs, are written to the save file. This means the redirector must remain present and valid for the level to load correctly; removing the redirector after saving a level will cause the level's references to point to a nonexistent asset.

Redirectors are used exclusively in the Unity Editor workflow for level design and are not typically authored by modders creating item or vehicle mods. They are documented here for completeness and because they appear as .asset files in the Editor/Redirectors/ directory of a Unity project that includes Unturned™'s modding tools.

Worked examples from shipped files ​

Example 1: Format A, root-level style (Ace.dat) ​

The Ace pistol demonstrates the most common Format A variant used for item assets. All fields, identity and body, are at the root dictionary level:

GUID 92b49222958d4c6fbeca1bd00987b0fd
Type Gun
Rarity Uncommon
Useable Gun
Slot Secondary
ID 107

Size_X 2
Size_Y 2
Size_Z 0.35
Size2_Z 0.35

Magazine 108

Hook_Barrel

Ammo_Min 2
Ammo_Max 6

Safety
Semi

Caliber 6

Range 100
Firerate 10
Action Trigger

Player_Damage 50
Player_Leg_Multiplier 0.6
Player_Arm_Multiplier 0.6
Player_Spine_Multiplier 0.8
Player_Skull_Multiplier 1.1

Zombie_Damage 99
Zombie_Leg_Multiplier 0.3
Zombie_Arm_Multiplier 0.3
Zombie_Spine_Multiplier 0.6
Zombie_Skull_Multiplier 1.1

Animal_Damage 50
Animal_Leg_Multiplier 0.6
Animal_Spine_Multiplier 0.8
Animal_Skull_Multiplier 1.1

Barricade_Damage 25
Structure_Damage 20
Vehicle_Damage 30
Resource_Damage 20
Object_Damage 25

Durability 0.08

Aim_In_Duration 0.15
Spread_Aim 0.05
Spread_Angle_Degrees 5.71

Recoil_Min_X -4
Recoil_Min_Y 15
Recoil_Max_X -8
Recoil_Max_Y 20

Recover_X 0.5
Recover_Y 0.5

Shake_Min_X -0.01
Shake_Min_Y 0.01
Shake_Min_Z -0.1
Shake_Max_X 0.01
Shake_Max_Y -0.01
Shake_Max_Z -0.15

Muzzle 3

Blueprints
[
    {
        Name Repair
        CategoryTag "732ee6ffeb18418985cf4f9fde33dd11" // Repair
        Operation RepairTargetItem
        InputItems
        [
            {
                ID "21ede8ebffb14c5580e8c7ad149e335e" // Metal Scrap
                Amount 3
            }
            {
                ID "5830b84bf8074caa91cf3f4dde0dd19e" // Blowtorch
                Delete false
            }
        ]
        RequiresNearbyCraftingTags
        [
            "7b82c125a5a54984b8bb26576b59e977" // Workbench
        ]
        Effect "84347b13028340b8976033c08675d458" // Wrench
    }
    {
        Name Salvage
        CategoryTag "7ed29f9101ae4523a3b2e389414b7bd9" // Salvage
        InputItems this
        OutputItems "21ede8ebffb14c5580e8c7ad149e335e x 2" // Metal Scrap
        Effect "84347b13028340b8976033c08675d458" // Wrench
    }
]

This Format A root-level file demonstrates: the identity block (GUID, Type, ID), inherited ItemAsset fields (Size_X, Size_Y, Rarity), gun-specific fields (Caliber, Firerate, Recoil), cross-reference by ID (Magazine 108), presence flags (Safety, Semi, Hook_Barrel), and a deeply nested Blueprints array.

Example 2: Format A, Metadata-and-Asset style (DefaultAirdrop.asset) ​

The default airdrop definition demonstrates the Metadata and Asset block variant:

Metadata
{
    GUID 229440c249dc490ba26ce71e8a59d5c6
    Type SDG.Unturned.AirdropAsset, Assembly-CSharp, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null
}
Asset
{
    Landed_Barricade
    {
        GUID fe71781c60314468b22c6b0642a51cd9
    }
    Carepackage_Prefab
    {
        MasterBundle core.masterbundle
        AssetPath Level/Carepackage.prefab
    }
}

This Format A variant demonstrates: the Metadata block containing the identity fields, the fully qualified Type string, the Asset block containing body fields, nested dictionaries (Landed_Barricade, Carepackage_Prefab), and bundle-path specification (MasterBundle, AssetPath).

Example 3: Format B, simple tag definition (BlueprintCategoryTag_Repair.asset) ​

The repair blueprint category tag demonstrates Format B:

GUID 732ee6ffeb18418985cf4f9fde33dd11
Type Tag

HasIcon true
IconPath UI/BlueprintCategoryTagIcons/Repair.png

This Format B file demonstrates: the minimal identity block (GUID and Type at root level), no Metadata or Asset blocks, simple body fields (HasIcon, IconPath), and no bundle-linkage fields (the tag has no 3D model and does not need a bundle).

Complete asset definition field reference ​

FieldTypeFormatRequiredPurpose
GUID32-char hex stringBothYesGlobally unique identifier for the asset
TypestringBothYesDetermines which C# class reads the asset's fields
IDuint16Format AYes (items)Legacy numeric identifier; unique per category
Master_Bundle_OverridestringFormat ANoName of a specific master bundle to use
Exclude_From_Master_BundleflagFormat ANoIf present, use individual .unity3d bundle instead of master bundle
Bundle_Override_PathstringFormat ANoPath within the master bundle to load content from
Bundle_Path_Include_FilenameboolFormat ANoIf true, appends asset file name as subdirectory in bundle path
Asset_Bundle_VersionintFormat ANoUnity version indicator for the bundle
AssetCategoryenumRedirectorNoCategory for legacy ID redirector remapping
TargetAssetGUIDRedirectorYesGUID of the actual asset the redirector points to

Frequently asked questions ​

What is the difference between a .dat file and an .asset file? ​

The file extension signals a historical distinction. Before the 3.23.6.0 update, .dat files and .asset files used different syntax versions ("v1" and "v2"). After that update, both extensions use the same syntax grammar documented in the Data File Format Reference. In current Unturned™ versions, the choice between .dat and .asset is a matter of convention and loading-order priority: a same-name .asset file takes priority over a same-name .dat file in the loading order. The contents and syntax are identical.

Do I need both a .dat and a .asset file for each item? ​

No. An item requires one definition file. Most vanilla items use a .dat file with the same name as the folder and no .asset file. Some newer assets use a .asset file instead. If both a same-name .asset and .dat exist in the same folder, the .asset takes priority and the .dat is ignored.

What happens if two assets have the same GUID? ​

The asset that loads later overwrites the earlier asset in the engine's internal registry. The earlier asset effectively disappears, its fields, references, and in-game behavior are replaced by the later asset. This is the GUID collision failure that produces "item invisible" or "item replaced by different item" bugs. GUIDs must be unique across all mods loaded together.

Can I use the same GUID across different mods? ​

No. If two mods are loaded on the same server or in the same single-player session, any GUID collision between them will cause one mod's asset to overwrite the other. Generate a fresh GUID for every asset and never reuse GUIDs from other mods, tutorial files, or example projects.

How does the game find the prefab for an asset without a Master_Bundle_Override? ​

If no Master_Bundle_Override is specified, the game searches upward through the directory hierarchy for a MasterBundle.dat file (see the master bundle resolution chain flowchart earlier in this article). If a MasterBundle.dat is found, the game uses that master bundle and resolves the asset's prefab path based on the asset's file path relative to the bundle's asset prefix. If no MasterBundle.dat is found, the game looks for a .unity3d file with the same name as the .dat file in the same directory.

Can I put GUID and Type in a Metadata block for every asset type? ​

Yes. The Metadata block placement is valid for any asset type. However, the auto-generation of an empty GUID field only works in the root dictionary, not inside a Metadata block. If you use the Metadata block structure, always provide an explicit GUID value. The cohort recommendation is to use the root-dictionary style for item assets (matching the vanilla convention) and the Metadata block style only when the asset type's documentation or tooling expects it.

What is the difference between Type as a short name and Type as a fully qualified name? ​

The short name (e.g., Type Melee) is an alias that the game resolves to the corresponding C# class internally. The fully qualified name (e.g., Type SDG.Unturned.AirdropAsset, Assembly-CSharp, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null) specifies the exact class, assembly, and version. Short names are used for all built-in item, vehicle, animal, and object types. Fully qualified names are used for asset types that do not have a registered short-name alias or when the modder needs to specify a type from a specific assembly.

Can an asset reference another asset by GUID even if they're in different categories? ​

Yes. GUID-based references work across any asset category. A blueprint's CategoryTag field references a tag asset by GUID; a tag asset is not in the same category as the item that references it. GUIDs are globally unique and category-independent. Legacy ID-based references (e.g., a gun's Magazine 108 field) are category-scoped, they only work within the same category because IDs are only unique per category.

How do I know which asset type a .dat file is for? ​

The Type field on the first few lines of the file. Open the file in a text editor; the Type field (immediately after the GUID field) tells you which C# class will read the file. The type determines the entire set of recognized fields. If you are unsure which fields a given type supports, refer to the type-specific article in this knowledge base (e.g., Melee Asset for Type Melee).

Can one .asset file define multiple assets? ​

No. Each .dat or .asset file defines exactly one asset. A folder can contain multiple .asset files (each defining one asset), which is the pattern used by the tags system: the Tags/BlueprintCategory/ folder contains one .asset file per tag. The folder name is not the asset name in this pattern, each .asset file is an independent asset definition.

Best practices ​

  • Generate a fresh GUID for every asset using a UUID v4 generator. Remove hyphens. Never reuse GUIDs.
  • Place the GUID and Type fields at the root level of the dictionary for item assets, matching the vanilla convention.
  • Use Asset_Bundle_Version to declare the Unity version the bundle was built for, ensuring backward compatibility on game updates.
  • Use Master_Bundle_Override only when the asset needs a bundle different from the hierarchy-determined one.
  • Assign IDs in the 50,000+ range to avoid vanilla and community mod ID collisions.
  • Match the file name to the folder name (e.g., MyItem/MyItem.dat) unless the folder contains multiple assets (Format B pattern).
  • Always provide an English.dat file in the same directory for localization.
  • Verify the GUID is unique across all assets in the mod project before testing in-game.
  • Do not delete redirector .asset files used during level editing, levels save the original redirector GUIDs, not the resolved target GUIDs.
  • Use root-level Format A for item and vehicle assets; use Format B for tags, redirectors, and assets without bundle dependencies.

Appendix A: Quick-reference field card ​

GUID <32-char-hex>              ← required, globally unique
Type <AssetType>                 ← required, determines recognized fields
ID <uint16>                      ← required for items, unique per category

Metadata                         ← optional block (Format A variant)
{
    GUID <...>
    Type <...>
}

Asset                            ← optional block (Format A variant)
{
    <body fields>
}

Master_Bundle_Override <name>    ← optional, overrides hierarchy bundle
Exclude_From_Master_Bundle       ← optional, use .unity3d instead
Bundle_Override_Path <path>      ← optional, path within bundle
Bundle_Path_Include_Filename true ← optional, append filename to path
Asset_Bundle_Version <1-6>       ← optional, Unity version indicator

Appendix B: Asset loading order reference ​

Priority 1: <FolderName>.asset   ← same-name .asset file
Priority 2: <FolderName>.dat     ← same-name .dat file
Priority 3: Asset.dat            ← generic fallback
Priority 4: All *.asset files    ← multi-asset folder catch-all

Appendix C: Master bundle resolution reference ​

1. Exclude_From_Master_Bundle set?  → use individual .unity3d
2. Master_Bundle_Override set?      → use named master bundle
3. MasterBundle.dat in hierarchy?   → use nearest hierarchy master bundle
4. Same-name .unity3d exists?       → use that individual bundle
5. None of the above                → no bundle; prefab not loaded

Cross-references ​

Document history ​

VersionDateAuthorNotes
1.02026-07-2657 StudiosInitial publication. Complete asset definitions reference validated against shipped game files.

Glossary ​

TermDefinition
Asset definitionA text file (.dat or .asset) that associates game data with Unity content via GUID, Type, and bundle-linkage fields
AssetBundleA Unity binary file (.unity3d or .masterbundle) containing 3D models, textures, audio, and prefabs
Format AThe structured asset definition with optional Metadata and Asset sub-dictionaries
Format BThe simple asset definition with GUID and Type at the root level and no sub-dictionary blocks
Fully qualified nameThe complete .NET type reference including namespace, class, and assembly
GUIDA 128-bit globally unique identifier written as a 32-character hex string
Inheritance hierarchyThe C# class tree that determines which fields each asset type recognizes
Loading orderThe prioritized sequence the game uses to find an asset definition file in a folder
Master bundleA .masterbundle file containing bundled Unity assets for multiple asset definitions
Master bundle resolutionThe chain of decisions that determines which bundle file the game loads for an asset
Redirector assetA special asset type that remaps GUID and legacy ID references to a different target asset
Root dictionaryThe implicit top-level key-value dictionary in a .dat or .asset file
Type stringThe value of the Type field that determines the asset's C# class
57 Studios logo with slogan

Beginner-friendly guides for Unturned modding, tools, publishing, server operations, and troubleshooting.

Learn

Getting StartedSteam SetupInstalling Unturned

Explore

ItemsSelf-HostingTroubleshootingHome

Built for Unturned creators, server staff, and 57 Studios™ contributors.

Copyright © 57 Studios™. All rights reserved. 57 Studios™, its branding, guides, and associated original content are protected by applicable copyright and trademark law.