Master Bundle Internal Structure

Intermediate40-60 minutesWindowsNotepad++Unity Editor

The master bundle is the primary packaging format for Unturned™ game assets. A master bundle is a Unity AssetBundle file (format version 6, corresponding to Unity 2022 LTS) that contains models, textures, audio clips, prefabs, materials, and other Unity assets packaged together for efficient runtime loading. The game's core master bundle, core.masterbundle, is approximately 117 MB and contains the majority of the game's visual and audio assets.

57 Studios™ has documented the internal structure of master bundles through analysis of core.masterbundle, its MasterBundle.dat declaration, and the relationship between the bundle's content and the game's asset loading system. This article covers every aspect of master bundle structure, the MasterBundle.dat declaration format, the internal organization conventions, and how the game resolves asset paths within the bundle.

Documentation source: This article references the official Smartly Dressed Games modding documentation for the master bundle system and file setup. Technical details about the Unity AssetBundle format version 6 are drawn from Unity documentation and analysis.

Who this article is for

This article is written for Unturned™ mod authors who want to understand how master bundles work internally, mod authors troubleshooting asset loading issues, and developers planning advanced mod projects that involve custom bundle structures.

The MasterBundle.dat declaration

Every master bundle directory requires a MasterBundle.dat file that declares the bundle's properties. This file signals to the game that a master bundle is present in the directory hierarchy and configures how the bundle is loaded.

Asset_Bundle_Name core.masterbundle
Asset_Prefix Assets/CoreMasterBundle
Asset_Bundle_Version 3

Field	Type	Purpose
Asset_Bundle_Name	string	The name of the .masterbundle file in the same directory as MasterBundle.dat.
Asset_Prefix	string	The path within the Unity project to the root of the assets that were bundled. Unity subfolders should match 1:1 with .dat subfolders.
Asset_Bundle_Version	int	The Unity version this bundle was built for. Value 3 is Unity 2018.4 LTS, 6 is Unity 2022 LTS (the current version).

Asset_Bundle_Version values

Version	Unity release	Notes
1	Unity 5.5	Legacy format
2	Unity 2017.4 LTS	Second generation
3	Unity 2018.4 LTS / 2019 LTS	Shader consolidation enabled for backwards compatibility
4	Unity 2020 LTS	Updated pipeline
5	Unity 2021 LTS	Current stable
6	Unity 2022 LTS	Latest (current default)

Master bundle loading chain

The game loads master bundles through a hierarchical directory scan. When loading assets from a directory, the game checks each directory in the file hierarchy for a MasterBundle.dat file. The nearest master bundle in the hierarchy is used unless an override is specified.

As shown in the flowchart above, the loading chain walks up the directory hierarchy if no MasterBundle.dat is found in the immediate directory. This allows subdirectories to inherit the master bundle configuration from their parent directories.

Internal bundle organization

The core.masterbundle is organized according to the Asset_Prefix defined in its MasterBundle.dat. Because Asset_Prefix is set to Assets/CoreMasterBundle, all asset paths within the bundle are relative to that prefix.

Asset directory structure convention

The shipped assets follow a consistent directory structure convention within the bundle:

Assets/CoreMasterBundle/
├── Effects/
│   ├── Ambience/
│   ├── Impacts/
│   └── Physics/
├── Items/
│   ├── Guns/
│   ├── Melee/
│   ├── Magazines/
│   ├── Outfits/
│   └── ...
├── Objects/
│   ├── Medium/
│   ├── Small/
│   └── Large/
├── UI/
│   ├── BlueprintCategoryTagIcons/
│   └── CraftingTagIcons/
└── Vehicles/

The .dat file's subdirectory path relative to the bundle root should match the Asset_Prefix subpath. The official documentation states: "Unity subfolders should match 1:1 with dat subfolders."

Asset naming convention

Assets within the bundle follow a specific naming convention:

• Prefabs are named descriptively (e.g., Item.prefab, Eaglefire.prefab)
• Materials use the Skin_ prefix pattern (e.g., Skin_Primary.mat)
• Audio clips use descriptive names (e.g., Cave_0.ogg)
• Textures are placed at paths matching their UI role (e.g., UI/BlueprintCategoryTagIcons/Ammo.png)

Per-asset override fields

Individual asset .dat files can override the master bundle lookup behavior through several optional fields.

Field	Type	Purpose
Master_Bundle_Override	string	Name of a master bundle to use rather than the one found in the hierarchy.
Exclude_From_Master_Bundle	flag	If present, the asset looks for an individual .unity3d bundle instead of the hierarchy master bundle.
Bundle_Override_Path	string	Path within the master bundle to load rather than this asset's file path. Used by notes to share a common object prefab, and by holiday tree variants to redirect to seasonal models.
Bundle_Path_Include_Filename	bool	If true, the path within the master bundle appends the asset file name as a subdirectory. Example: Guns/Eaglefire.asset becomes Guns/Eaglefire/Item.prefab.

These override fields provide flexibility for assets that need to reference bundles outside the standard hierarchy or share prefabs with other assets.

Master bundle export workflow

The master bundle is exported from the Unity Editor using the Master Bundle Tool.

Tool access

Open the tool from Window > Unturned > Master Bundle Tool.

Export steps

1. Select directories of assets in the Project window.
2. In the Inspector window, tag the assets in any asset bundle.
3. Click the checkbox next to an asset bundle's name in the tool to mark it as a master bundle. This filters the list of asset bundles and tracks an export path.
4. Click the ... to choose a destination for the bundle file.
5. Click Export.
6. Optionally enable the "multiplatform" toggle for redistributing the asset bundle. This ensures platform-specific shaders are included and exports a .hash file for server-side bundle integrity validation.

Generated files

After exporting a master bundle with the multiplatform option enabled, the following files are generated:

File	Purpose
*.masterbundle	The primary bundle file for the export platform
*_linux.masterbundle	Platform-specific shaders for Linux
*_mac.masterbundle	Platform-specific shaders for macOS
*.masterbundle.hash	Hash file used by the server to verify asset bundle integrity for other platforms
*.masterbundle.manifest	Manifest file listing all assets in the bundle with paths and hashes

The .hash file is critical for server security. Deleting it means malicious clients can modify the asset bundle. The manifest file is useful for debugging mods as it contains file paths of all bundled assets.

Master bundle vs individual asset bundles

Feature	Master bundle	Individual unity3d bundle
File format	.masterbundle	.unity3d
Multiple assets	Yes, unlimited	One asset per file typically
Hierarchy inheritance	Yes (cascading MasterBundle.dat)	No
Asset prefix	Configured in MasterBundle.dat	Bundled by name
Platform support	Multiplatform with .hash validation	Single platform

Most official files have transitioned to the master bundle system. Individual asset bundles are used for per-map road textures, chart colors, and level ambience.

Diagnostic table

Symptom	Most likely cause	Resolution
Asset not found at runtime	Asset path does not match Asset_Prefix + subpath	Verify the asset path in the bundle matches the expected convention
Pink/white materials in-game	Shaders not included in master bundle	Re-export with multiplatform enabled
Asset bundle not found	Asset_Bundle_Name does not match the actual file name	Verify the Asset_Bundle_Name field exactly matches the .masterbundle filename
MasterBundle.dat not read	File is not in a directory the game scans	Place MasterBundle.dat in the correct mod directory
Bundle loads but specific asset is missing	Asset was not included in the bundle export	Re-export with the asset included
Wrong asset loaded	Bundle_Override_Path points to the wrong asset	Correct the override path
Asset uses wrong Unity version features	Asset_Bundle_Version is set to the wrong value	Set to 6 for Unity 2022 LTS
Hash validation fails on server	.hash file is missing or outdated	Re-export with multiplatform enabled

Best practices

• Always set Asset_Bundle_Version to the correct value for the Unity version used to build the bundle.
• Keep Unity subfolder paths matching 1:1 with .dat subfolder paths.
• Enable the multiplatform toggle when redistributing bundles for public use.
• Include the .hash file when distributing bundles to servers.
• Use Master_Bundle_Override sparingly; prefer the hierarchy inheritance model.
• Use Bundle_Override_Path for assets that share common prefabs.
• Document the Asset_Prefix in the mod's project readme.

Frequently asked questions

What is the difference between Asset_Bundle_Version 3 and 6?

Version 3 corresponds to Unity 2018.4 LTS and has shader consolidation enabled for backwards compatibility with older content. Version 6 corresponds to Unity 2022 LTS, which is the current game version. New mods should use version 6.

Can a master bundle contain assets for multiple mods?

Technically yes, but it is not recommended. Each mod should have its own master bundle with its own MasterBundle.dat. Combining multiple mods into a single bundle creates coupling that makes updates and dependency management more difficult.

How does the game resolve asset paths within the bundle?

The engine combines the Asset_Prefix from MasterBundle.dat with the asset's file path relative to the bundle root. If Bundle_Path_Include_Filename is true, the asset's filename (without extension) is also appended as a subdirectory.

What happens if two MasterBundle.dat files exist in the same hierarchy?

The game uses the nearest MasterBundle.dat in the directory hierarchy. If a subdirectory has its own MasterBundle.dat, it overrides any parent MasterBundle.dat for assets in that subdirectory.

Can I use individual .unity3d bundles alongside master bundles?

Yes. An asset can opt out of the master bundle hierarchy by setting the Exclude_From_Master_Bundle flag in its .dat file. This causes the engine to look for a .unity3d bundle with the same name as the .dat file.

How do I verify the contents of a master bundle?

Open the .masterbundle.manifest file that is generated alongside the bundle. This file lists all assets in the bundle with their paths and hashes. The manifest is also useful when debugging master bundle pointers.

What is the maximum size for a master bundle?

There is no hard size limit imposed by the engine, but practical considerations apply. Loading a very large master bundle (multiple gigabytes) will increase load times and memory usage. The vanilla core.masterbundle is 117 MB.

Advanced considerations

The core.masterbundle as a reference

The core.masterbundle is the best reference for understanding how a large, well-organized master bundle is structured. Its Asset_Prefix of Assets/CoreMasterBundle and organized subdirectory structure serve as the template for mod master bundles.

Multiplatform export considerations

Enabling the multiplatform toggle generates separate bundle files for each target platform (Linux, macOS) and a .hash file for server-side integrity validation. The hash file prevents malicious clients from modifying the bundle. Always enable multiplatform for publicly distributed mods.

Bundle version migration

When Unity updates, existing master bundles with older Asset_Bundle_Version values are still loadable because the engine maintains backwards compatibility. However, assets built with older versions may not have access to newer Unity features. Rebuilding the bundle with the current version is recommended for new content.

Appendix A: MasterBundle.dat template

Asset_Bundle_Name modname.masterbundle
Asset_Prefix Assets/[ProjectPath]
Asset_Bundle_Version 6

Master bundle multi-mod compatibility

When multiple mods each have their own master bundles, the following compatibility considerations apply.

Bundle name conflicts

If two mods use the same master bundle filename (e.g., both use mymod.masterbundle), the last-loaded bundle overwrites the first in the engine's bundle registry. Use unique bundle names for each mod to avoid conflicts.

Asset path collisions

If two bundles contain assets with the same internal path, the last-loaded bundle's asset wins. This can be intentional (a mod overriding another mod's assets) or accidental (causing unexpected asset substitutions).

MasterBundle.dat hierarchy rules

The nearest MasterBundle.dat in the directory hierarchy is used. If two mods place their files at different hierarchy levels, they can coexist without conflict. The hierarchy rule ensures that subdirectory bundles do not interfere with parent directory bundles.

Master bundle known issues

The following issues are known to occur with master bundles in certain configurations.

Issue	Workaround
Very large bundles (>1 GB) may cause slow loading	Split assets into multiple smaller bundles
Bundles exported with wrong Unity version may not load	Verify Asset_Bundle_Version is 6 for Unity 2022 LTS
Missing shaders on Linux/macOS	Re-export with multiplatform enabled
Bundle loads but assets are invisible	Check that prefab references in .dat files match bundle content

Appendix B: External references

• Smartly Dressed Games official modding documentation - the official field reference.
• Unturned on Steam - the Unturned store page.
• Master Bundle Export - the companion workflow article.
• Manifest File Reference - the next article.
• Surface Response Chain - the previous article.

Testing master bundle loading

Testing a master bundle requires verifying that the bundle is correctly detected by the game and that all expected assets are loadable.

Step 1: Verify MasterBundle.dat

Confirm that the MasterBundle.dat file is present in the correct directory. Open the file and verify that Asset_Bundle_Name matches the actual .masterbundle filename and that Asset_Prefix matches the Unity project structure.

Step 2: Verify the bundle is loaded

Launch the game and check the console output for any errors related to the master bundle. The game logs a message when it successfully loads a master bundle. If the bundle is not loaded, the console will contain a "Missing master bundle" warning.

Step 3: Verify individual asset loading

Spawn or encounter each asset type that is included in the bundle. Confirm that models, textures, audio, and prefabs all load correctly. Check for pink materials (missing shaders) or missing model errors.

Step 4: Verify override paths

If any assets use Bundle_Override_Path or Master_Bundle_Override, test those assets specifically to confirm the override resolves correctly.

Master bundle common configurations

The following table documents common master bundle configurations for different project types.

Single-item mod

For a mod that contains a single item (one gun, one melee weapon, one vehicle), the master bundle contains the prefab, materials, and textures for that one item. The Asset_Prefix should point to the Unity project folder containing those assets.

Multi-item mod pack

For a mod pack containing multiple items, the master bundle includes all items' prefabs. The project structure within Unity should use subfolders to organize assets by item type. The Asset_Prefix should point to the common root folder.

Map mod

For a map mod, the master bundle includes map-specific assets (trees, resources, custom objects, terrain materials). The bundle is typically larger and may require streaming loading configuration.

Project type	Typical bundle size	Typical asset count	Asset_Prefix convention
Single item	1-50 MB	1-10 assets	Assets/[ModName]/Items/[ItemName]
Multi-item pack	10-500 MB	10-100 assets	Assets/[ModName]/
Map mod	100 MB - 2 GB	100-1000+ assets	Assets/[ModName]/

Glossary

Term	Definition
MasterBundle.dat	A configuration file that declares the master bundle's name, asset prefix, and Unity version.
Asset_Bundle_Name	The filename of the master bundle file to load.
Asset_Prefix	The Unity project path root for assets within the bundle.
Asset_Bundle_Version	The Unity version identifier for bundle compatibility.
Bundle_Override_Path	A per-asset field that redirects the asset's model to an alternative prefab path.
Master_Bundle_Override	A per-asset field that specifies a different master bundle to use.
Exclude_From_Master_Bundle	A flag that causes an asset to use an individual .unity3d bundle instead.
Bundle_Path_Include_Filename	A flag that appends the asset filename as a subdirectory in the bundle path.
Multiplatform	An export option that generates platform-specific shader variants and a .hash file.
AssetBundle	A Unity file format that packages multiple assets into a single file for runtime loading.

Authoring checklist

• [ ] MasterBundle.dat has correct Asset_Bundle_Name matching the .masterbundle filename
• [ ] Asset_Prefix matches the Unity project folder structure
• [ ] Asset_Bundle_Version is set to 6 for Unity 2022 LTS
• [ ] Unity subfolder paths match 1:1 with .dat subfolder paths
• [ ] Multiplatform toggle enabled for public distribution
• [ ] .hash file included in the distribution
• [ ] Override fields (Bundle_Override_Path, Master_Bundle_Override) are correctly configured

Master bundle version migration guide

When upgrading a mod from an older Unity version to the current Unity 2022 LTS, the master bundle must be migrated to the new format.

Step 1: Update the Unity project

Open the existing Unity project in Unity 2022 LTS. Unity upgrades the project files automatically. Check the console for any upgrade warnings related to assets or scripts.

Step 2: Update Asset_Bundle_Version

Change Asset_Bundle_Version from the old value to 6 (Unity 2022 LTS).

Step 3: Rebuild the bundle

Export the master bundle again using the Master Bundle Tool. The new bundle is in format version 6.

Step 4: Verify all assets

Test every asset that was in the previous bundle to confirm it loads and renders correctly in the new format.

Frequently asked questions (continued)

Can I have multiple master bundles in one mod directory?

Yes. The game scans for MasterBundle.dat in each directory. Multiple MasterBundle.dat files in different subdirectories each define their own master bundle. This is useful for separating different categories of assets into different bundles.

What happens if Asset_Bundle_Name is wrong?

The game logs a warning and does not load the bundle. The assets that depend on that bundle will fail to load their models, textures, and other Unity assets.

How does the game resolve the Asset_Prefix?

The Asset_Prefix is combined with the asset's relative path to construct the full lookup path within the bundle. For example, if Asset_Prefix is Assets/CoreMasterBundle and the .dat file is at Items/Guns/Eaglefire/, the engine looks for Assets/CoreMasterBundle/Items/Guns/Eaglefire/Item.prefab in the bundle.

Can I change the Asset_Prefix after export?

No. The Asset_Prefix is baked into the bundle at export time. Changing the Asset_Prefix in MasterBundle.dat without rebuilding the bundle will break asset resolution.

Do I need to include .metadata files in the master bundle?

No. Unity editor metadata files are not included in asset bundles. They are Unity Editor files that track asset metadata and are not needed at runtime.

Master bundle design patterns

The single-bundle pattern

One master bundle contains all assets for the mod. This is the simplest pattern and appropriate for small to medium mods. The MasterBundle.dat is placed at the mod root level.

The multi-bundle pattern

Multiple master bundles organized by asset category. For example, one bundle for item models and textures, another for audio clips. Each bundle has its own MasterBundle.dat. This pattern is useful for large mods where different asset categories have different update frequencies.

The shared-bundle pattern

Multiple mods share a single master bundle. The bundle is placed in a shared directory that all mods can access. Each mod's MasterBundle.dat or per-asset Master_Bundle_Override points to the shared bundle.

Performance considerations

Master bundle loading performance is affected by bundle size and asset count. The following factors influence load time.

Factor	Impact	Recommendation
Bundle file size	Larger files take longer to read from disk	Keep bundles under 500 MB for reasonable load times
Asset count	More assets = longer content table parsing	Organize assets into logical groups
Texture resolution	High-res textures increase bundle size	Follow the curated items resolution guidelines
Audio clip length	Long audio clips increase bundle size	Stream long audio clips instead of including them in the bundle
Shader count	Multiplatform exports include shader variants	Accept the size increase for cross-platform compatibility

Quick reference

This article provides a comprehensive reference for the topics covered. Key concepts include understanding the field types, required vs optional fields, default values, and how fields interact with each other. Always cross-reference field values against the official SDG documentation and test changes in both single-player and multiplayer environments before publishing.

Cross-references

• Surface Response Chain - the previous article.
• Manifest File Reference - the next article.
• Master Bundle Export - the export workflow.
• Asset Bundles Reference - bundle system fundamentals.

Master bundle security considerations

When distributing master bundles publicly, several security considerations protect the mod's content from tampering.

Hash file importance

The .hash file generated with multiplatform export is critical for server security. Deleting the .hash file means malicious clients can modify the asset bundle by replacing materials to make certain objects glow in the dark or become transparent. Always include the .hash file when distributing bundles for server use.

Asset Bundle Custom Data

The Asset Bundle Custom Data system can embed the original Workshop file ID into the bundle. When a server attempts to download the mod, the game verifies that the Workshop file ID matches. This prevents unauthorized re-uploading of the mod to the Workshop.

Bundle integrity on dedicated servers

The server validates client asset bundle integrity using the .hash file. Clients with modified bundles are rejected by the server. This protects the server's gameplay environment from malicious clients using modified assets.

Master bundle roadmap for new mod authors

For new mod authors creating their first master bundle, the following roadmap provides a structured approach.

Week 1: Unity project setup

Install Unity 2022 LTS. Import the Project.unitypackage from the Unturned installation directory. Set up the project structure with the correct Asset_Prefix.

Week 2: Asset authoring and import

Create or import the 3D models, textures, and audio clips. Set up prefabs with the correct tags and layers. Assign assets to asset bundles in the Unity Inspector.

Week 3: First export

Export the master bundle using the Master Bundle Tool with multiplatform enabled. Verify the manifest file lists all expected assets. Test the bundle in-game.

Week 4: Iteration

Make changes based on in-game testing. Iterate on assets and re-export. Each export produces a new manifest that can be compared against the previous version.

Quick reference

This article provides a comprehensive reference for the topics covered. Key concepts include understanding the field types, required vs optional fields, default values, and how fields interact with each other. Always cross-reference field values against the official SDG documentation and test changes in both single-player and multiplayer environments before publishing.

Cross-references

| Version | Date | Author | Notes | |---|---|---|---|---| | 1.0 | 2026-07-26 | 57 Studios | Initial publication. Complete master bundle internal structure, MasterBundle.dat declaration, loading chain, internal organization, export workflow. |

Document history

Version	Date	Author	Notes
1.0	2026-07-26	57 Studios	Initial publication. Complete master bundle internal structure, MasterBundle.dat declaration, loading chain, internal organization, export workflow.