Asset Bundles Reference

Intermediate40-60 minutesWindowsNotepad++Unity Editor

Asset bundles are the packaging mechanism by which Unturned™ loads textures, audio, meshes, prefabs, and all other 3D assets from mods at runtime. Every custom item a modder authors eventually lives inside an asset bundle. The bundle is the bridge between the Unity Editor project on the modder's workstation and the game engine that renders the mod's content on every player's screen. A modder who understands the bundle system end-to-end can author, build, and ship assets with confidence; a modder who treats the bundle as a black box will encounter silent failures, missing prefabs, and Workshop submissions that load with placeholder cubes instead of the modelled content.

This article is the 57 Studios™ canonical reference for the Unturned asset bundle system. It documents every bundle type, the MasterBundle.dat declaration file that signals a bundle to the engine, the file-naming conventions that the load-time scanner depends on, the versioning and compatibility rules that govern which Unity versions produce loadable bundles, the tool workflow for building bundles from the Unity Editor, and the load-time chain by which the engine discovers and consumes bundled assets. The article covers the full asset bundle ecosystem: master bundles (the modern standard), individual .unity3d bundles (the legacy format that persists in official game files), and content bundles (the deprecated .content format that must be migrated). The modder who completes this article will understand every link in the chain that connects a Unity prefab to a rendered item in the game world.

Documentation source: This article references the official Smartly Dressed Games modding documentation for field definitions, tool workflows, and bundle loading behaviour. Shipped Unturned game files under Bundles\ have been inspected to confirm field behaviour. 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 who have already set up Unity per Unity Setup, generated GUIDs per Project Folder Structure and GUIDs, and authored at least one .dat item configuration file. It is the prerequisite reference for every subsequent pipeline article that references asset bundles: Master Bundle Export, Asset Bundle Custom Data, and every item-type reference that documents prefab setup. If you are new to Unturned modding and have not yet installed Unity, start with Unity Setup before returning here.

How Unturned loads asset bundles

Unturned's asset bundle loading system is a recursive directory scanner that operates at game load time. The engine walks every directory that is configured as a mod-loading path (the game's own Bundles\ directory, each subscribed Workshop item's content folder, and any manually installed mod folders under Workshop\Content\304930\). At each directory level, the scanner performs one critical check: it looks for a MasterBundle.dat file. The presence of a MasterBundle.dat file signals to the engine that the current directory contains a master bundle. The contents of that MasterBundle.dat file tell the engine the name of the bundle file, the Unity asset path prefix, and the bundle version.

The directory scan runs from the innermost directory outward. When the engine loads an item .asset file from a folder such as Bundles\Items\Guns\Eaglefire\, it checks that directory first for a MasterBundle.dat. If none is found, it checks the parent directory (Bundles\Items\Guns\), then that parent's parent (Bundles\Items\), then the root (Bundles\). The first MasterBundle.dat encountered is the one used, unless an individual .asset file specifies a Master_Bundle_Override directive. This hierarchical resolution means that a mod project can have a single master bundle at the project root serving every item, or multiple master bundles at different directory levels, or a mix of both patterns.

The flowchart above shows the master bundle discovery and loading chain. The load-time scanner is the first system that processes a mod's assets; if the scanner cannot find a MasterBundle.dat or cannot parse its fields, every item in the mod's directory tree will fail to resolve its prefab references.

The nearest-master-bundle rule

The "nearest master bundle" rule is the most important behavioural detail in the asset bundle loading system. Unless an item's .asset file carries an explicit Master_Bundle_Override field, the engine uses the master bundle declared in the nearest ancestor directory that contains a MasterBundle.dat file. This means a mod project structured as follows:

MyMod/
├── Bundles/
│   ├── MasterBundle.dat                  ← declares core.masterbundle
│   ├── core.masterbundle
│   └── Items/
│       ├── MyGun/
│       │   ├── MasterBundle.dat          ← declares mygun.masterbundle
│       │   ├── mygun.masterbundle
│       │   └── MyGun.asset
│       └── MyMelee/
│           └── MyMelee.asset             ← uses core.masterbundle (nearest ancestor)

In the structure above, MyGun.asset loads from mygun.masterbundle because it has its own nearest MasterBundle.dat. MyMelee.asset loads from core.masterbundle because it has no local MasterBundle.dat, and the nearest ancestor with one is the Bundles\ root. This pattern is used in official Unturned content where the core game bundle serves most items, but specific item groups (maps, large feature packs) have their own dedicated bundles.

MasterBundle.dat field reference

The MasterBundle.dat file is a plain text UTF-8 configuration file that declares a master bundle to the engine. Every field is a key-value pair on a single line. Comments are supported using the // prefix convention that Unturned's .dat parser follows; lines beginning with // are ignored.

| Field | Type | Required | Example | Purpose | |---|---|---|---| | Asset_Bundle_Name | string | Yes | core.masterbundle | The filename of the asset bundle file, located in the same directory as this MasterBundle.dat. The engine attempts to load this file when it processes the directory. | | Asset_Prefix | string | Yes | Assets/CoreMasterBundle | The path to the asset bundle's root folder within the Unity project. Unity subfolders in the bundle should match one-to-one with .dat subfolders. This is the key that maps the Unity project hierarchy to the mod's file hierarchy. | | Asset_Bundle_Version | integer | Yes | 3 | The asset bundle version number. Version 3 corresponds to Unity 2018.4 LTS. Older versions enable shader consolidation for backwards compatibility. This field controls which Unity build pipeline and shader handling the engine expects for the bundle. |

The Asset_Bundle_Version field warrants particular attention. Unturned's asset bundle pipeline has evolved across multiple Unity engine versions. Version 3 is the current standard and corresponds to the Unity 2018.4 LTS build target that the current Unturned release uses. If a modder builds a bundle with a newer Unity version and sets Asset_Bundle_Version 3, the engine attempts to load the bundle with 2018.4-era shader expectations. If the bundle was actually built with a later Unity version, shader mismatches produce pink materials or missing shader errors at runtime. The version number must match the Unity version that actually built the bundle.

Unturned's .dat parser behaviour with MasterBundle.dat

The parser that reads MasterBundle.dat is the same key-value parser that reads .asset files and item .dat files. It expects:

• One key-value pair per line
• The key and value separated by whitespace
• Lines beginning with // treated as comments
• Empty lines ignored
• UTF-8 encoding without BOM

A malformed MasterBundle.dat file (a missing field, a typo in a field name, a value that includes unexpected characters) causes the entire bundle to be skipped silently. The engine does not emit a visible error; it simply does not load the bundle. The modder sees missing prefabs and must diagnose the MasterBundle.dat content by inspection.

Example MasterBundle.dat files

The core Unturned master bundle declaration, as found in the shipped game's Bundles\MasterBundle.dat:

Asset_Bundle_Name core.masterbundle
Asset_Prefix Assets/CoreMasterBundle
Asset_Bundle_Version 3

A mod-specific master bundle declaration for a custom item pack:

Asset_Bundle_Name MyItemPack.masterbundle
Asset_Prefix Assets/MyItemPackMasterBundle
Asset_Bundle_Version 3

An older bundle declaration that uses version 2 for a legacy content pack:

Asset_Bundle_Name LegacyContent.masterbundle
Asset_Prefix Assets/LegacyContentMasterBundle
Asset_Bundle_Version 2

Individual .asset file field reference for bundle configuration

Each item's .asset file can include fields that modify how the engine resolves the bundle for that specific item. These fields override the hierarchical nearest-bundle resolution and provide fine-grained control over which bundle a given item loads from.

| Field | Type | Required | Purpose | |---|---|---| | Master_Bundle_Override | string | No | Specifies the name of a master bundle file to load this item's assets from. Overrides the nearest-ancestor MasterBundle.dat resolution. The engine looks for a MasterBundle.dat that declares this bundle name in any ancestor directory. | | Exclude_From_Master_Bundle | flag | No | If present, the engine does not look for a master bundle for this item. Instead, it looks for an individual .unity3d asset bundle file. This flag is used for legacy items that have not been migrated to the master bundle system. | | Bundle_Override_Path | string | No | Overrides the path within the master bundle from which the item loads its prefab. Used when multiple items share a common object prefab. Example: /Objects/Medium/Furniture/Note causes multiple note items to load the same shared note prefab. | | Bundle_Path_Include_Filename | bool | No | When true, the path within the master bundle appends the asset file's own name as a subdirectory. For example, Guns/Eaglefire.asset resolves to Guns/Eaglefire/Item.prefab inside the bundle. This is the standard pattern for item types that have their own dedicated prefab. |

Bundle_Override_Path: shared prefab pattern

The Bundle_Override_Path field is used when a group of items shares a single prefab. The canonical example is the note system in Unturned: every note item (a dozen or more distinct note types with different text content) uses the same physical prefab (a rectangular paper sheet). Each note's .asset file specifies Bundle_Override_Path /Objects/Medium/Furniture/Note, and the engine loads the same Note prefab for every note item. The items are differentiated by their .asset fields (the note's text content, the note's rarity, the note's ID) rather than by the prefab.

This pattern is useful for any mod that includes multiple variants of a single visual item: a collection of decorative signs that all share a signpost prefab, a set of clothing items that differ only in color and all share a single clothing mesh, or a set of storage containers that differ only in capacity and all share a single crate prefab.

Bundle_Path_Include_Filename: the standard item pattern

The Bundle_Path_Include_Filename field is set to true on the vast majority of item .asset files in the shipped game. When true, the engine constructs the prefab path inside the bundle by taking the .asset file's relative path, replacing the .asset extension with a subdirectory name, and appending a default prefab filename. The exact default filename depends on the item type: Guns/ items resolve to Item.prefab, most clothing items resolve to Item.prefab or a type-specific prefab name, and so on.

For a gun item at Bundles\Items\Guns\Eaglefire\Eaglefire.asset with Bundle_Path_Include_Filename true, the engine looks inside the master bundle at the Unity path Assets/CoreMasterBundle/Guns/Eaglefire/Item.prefab. The one-to-one mapping between .dat file hierarchy and Unity project hierarchy is the foundation of the bundle resolution system.

Master bundle strategy: one bundle versus multiple bundles

A mod project can use a single master bundle for every asset, or split assets across multiple master bundles at different directory levels. The choice has practical consequences for build time, load time, Workshop submission size, and update frequency.

| Strategy | Build time | Load time | Submission size | Update cost | |---|---|---|---| | Single master bundle | One build pass for the entire project | One bundle load at startup | Entire bundle uploaded for every update | Any change requires the full bundle to be rebuilt and re-uploaded | | Multiple master bundles | Each bundle builds independently | Each bundle loads independently; additional bundles load on demand | Only the changed bundle is re-uploaded | Smaller updates; only rebuild and re-upload the changed bundle |

The single-bundle strategy is the simpler of the two and the recommended starting point for new mod projects. A single MasterBundle.dat in the project's Bundles\ root directory, a single core.masterbundle file, and every item's .asset file resolving against that one bundle. The simplicity eliminates an entire category of misconfiguration: there is no possibility of an item referencing the wrong bundle because there is only one bundle.

The multiple-bundle strategy becomes advantageous when a mod project grows large. A map mod with several hundred megabytes of terrain textures should not force every player to re-download the entire bundle when a single item's prefab is updated. Placing the map data in one master bundle and the item data in another master bundle allows the modder to update items without touching the map bundle, and Workshop subscribers download only the changed bundle. The official Unturned core game content uses the multiple-bundle strategy: the core core.masterbundle serves the majority of items, while individual maps and large feature packs use their own bundles.

Loading asset bundles: the game-side chain

When the engine has located a MasterBundle.dat and loaded the corresponding .masterbundle file, the asset loading chain proceeds in three stages for each item:

The sequence above shows the full chain from directory scan to prefab instantiation. Each step is synchronous: a failure at any step blocks the item from loading. A missing MasterBundle.dat blocks the bundle load. A missing .masterbundle file blocks the bundle load. A typo in the Asset_Prefix field causes every prefab path inside the bundle to resolve incorrectly. A missing prefab inside the bundle causes the item to load with a fallback placeholder mesh (or, in some engine versions, to fail silently and produce an invisible item).

Prefab path resolution in detail

The engine constructs the prefab path inside the bundle by combining the Asset_Prefix from MasterBundle.dat, the relative path of the .asset file from the project root, and the Bundle_Path_Include_Filename logic. For an item at Bundles\Items\Guns\Eaglefire\Eaglefire.asset with Bundle_Path_Include_Filename true and Asset_Prefix Assets/CoreMasterBundle:

1. The engine strips the Bundles\ prefix from the .asset file path, producing Items\Guns\Eaglefire\Eaglefire.asset
2. It replaces .asset with a directory separator, producing Items\Guns\Eaglefire\
3. It appends the default prefab filename for the item type, producing Items\Guns\Eaglefire\Item.prefab
4. It prepends the Asset_Prefix, producing Assets/CoreMasterBundle/Items/Guns/Eaglefire/Item.prefab
5. It looks up this path in the loaded master bundle's asset table

If the path does not exist in the bundle's asset table, the item loads without a prefab and appears as a placeholder or is invisible. The most common cause of missing prefab paths is a mismatch between the Unity project folder structure and the .dat file folder structure. The two must mirror each other exactly.

Bundle versioning and compatibility

Unturned's asset bundle versioning system bridges the gap between the Unity Editor version that builds the bundle and the Unity runtime version that loads the bundle. The Asset_Bundle_Version field in MasterBundle.dat determines which version-specific behaviours the engine applies when loading the bundle.

Version	Unity equivalent	Shader behaviour	Status
1	Pre-2018.4	Full shader consolidation enabled; all shaders compiled into a single compatibility set	Legacy; not recommended for new projects
2	Intermediate	Partial shader consolidation; some platform-specific shader variants included	Legacy; not recommended for new projects
3	Unity 2018.4 LTS	No shader consolidation; shaders are platform-specific as built by Unity	Current standard

Version 3 should be used for all new mod projects. It corresponds to the Unity 2018.4 LTS build target that the current Unturned release uses, and it disables the shader consolidation that earlier versions performed. Shader consolidation was a compatibility mechanism that merged multiple shader variants into a single shader file; it was necessary in earlier Unity versions that lacked robust cross-platform shader support but is no longer needed and can introduce subtle rendering differences between platforms.

What happens when the version is wrong

If Asset_Bundle_Version is set to 3 but the bundle was built with a Unity version earlier than 2018.4, the engine expects platform-specific shaders that the bundle does not contain. Materials render as bright pink (the Unity missing-shader fallback colour). If Asset_Bundle_Version is set to 2 but the bundle was built with Unity 2018.4 or later, the engine applies shader consolidation logic that is unnecessary and may strip shader variants that the bundle expects to use. The result is materials that render incorrectly on specific graphics hardware or platforms.

The version number is not automatically detected by the engine from the bundle file's metadata. The modder must set it correctly in MasterBundle.dat. The engine trusts the declared version and does not cross-check it against the bundle's actual Unity build version. A mismatch produces silent rendering failures that are difficult to diagnose because the bundle loads without errors and the only visible symptom is the wrong material colour on the rendered item.

File naming conventions

The asset bundle system imposes specific naming conventions that the engine relies on for file discovery and asset resolution. The conventions below are enforced by the engine's scanner and must be followed exactly.

Convention	Requirement	Reason
MasterBundle.dat filename	Must be named exactly MasterBundle.dat	The directory scanner looks specifically for this filename. Any other name is ignored.
Bundle file extension	.masterbundle for master bundles, .unity3d for individual bundles	The engine uses the extension to determine which loading path to use.
Asset_Prefix value	Must match the Unity project folder name exactly, including case	The engine concatenates the prefix with the resolved item path. A case mismatch produces a lookup failure on case-sensitive platforms (Linux dedicated servers).
.asset filename	Must match the directory name for the item type's standard resolution	The Bundle_Path_Include_Filename resolution depends on the filename matching the directory. Example: Guns\Eaglefire\Eaglefire.asset rather than Guns\Eaglefire\MyGunData.asset.
Bundle file location	Must reside in the same directory as the MasterBundle.dat that declares it	The engine looks for the bundle file alongside the .dat file that names it.

Multiplatform bundle naming

When the master bundle tool's "multiplatform" toggle is enabled, the export produces three bundle files:

MyBundle.masterbundle               ← Windows build (primary)
MyBundle_linux.masterbundle         ← Linux dedicated server build
MyBundle_mac.masterbundle           ← macOS client build
MyBundle.masterbundle.hash           ← Hash file for server-side integrity verification
MyBundle.masterbundle.manifest       ← Manifest listing all bundled assets

The platform-specific bundles contain shader variants compiled for each target platform. The Windows client uses the primary .masterbundle file. Linux dedicated servers read from _linux.masterbundle. macOS clients read from _mac.masterbundle. The hash file is used by the server to validate that a connecting client's bundle matches the server's bundle, preventing modified clients that give unfair advantages (transparent walls, glowing materials, removed foliage).

The manifest file lists every asset in the bundle with its internal path and its content hash. The manifest is not required at runtime; it is a debugging and diagnostic tool. When a modder suspects that a particular prefab was not included in the bundle, opening the manifest file and searching for the prefab's path confirms whether the bundle contained it.

The .hash file and integrity verification

The .hash file is a critical security feature for multiplayer mods. When a server loads a master bundle that includes a .hash file, the server computes the hash of every connecting client's bundle and compares it to the stored hash. If the hashes differ, the client is rejected with a bundle-mismatch error. This prevents clients that have modified the bundle to gain unfair visual advantages: rendering walls as transparent, removing foliage to expose players, or highlighting items through terrain.

Critical warning

Deleting the .hash file disables bundle integrity verification. A server running without hash verification allows cheaters to connect with modified asset bundles. Mods intended for multiplayer distribution must always include the .hash file. The cohort recommendation is to enable the multiplatform toggle during export, which generates the hash file automatically, and to include every generated file in the mod's Workshop submission.

The master bundle tool workflow

The master bundle tool is a Unity Editor extension that ships with the Unturned modding package. It wraps Unity's BuildAssetBundles API with Unturned-specific parameters and provides a graphical interface for selecting assets, assigning bundle names, designating master bundles, and choosing export destinations. The tool must be imported into the Unity project before use, following the tool setup procedure documented in How to Find the Master Bundle Tool.

Tool setup

Before the master bundle tool is available, the Unturned Unity package must be imported into the modder's Unity project. The procedure is:

1. Inside Unity, open the Assets > Import Package > Custom Package wizard.
2. Navigate to the Unturned installation directory.
3. Open the Extras/Sources directory.
4. Select and import the Project.unitypackage file.

After import, the tool appears under Window > Unturned > Master Bundle Tool. The tool window displays a list of all asset bundles currently defined in the Unity project, with checkboxes to designate which bundles are master bundles and an export path selector for each designated bundle.

Export workflow step-by-step

The complete export workflow, from a Unity project with assets to a loadable master bundle file in the mod's folder structure, follows these steps:

1. Select directories of assets in the Unity Project window. These are the folders containing prefabs, materials, textures, and audio files that the mod will package.
2. In the Inspector window, tag the selected assets into any asset bundle. The bundle name is the name that will appear in the master bundle tool's list and in the exported .masterbundle filename. Use a descriptive name that matches the mod's identity (e.g., MyItemPackMasterBundle).
3. Open the master bundle tool from the Window > Unturned > Master Bundle Tool menu.
4. Click the checkbox next to the asset bundle's name to mark it as a master bundle. This filters the list to show only master bundles and enables the export path selector.
5. Click the ... button to choose a destination folder for the exported bundle file or files. This should be the mod's Bundles\ folder or a subfolder within it.
6. Click Export. The tool invokes BuildAssetBundles with the configured settings and writes the .masterbundle file (or files, if multiplatform is enabled) to the chosen destination.
7. (Optional) Enable the multiplatform toggle before exporting if the mod is intended for distribution. This ensures platform-specific shaders are included and generates the .hash file for server-side integrity verification.

Generated files after export

After a successful export, the destination folder contains the following files:

File	Always generated?	Purpose
<name>.masterbundle	Yes	The primary asset bundle file. Contains all prefabs, meshes, materials, textures, and audio assets for the Windows platform.
<name>_linux.masterbundle	Only with multiplatform enabled	Contains platform-specific shader variants for Linux dedicated servers.
<name>_mac.masterbundle	Only with multiplatform enabled	Contains platform-specific shader variants for macOS clients.
<name>.masterbundle.hash	Only with multiplatform enabled	The hash file used by servers to validate client bundle integrity.
<name>.masterbundle.manifest	Only with multiplatform enabled	A text file listing every asset in the bundle, its internal path, and its content hash.

Individual asset bundles (.unity3d)

Individual asset bundles are the legacy bundle format that predates the master bundle system. Most official Unturned files have been migrated to the master bundle system, but some specific asset types continue to use individual .unity3d bundles. The remaining use cases include per-map road textures, colours used by chart objects in the UI, and level ambience audio.

Individual bundles are loaded by name without extension. Each game type looks for specific names depending on the asset category: items look for a bundle named something like the item's folder name, objects look for a bundle named after the object type, and so on. The .unity3d extension was originally chosen for web browser compatibility (Unity's Web Player used .unity3d as its bundle extension), but the system has aged poorly and the master bundle system is the recommended replacement for all new projects.

Individual bundle tool workflow

The individual bundle tool, available under Window > Unturned > Bundle Tool in Unity, provides a simpler workflow for exporting individual .unity3d bundles:

1. Select individual assets or directories of assets in the Unity Project window.
2. Click Grab to preview which assets will be included in the export.
3. Click Bundle to choose a destination for the .unity3d file.

An item's .asset file can opt into the individual bundle system by including the Exclude_From_Master_Bundle flag. When this flag is present, the engine bypasses the master bundle resolution for that item and instead looks for a .unity3d bundle file. The bundle filename is derived from the item's directory structure or from an explicit bundle name field in the .asset file.

When to use individual bundles

The cohort recommendation is to use individual bundles only when the asset type genuinely requires them. The official documentation identifies three remaining use cases: per-map road textures, colours used by chart UI elements, and level ambience audio. For all other asset types, the master bundle system is the correct choice. New mod projects should use master bundles exclusively unless the modder is specifically extending one of the individual-bundle-only asset categories.

Content bundles (.content)

Content bundles are a deprecated format that was used by terrain data, material palettes, and radio songs in earlier Unturned versions. Support for content bundles was removed on February 25, 2022 (Unturned version 3.22.4.0). Any mod that still uses .content files will not load in current Unturned builds.

Migrating an old content bundle to the master bundle system is straightforward. The migration procedure is:

1. Rename the .content file to .masterbundle (change only the extension, not the rest of the filename).
2. Create a MasterBundle.dat file in the same directory, configured with the standard fields: Asset_Bundle_Name pointing to the renamed .masterbundle file, Asset_Prefix set to the original Unity project path, and Asset_Bundle_Version set to the appropriate version.
3. Verify the migrated bundle loads correctly by checking the item's .asset file paths against the new bundle's asset table.

The rename-and-declare migration preserves the original bundled assets without requiring a rebuild in Unity. The bundle's internal structure is compatible: the .content and .masterbundle formats share the same underlying Unity asset bundle serialization, and only the file extension and the loading path differ.

How the bundle connects to the item system

The asset bundle is not an end in itself; it is the middle layer in a three-layer asset pipeline. The .dat file layer defines what an item is (its ID, GUID, type, and data fields). The bundle layer supplies the visual and audio content (prefabs, meshes, materials, textures, audio clips). The engine layer connects the two at load time by resolving prefab paths inside the bundle from the fields in the .dat file.

The flowchart above shows the three distinct concerns that the modder must author correctly. A mistake in the .dat layer (wrong GUID, wrong type) prevents the item from being recognized by the engine. A mistake in the .asset or MasterBundle.dat layer (wrong prefix, wrong path) prevents the prefab from being resolved. A mistake in the bundle itself (missing prefab, wrong Unity build target) prevents the resolved prefab from rendering correctly. Each layer must be correct for the item to appear and function in the game world.

Tool setup: importing the Unturned Unity package

The Unity project that builds the master bundle must contain the Unturned modding package. The package provides the master bundle tool, the individual bundle tool, and type-specific Unity scripts (such as UseableMelee, UseableGun) that the prefabs reference. The import procedure uses Unity's built-in package import wizard.

The package is located in the Unturned installation directory under Extras/Sources/Project.unitypackage. If the Unturned installation directory is not at its default Steam Library location, the path can be found by right-clicking Unturned in the Steam Library, selecting Properties > Installed Files > Browse, and navigating to Extras/Sources/ from there.

Pro tip

Import the Unturned Unity package into a clean Unity project that contains only the mod's source assets. Do not import it into a Unity project that contains multiple unrelated mods or other development assets. The package includes scripts and prefabs that assume a specific project structure, and mixing them with assets from other projects produces a project that is difficult to maintain and debug.

Common bundle export issues and fixes

The export process has several known failure modes, each with a documented resolution. The table below lists the most common issues encountered during master bundle export and the fix for each.

Symptom	Most likely cause	Resolution
Master bundle tool does not appear in the Window menu	Unturned Unity package not imported	Import Project.unitypackage from Extras/Sources in the Unturned installation directory
Export produces no output file	No asset bundle name assigned to selected assets	Select assets in the Project window, assign a bundle name in the Inspector
Export produces an empty or very small .masterbundle	Assets not tagged into the correct bundle	Confirm each asset's bundle assignment in the Inspector; verify assets are not assigned to a different bundle name
Asset bundle loads but prefabs are invisible	Asset_Prefix does not match Unity project folder name	Open MasterBundle.dat, confirm Asset_Prefix matches the Unity project's folder name exactly
Materials render as bright pink	Shader compilation mismatch; Unity version does not match Asset_Bundle_Version	Confirm the Unity Editor version used to build the bundle matches the Asset_Bundle_Version field; rebuild with the correct Unity version
Prefab appears with wrong scale or rotation	Non-unit scale on the prefab in the Unity scene	Reset the prefab's Transform to default values before assigning it to the bundle
Linux dedicated server rejects clients with "bundle mismatch"	.hash file missing or stale after bundle update	Rebuild the bundle with the multiplatform toggle enabled; include the generated .hash file in the server's bundle directory
Item loads but uses placeholder mesh	Prefab not included in the master bundle, or path resolution failed	Check the bundle manifest file for the expected prefab path; confirm the .asset file's bundle-related fields resolve to the correct prefab path inside the bundle

Working with master bundle pointers

Master bundle pointers are a load-time mechanism that allows one master bundle to reference assets in another master bundle. This is the system that enables the official game's core bundle to reference per-map assets that live in map-specific bundles. The pointer system uses the Master_Bundle_Override field on individual .asset files to redirect the asset resolution to a different bundle.

When an .asset file includes Master_Bundle_Override MyMap.masterbundle, the engine skips the hierarchical nearest-bundle resolution and instead searches for a MasterBundle.dat that declares Asset_Bundle_Name MyMap.masterbundle. If found, the item loads its prefab from that bundle. If not found, the item loads without a prefab.

This mechanism is the standard pattern for mods that want to split their assets across multiple bundles. A core bundle provides common prefabs; specialty bundles provide map-specific or feature-specific prefabs; and individual items point to the appropriate bundle through Master_Bundle_Override. The cohort recommendation for multi-bundle mods is to document which bundle serves which items in the mod's README.md or Workshop description, so that other modders collaborating on the project understand the bundle topology.

Best practices

• Use the master bundle system for all new mod projects. Do not start new development with individual .unity3d bundles or deprecated .content bundles.
• Set Asset_Bundle_Version 3 in MasterBundle.dat and build the bundle with the Unity version that matches the current Unturned build target.
• Enable the multiplatform toggle when exporting for distribution. Include every generated file (.masterbundle, .hash, .manifest, and platform suffixes) in the Workshop submission.
• Never delete the .hash file from a published mod. Bundle integrity verification is the primary defence against cheating through modified asset bundles.
• Keep the Unity project folder structure and the mod's .dat folder structure mirrored exactly. A mismatch between the two produces prefab resolution failures that are time-consuming to diagnose.
• Use a single master bundle for small to medium mod projects. Graduate to multiple bundles only when the project's size or update frequency genuinely benefits from the split.
• Document the bundle topology in the mod's project files. A new collaborator should be able to read one document and understand which items load from which bundle.
• Verify the bundle's contents by inspecting the manifest file after export. Confirm that every expected prefab, material, and texture appears in the manifest.
• Test the built bundle in a local Unturned single-player session before uploading to the Workshop. A bundle that loads in the Unity Editor does not necessarily load in the compiled game.
• Retain the Unity project that built the bundle. A rebuilt bundle must be built from the same project (or a version-controlled copy) to maintain asset consistency across updates.

Frequently asked questions

What is a master bundle?

A master bundle is a Unity asset bundle that has been designated as a master bundle through the MasterBundle.dat declaration file. The term "master bundle" is an Unturned convention, not a Unity API distinction. A master bundle is a regular Unity asset bundle, built for the platform Unturned runs on, with the naming convention Unturned expects, placed in a folder that contains a MasterBundle.dat file. The master bundle system is the recommended packaging format for all new mod projects.

Can a mod have its own master bundle?

Yes. Every mod should have its own master bundle. A mod creates its own MasterBundle.dat file in its Bundles\ directory, points Asset_Bundle_Name at the mod's own .masterbundle file, sets Asset_Prefix to the mod's Unity project folder name, and builds the bundle from the mod's Unity project. The mod's items load from the mod's bundle, completely independent of the official game's core bundle. Mod bundles can coexist with the core bundle and with other mod bundles without conflict.

Why are there three bundle file formats (master, individual, content)?

The three formats represent the evolution of Unturned's modding infrastructure across engine versions. Individual .unity3d bundles were the original format, designed when Unturned needed to load custom content at runtime with a simple name-based lookup system. Content bundles (.content) were an intermediate format used for specific asset types like terrain and material palettes. Master bundles (.masterbundle) are the current and recommended format, providing the most robust feature set: hierarchical loading, multiplatform shader support, hash-based integrity verification, and manifest-based asset tracking. The older formats persist in the engine for backwards compatibility with legacy content but should not be used for new projects.

What does the Asset_Prefix field actually control?

Asset_Prefix is the prefix that the engine prepends to every prefab path it resolves inside the bundle. When the engine needs to load a prefab for an item at the path Guns/Eaglefire/Item.prefab, it prepends the Asset_Prefix from the nearest MasterBundle.dat to produce the full lookup path: Assets/CoreMasterBundle/Guns/Eaglefire/Item.prefab. This path is used to look up the prefab in the loaded bundle's internal asset table. If the Asset_Prefix does not match the Unity project's folder name, the lookup produces a path that does not exist in the bundle, and the item loads without a prefab.

When should I use Bundle_Override_Path instead of the standard path resolution?

Use Bundle_Override_Path when multiple items share a single prefab. The canonical use case is the note system in Unturned: every note item (each with different text content) uses the same physical note paper prefab. Each note's .asset file sets Bundle_Override_Path /Objects/Medium/Furniture/Note, and all notes load the same prefab. Without this override, each note would need its own copy of the prefab inside the bundle, duplicating asset data. Use Bundle_Override_Path sparingly: it is a tool for deduplication, not a general-purpose path override mechanism.

What happens if I delete the .hash file from my mod?

If the .hash file is deleted from a mod that is installed on a multiplayer server, the server can no longer verify that connecting clients have an unmodified copy of the mod's asset bundle. Cheaters can then modify their local copy of the bundle to gain unfair advantages: rendering walls as transparent, removing foliage that would otherwise conceal players, or making certain materials glow to highlight items in darkness. The .hash file is the only mechanism the engine provides to detect modified bundles. Deleting it removes the integrity check entirely.

Can I use the same master bundle for multiple mods?

Technically yes, but the cohort recommendation is to give every mod its own master bundle. A mod that shares a bundle with another mod creates a dependency: the shared bundle must be installed for either mod to work. If one mod updates and changes the shared bundle's contents, the other mod may break because its prefab paths no longer resolve correctly. Furthermore, Workshop subscribers cannot install one mod without the other because the shared bundle is a single file. The small disk-space saving of a shared bundle is not worth the complexity it introduces.

How do I know if my bundle loaded correctly?

The fastest verification method is to spawn an item that references the bundle in a local single-player session and visually confirm that the item's model appears correctly (not pink, not a placeholder cube, not invisible). A more thorough verification is to open the console with ~ and check for any errors related to asset loading. The most thorough verification is to inspect the bundle's manifest file after export and confirm that every expected prefab, material, and texture path appears in the manifest.

What Unity version should I use to build master bundles?

The Unity version that matches the current Unturned build target. As of the current Unturned release, that is Unity 2018.4 LTS. The version is documented in the official Smartly Dressed Games modding documentation and can be confirmed by checking the Unturned changelog on Steam. Building a bundle with a different Unity version produces a bundle that the engine may load but whose shaders may not compile correctly, producing pink materials or rendering artefacts.

What is the multiplatform toggle and when should I use it?

The multiplatform toggle is an option in the master bundle tool that, when enabled, generates platform-specific bundle variants for Linux dedicated servers and macOS clients, a .hash file for server-side integrity verification, and a .manifest file for asset tracking. Enable the multiplatform toggle for every mod that is intended for distribution through the Steam Workshop. The only scenario in which the multiplatform toggle should be disabled is a mod that is exclusively for local single-player use on Windows, where the additional platform-specific bundle files and hash file are unnecessary.

Can I load assets directly from the Unity Editor without building a bundle?

No. Unturned's runtime does not connect to a Unity Editor session; it can only load assets from compiled bundle files on disk. During development, the workflow is to build the bundle, copy it to the mod's test folder, launch Unturned, and test the loaded assets. This edit-build-test cycle is the standard workflow for all Unturned mod development. The cohort recommendation for reducing iteration time is to automate the build-and-copy steps with a batch script or Unity Editor build hook.

What is the maximum size of a master bundle?

There is no hard maximum size enforced by the Unity asset bundle format or by Unturned. Practical limits are determined by download time for Workshop subscribers and load time for players launching the game. A bundle of several hundred megabytes is typical for large map mods and loads within acceptable times on modern hardware. A bundle approaching several gigabytes will result in long Workshop download times and should be split into multiple smaller bundles if possible.

Advanced considerations

Bundle dependency chains

Master bundles can depend on assets in other master bundles. This is the dependency chain pattern used in the official game: map-specific bundles reference shared core assets, and specialty bundles reference both core and map-specific assets. The dependency is declared through Master_Bundle_Override on individual .asset files and is resolved at load time. A broken dependency chain (an item that references a bundle that is not installed) produces the standard missing-prefab behaviour: the item loads but appears with a placeholder mesh or is invisible.

Managing dependency chains requires discipline. Every bundle that a mod declares as a dependency must be documented in the mod's Workshop description so that players understand which other mods are required. The cohort recommendation for standalone Workshop submissions is to avoid dependency chains in favour of self-contained bundles. If dependency chains are necessary (for a large map mod that must reference the core game bundle, or for a mod series where multiple Workshop items share a base-content bundle), document the dependency graph prominently in every affected Workshop item's description.

Asset bundle compression: LZ4 versus LZMA

Unity supports two compression algorithms for asset bundles: LZ4 and LZMA. LZMA produces smaller files but requires decompressing the entire bundle into memory before any asset can be loaded. LZ4 produces larger files but allows individual assets to be loaded from the bundle without loading the entire bundle. Unturned's master bundle tool defaults to LZ4 compression, which is the appropriate choice for the mod use case: mods typically contain many individual assets (prefabs, textures, materials) that are loaded on demand as items are spawned, and the per-asset loading capability of LZ4 avoids the memory spike of decompressing an entire multi-hundred-megabyte bundle at startup.

Incremental builds and bundle caching

Unity's BuildAssetBundles API supports incremental builds: assets that have not changed since the last build are not reprocessed, and only changed assets are recompressed into the bundle. The incremental build is significantly faster than a full rebuild, especially for large mod projects with hundreds of assets. The incremental build is enabled by default when building to the same output directory as a previous build. The cohort recommendation is to use the same build output directory throughout a mod's development cycle to benefit from incremental build caching.

Custom shaders in asset bundles

Unturned supports custom shaders in mod bundles, but the shaders must be compatible with the Unity version that Unturned uses at runtime. A custom shader written for a newer Unity version may fail to compile when the engine loads the bundle, producing the pink missing-shader material. The cohort recommendation for mods that require custom visual effects is to use the standard Unity shader (or one of the shaders included in the Unturned Unity package) for all materials, and to reserve custom shaders for genuinely necessary effects that cannot be achieved through standard shader parameter tuning.

Asset bundle streaming and memory management

The engine loads asset bundles into memory and holds references to loaded prefabs for the duration of the game session. A bundle that contains many large textures or high-polygon meshes consumes significant memory. The cohort recommendation for performance-sensitive mods is to keep individual bundle sizes reasonable (under 500 MB for the largest bundle in a mod) and to use texture compression settings that balance visual quality with memory consumption. The Unity Editor's asset bundle build report can be consulted before export to preview the bundle's size and asset breakdown.

Appendix A: MasterBundle.dat field quick reference

Field	Type	Required	Example	Purpose
Asset_Bundle_Name	string	Yes	core.masterbundle	Filename of the bundle file in the same directory
Asset_Prefix	string	Yes	Assets/CoreMasterBundle	Unity project folder path for asset lookup
Asset_Bundle_Version	integer	Yes	3	Unity version compatibility flag

Appendix B: Item .asset file bundle configuration fields quick reference

Field	Type	Required	Default	Purpose
Master_Bundle_Override	string	No	,	Override the nearest master bundle with a named bundle
Exclude_From_Master_Bundle	flag	No	not set	Use individual .unity3d bundle instead of master bundle
Bundle_Override_Path	string	No	,	Override the prefab path within the bundle
Bundle_Path_Include_Filename	bool	No	false	Append the asset filename as a subdirectory in the bundle path

Appendix C: Bundle format comparison

Format	Extension	Status	Recommended for new projects?	Key features
Master bundle	.masterbundle	Current	Yes	Hierarchical loading, multiplatform shaders, hash integrity, manifest
Individual bundle	.unity3d	Legacy	No (except specific asset types)	Simple name-based loading
Content bundle	.content	Deprecated (removed 2022-02-25)	No	Rename to .masterbundle to migrate

Appendix D: Diagnostic table for bundle issues

Symptom	Most likely cause	Resolution
No MasterBundle.dat found	File is missing or incorrectly named	Create MasterBundle.dat in the correct directory; confirm the filename is exact
Items load without prefabs	Asset_Prefix does not match Unity project folder	Correct Asset_Prefix to match the Unity project folder name exactly
Materials appear pink	Shader compilation mismatch or missing shader	Confirm Unity version matches Asset_Bundle_Version; rebuild with correct Unity version
Client rejected from server with "bundle mismatch"	.hash file missing or stale	Rebuild with multiplatform toggle; include .hash file
Bundle export produces no output	No asset bundle name assigned	Select assets in Project window; assign a bundle name in the Inspector
Prefab path not found in bundle	Unity folder structure does not mirror .dat folder structure	Mirror the .dat folder structure inside the Unity project
Bundle loads but item is invisible	Prefab not included in bundle or Bundle_Override_Path incorrect	Check manifest file for missing prefab; verify Bundle_Override_Path
Multiple bundles conflict	Two MasterBundle.dat files declare the same Asset_Bundle_Name	Use unique bundle names for separate bundles in the same project

Appendix E: Complete master bundle tool workflow reference

The master bundle tool workflow summarised in a single reference table for quick consultation:

Step	Action	Location
1	Import Unturned Unity package	Assets > Import Package > Custom Package, navigate to Unturned\Extras\Sources\Project.unitypackage
2	Create or open Unity project	Unity Hub or File > Open Project
3	Select asset directories	Unity Project window
4	Assign bundle name in Inspector	Inspector window, asset bundle dropdown at the bottom
5	Open master bundle tool	Window > Unturned > Master Bundle Tool
6	Check the master bundle checkbox	Checkbox next to the bundle name in the tool window
7	Choose export destination	Click the ... button, select the mod's Bundles\ folder
8	Enable multiplatform toggle (for distribution)	Toggle in the tool window
9	Click Export	Export button in the tool window
10	Verify generated files	Check destination folder for .masterbundle, .hash, .manifest, and platform suffix files
11	Create MasterBundle.dat	Create MasterBundle.dat in the export directory with correct fields
12	Test in Unturned single-player	Copy bundle and .dat files to test folder, launch game, spawn item

Appendix F: External references

• Smartly Dressed Games modding documentation, the official field reference and tool workflow documentation for Unturned asset bundles.
• Unturned on Steam, the Unturned™ store page and community hub.
• Master Bundle Export, the Unity bundling workflow article; covers the BuildAssetBundles API, platform targeting, and compression settings in detail.
• Asset Bundle Custom Data, the next article in this section; covers custom metadata that can be embedded in a master bundle.
• How to Find the Master Bundle Tool, details the tool setup procedure and the Unity menu structure.
• Project Folder Structure and GUIDs, the folder layout that master bundles depend on; covers GUID generation and ID conventions.
• Asset Validation Rules, the preceding article in this section; covers the .asset file format fields.

Document history

Version	Date	Author	Notes
1.0	2026-07-26	57 Studios	Initial publication. Complete asset bundle reference: master, individual, and content bundle formats; MasterBundle.dat field reference; bundle loading chain; versioning and compatibility; file naming conventions; worked export workflow; diagnostic tables; external references.

Authoring checklist

Before publishing a mod that uses asset bundles, confirm the following:

• [ ] MasterBundle.dat is present in the mod's Bundles\ directory (or the appropriate subdirectory)
• [ ] Asset_Bundle_Name field matches the exported .masterbundle filename exactly
• [ ] Asset_Prefix field matches the Unity project folder name exactly
• [ ] Asset_Bundle_Version is set to 3 (or the correct version for the Unity Editor version used)
• [ ] The .masterbundle file is present in the same directory as the MasterBundle.dat that declares it
• [ ] The multiplatform toggle was enabled during export, and all generated files are included in the submission
• [ ] The .hash file is included for server-side integrity verification
• [ ] Every item .asset file resolves to a valid prefab path inside the bundle
• [ ] The Unity project folder structure mirrors the mod's .dat folder structure exactly
• [ ] The bundle has been tested in a local Unturned single-player session before Workshop submission

Cross-references

• Asset Bundle Custom Data, the next article in this section; covers custom metadata embedded in master bundles.
• Master Bundle Export, the detailed Unity bundling workflow article with compression settings and platform targeting.
• How to Find the Master Bundle Tool, tool setup and Unity menu navigation for the master bundle tool.
• Project Folder Structure and GUIDs, the folder layout that bundle resolution depends on.
• Item Asset Anatomy, the shared fields that every .asset file supports, including the bundle configuration fields.
• Smartly Dressed Games modding documentation, the official field reference for Unturned asset bundles.
• Unturned on Steam, game page and community.