Mod Project Directory Structure

Intermediate40-60 minutesWindowsNotepad++Unity Editor

The Unturned™ mod project directory structure is the organizational framework that determines how the game finds, loads, and resolves assets. The directory path from the mod root to the asset file drives three linked resolutions: the folder name maps to the .dat filename, the .dat file's Name field maps to the Unity prefab lookup within the master bundle, and the bundle's Asset_Prefix combined with the asset's relative path resolves to the actual bundle content.

57 Studios™ has documented the complete directory structure conventions across all item types, the mapping from folder structure to bundle paths, and the directory conventions per asset type. This article covers both the Workshop deployment structure and the Unity project source structure.

Documentation source: This article references the official Smartly Dressed Games modding documentation and analysis of the shipped game file directory structure.

The folder-to-bundle path mapping chain

The game's asset resolution follows a three-step mapping chain from folder name to in-game asset.

Step 1: Folder name to .dat file name

The game scans a folder for asset files in this order:

1. Is there a .asset file with the same name as the folder? (e.g., Eaglefire.asset in the Eaglefire folder)
2. Is there a .dat file with the same name as the folder? (e.g., Eaglefire.dat in the Eaglefire folder)
3. Is there an Asset.dat file?
4. Otherwise, load all files with the .asset extension in the folder.

The convention across the shipped assets is to use Asset.dat as the filename inside the item's folder.

Step 2: .dat file to prefab name

The .dat file's Name field (or the folder name if Name is not set) determines which prefab in the master bundle is loaded. The Model field can override this lookup if the prefab name differs from the Name field.

Step 3: Prefab to bundle path

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

Workshop deployment directory structure

The deployment directory structure for a published Workshop mod follows this convention:

Workshop/Content/304930/<WorkshopFileID>/
├── Bundles/
│   ├── MasterBundle.dat
│   └── <modname>.masterbundle
├── Items/
│   ├── <ItemName>/
│   │   ├── Asset.dat
│   │   ├── English.dat
│   │   └── <ItemName>.unity3d (optional, if not using master bundle)
│   ├── <AnotherItem>/
│   │   ├── Asset.dat
│   │   └── English.dat
│   └── ...
├── Vehicles/ (if applicable)
│   └── ...
└── Workshop.dat

Workshop.dat

The Workshop.dat file at the mod root level contains the Workshop metadata:

GUID <mod-guid>
name My Mod
description My mod description
version 1.0.0

Unity project source directory structure

The Unity project structure mirrors the deployment structure within the Assets/ directory.

Assets/
├── CoreMasterBundle/          ← matched by Asset_Prefix
│   ├── Items/
│   │   ├── Guns/
│   │   ├── Melee/
│   │   ├── Magazines/
│   │   └── ...
│   ├── Vehicles/
│   ├── Effects/
│   └── UI/
├── Game/
│   └── Sources/               ← source files (.blend, .psd, etc.)
│       └── Items/
│           └── ...
└── Resources/                 ← Unity Resources (avoid adding new files here)

The official documentation recommends organizing the project into two separate folders: one for exported asset-bundled files (e.g., Item.prefab) and one for imported sources (e.g., .blend files). This separation ensures only the necessary assets are included in the bundle.

Per-asset-type directory conventions

Asset type	Deployment path	Unity project path
Guns	Items/Guns/<GunName>/	CoreMasterBundle/Items/Guns/<GunName>/
Melee	Items/Melee/<WeaponName>/	CoreMasterBundle/Items/Melee/<WeaponName>/
Magazines	Items/Magazines/<MagName>/	CoreMasterBundle/Items/Magazines/<MagName>/
Clothing	Items/<ClothingType>/<ItemName>/	CoreMasterBundle/Items/<ClothingType>/<ItemName>/
Outfits	Items/Outfits/<OutfitName>/	CoreMasterBundle/Items/Outfits/<OutfitName>/
Vehicles	Vehicles/<VehicleName>/	CoreMasterBundle/Vehicles/<VehicleName>/
Effects	Effects/<Category>/<EffectName>/	CoreMasterBundle/Effects/<Category>/<EffectName>/

Diagnostic table

Symptom	Most likely cause	Resolution
Asset not found by game	Folder structure does not match convention	Follow the Items/<Type>/<Name>/ pattern
Wrong prefab loaded	Name field in .dat does not match prefab name	Set Name to match the prefab name, or use Model override
Bundle not loaded	MasterBundle.dat missing from Bundles directory	Create MasterBundle.dat with correct Asset_Bundle_Name
Asset path mismatch in bundle	Unity subfolder does not match .dat subfolder	Ensure 1:1 correspondence between Unity paths and .dat paths
Workshop upload fails	Workshop.dat missing or incorrectly formatted	Include Workshop.dat with correct metadata
Multiple items share same folder name	Asset loading conflicts	Use unique folder names for each item

Best practices

• Use Asset.dat as the standard filename inside each item folder.
• Ensure folder names are unique and descriptive.
• Match Unity project subfolder paths to .dat subfolder paths 1:1.
• Keep source files separate from bundled files in the Unity project.
• Include a MasterBundle.dat in every mod's Bundles directory.
• Version control both the Unity project and the deployment directory.

Frequently asked questions

Can I use a flat directory structure (no subfolders)?

The game scans directories recursively. A flat structure without subfolder organization will work but makes maintenance difficult for multi-item mods. The recommended structure uses per-item subfolders.

What happens if two items have the same folder name?

If two items in the same mod have the same folder name, the second item's files may overwrite the first during asset loading. Always use unique folder names within a mod.

Do I need both a master bundle and individual .unity3d files?

No. Master bundles replace the need for individual .unity3d files. The Exclude_From_Master_Bundle flag can be used to opt specific assets out of the master bundle system, but the recommendation is to use master bundles for all content.

Where should I place map-specific assets?

Map-specific assets should be placed in a folder named after the map. The official convention for curated map items uses a per-map folder prefix (e.g., Arid/Arid_Arrowhead).

Can I share a master bundle across multiple Workshop items?

Yes. Multiple Workshop items can reference the same master bundle file. The bundle file should be placed in a shared location that all items can access.

Appendix A: Asset.dat loading order reference

Order	File type	Notes
1	<FolderName>.asset	Asset file matching folder name
2	<FolderName>.dat	Dat file matching folder name
3	Asset.dat	Generic asset file
4	All .asset files	Fallback: load all assets

Appendix B: External references

• Smartly Dressed Games official modding documentation - the official field reference.
• Unturned on Steam - the Unturned store page.
• Modding Workflow: End-to-End - the previous article.
• Local Asset Testing Workflow - the next article.
• Project Folder Structure and GUIDs - related guidance.

Directory structure design patterns

The single-item pattern

For a mod that contains exactly one item, the directory structure is minimal:

Bundles/
├── MasterBundle.dat
└── modname.masterbundle
Items/
└── ItemName/
    ├── Asset.dat
    └── English.dat

This pattern is appropriate for small, focused mods that add a single item to the game.

The multi-item organization pattern

For a mod pack with multiple items, organize items into subdirectories by type:

Items/
├── Guns/
│   ├── MyRifle/
│   └── MyPistol/
├── Melee/
│   └── MyKnife/
├── Magazines/
│   ├── MyRifleMag/
│   └── MyPistolMag/
└── Clothing/
    ├── MyShirt/
    └── MyHat/

This pattern mirrors the vanilla game's organizational structure and makes the mod easier to maintain.

The curated item pattern

For items submitted for curated status in the Stockpile, the directory structure follows the convention documented in the curated items guidelines:

Items/Outfits/<OutfitName>/
└── <OutfitName>_<ItemType>/
    ├── Asset.dat
    └── English.dat

Directory structure versioning and migration

When updating a mod that changes the directory structure, the following considerations apply.

Adding new items

Adding a new item to an existing mod requires creating a new folder with its Asset.dat and English.dat files. The master bundle must be rebuilt if the new item uses new Unity assets.

Renaming items

If an item folder is renamed, the old folder's assets will not be found by the game after the update. Players who update the mod will see the item disappear from their inventories if the save data references the old folder name.

Removing items

Removing an item folder from the mod removes that item from the game for players who update. Any instances of that item in existing saves will be lost or converted to a fallback state.

Directory structure troubleshooting

Common directory structure errors

Error	Cause	Fix
Asset not found	Folder name does not match .dat filename convention	Use Asset.dat as the filename
Bundle not loaded	MasterBundle.dat in wrong location	Place it in the Bundles/ directory
Item appears with wrong name	English.dat missing or Name field incorrect	Create English.dat with correct Name
Workshop upload fails	Workshop.dat missing or malformed	Verify Workshop.dat contains correct metadata
Multiple items conflict	Same folder name used twice	Use unique folder names for each item

Glossary

Term	Definition
Asset.dat	The standard filename for item configuration files in per-item folders.
English.dat	The localization file providing the item's display name and description.
Workshop.dat	The metadata file for Workshop-distributed mods.
MasterBundle.dat	The configuration file that declares a master bundle's properties.
Folder-to-bundle mapping	The resolution chain from folder name to .dat file to bundle prefab.
Asset scanning order	The order in which the game searches for asset files in a directory.
Unity project root	The top-level Assets folder in the Unity Editor project.
Source files	Authoring files (.blend, .psd) that are separate from bundled delivery files.

Authoring checklist

• [ ] Each item has its own uniquely named folder
• [ ] Asset.dat is present in each item folder
• [ ] English.dat is present in each item folder
• [ ] MasterBundle.dat is present in the Bundles directory
• [ ] Unity project subfolder paths match .dat subfolder paths
• [ ] Source files are separate from bundled files
• [ ] Workshop.dat is present for Workshop-distributed mods

Integration with other systems

This configuration interacts with several other Unturned systems that the mod author should be aware of when designing content.

Interaction with the asset definition system

Every configuration file must include the required identity fields that the asset definition system uses to register the asset in the game's registry. Without these fields, the asset is not recognized by the game and will not appear in any system that references it.

Interaction with the localization system

Configuration files that display text to the player must be paired with localization files. The English.dat file provides the default language display values. Additional language files can be added for multilingual support.

Interaction with the master bundle system

Configuration files that reference Unity assets must use master bundle pointers correctly. The asset path in the pointer must match the path in the master bundle's manifest. A mismatch causes the asset to fail to load without crashing the game.

Interaction with the validation system

The game validates configuration files during the loading phase. Validation errors produce warnings in the console but do not prevent the game from starting. The affected asset may use default values for invalid fields.

Performance considerations

Configuration file performance is determined by the complexity of the referenced assets and the number of active instances in the game world.

Memory footprint

Each loaded asset occupies memory proportional to its data size. Configuration files are small (a few kilobytes each) and do not significantly impact memory usage. The memory impact comes from the Unity assets (models, textures, audio) that the configuration files reference.

Loading time

The game parses all configuration files during the initial loading phase. The total parsing time is proportional to the total number of configuration files and their complexity. For most mods, this overhead is negligible (milliseconds to low seconds).

Runtime performance

The runtime performance impact of a configuration file is zero for static properties and minimal for properties that are evaluated per-frame. Field values are cached after the initial read and are not re-read each frame.

Testing and validation

A structured testing approach ensures that every configuration value produces the expected behavior.

Unit testing

Test each configuration field independently by changing one value at a time and observing the result. This isolates the effect of each field and makes it easy to identify which field is responsible for unexpected behavior.

Integration testing

Test the complete configuration with all fields set to their intended values. Verify that the combination of fields produces the expected overall behavior.

Regression testing

After making changes, re-test previously working behavior to confirm that the changes did not break existing functionality. A change that fixes one issue should not introduce new issues in unrelated areas.

Stress testing

Test the configuration under high-load conditions (many concurrent players, rapid interactions) to verify that no performance issues or crashes occur.

Common authoring mistakes

Mistake 1: Missing identity fields

The most common authoring mistake is omitting required identity fields. Without a GUID, Type, and ID, the asset cannot be registered in the game's asset registry.

Mistake 2: Incorrect Type values

The Type field must match the expected value for the asset class being defined. An incorrect Type value causes the parser to misread the configuration fields.

Mistake 3: GUID collisions

Two assets with the same GUID cause the later-loaded asset to overwrite the earlier one. Generate fresh GUIDs for every new asset and never reuse GUIDs.

Mistake 4: ID collisions

Two items with the same ID within the same category cause unpredictable behavior. Use IDs in the 50000+ range to avoid collisions with vanilla and established community mods.

Mistake 5: Invalid field values

Field values must match their expected types. A string value in a numeric field is silently ignored and replaced with the default value.

Mistake 6: Unbalanced braces

Dictionaries opened with { must be closed with }. Lists opened with [ must be closed with ]. Unbalanced braces cause parsing errors that prevent the asset from loading.

Mistake 7: Incorrect master bundle pointers

The AssetPath in a master bundle pointer must match the path in the bundle's manifest exactly. Even a single-character difference causes the reference to fail.

Mistake 8: Missing localization files

Assets that display text to the player should have a corresponding English.dat file. Without it, the asset may display an internal identifier instead of a user-friendly name.

Design patterns

The completeness pattern

Before declaring a configuration file complete, verify that every field that has a documented default value has been explicitly considered. Some fields should use their defaults; others need explicit values. The decision should be intentional.

The documentation pattern

Maintain a project-level documentation file that records the purpose and expected values for every field in every configuration file. This documentation helps other mod authors understand the design intent.

The version control pattern

Store all configuration files in a version control system (Git). Every change is tracked with a commit message that explains why the change was made. This creates a complete history of the project's evolution.

The peer review pattern

Before finalizing a configuration, have another mod author review the file. A reviewer may spot errors that the original author missed, particularly in field values that were changed recently and may have unintended interactions.

Frequently asked questions (continued)

How do I know if my configuration file is correct?

The game logs any parsing errors or validation warnings during startup. Check the console output after launching the game. If no errors or warnings related to your mod appear, the configuration file is syntactically correct.

What happens when a field is omitted from a configuration file?

The parser assigns the default value for that field. Default values are documented in the field reference tables in this knowledge base. If you omit a field, the behavior may not match your intent.

Can I include comments in configuration files?

Yes. Lines starting with // are treated as comments. Comments can also be added at the end of a line if the value is enclosed in quotes.

How do I create a minimal configuration file?

The minimal configuration file contains only the required identity fields (GUID, Type, ID) and the fields that must differ from their defaults. All other fields use their default values.

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

.dat files use the original Unturned key-value pair format. .asset files use the newer format that supports dictionaries, lists, and quoted keys/values. Both formats are valid and the parser handles both.

Glossary

Term	Definition
Configuration file	A text file containing key-value pairs that define an asset's properties.
Identity field	A required field (GUID, Type, ID) that identifies the asset to the engine.
Default value	The value used when a field is not explicitly specified in the configuration file.
Parsing error	An error that occurs when the file format is invalid or a value cannot be interpreted.
Validation warning	A warning that occurs when a parsed value is out of range or inconsistent.
Field reference	A table that documents each field's name, type, allowed values, and purpose.
Asset registry	The game's in-memory database of all loaded assets.
Master bundle pointer	A structured reference to an asset within a master bundle file.
Localization	The system for providing language-specific display text for assets.
Template	A pre-written configuration file with placeholder values.

Implementation roadmap

Phase 1: Research

Read the relevant reference article for the asset type. Understand the purpose of every field before writing any configuration values.

Phase 2: Planning

List the required and optional fields that need values. Determine the correct values based on the intended behavior.

Phase 3: Authoring

Create the configuration file. Fill in the identity fields first, then the gameplay fields, then the optional fields.

Phase 4: Validation

Check the configuration file for syntax errors. Verify that all braces and brackets are balanced. Confirm that all values match their expected types.

Phase 5: Testing

Place the configuration file in the mod directory. Launch the game and check for errors. Test the asset's behavior in-game.

Phase 6: Iteration

Adjust field values based on testing feedback. Repeat phases 4 and 5 until the behavior matches the intended design.

Authoring checklist

Before finalizing a configuration file for publication, confirm the following items:

• [ ] All identity fields are present (GUID, Type, ID)
• [ ] GUID is unique and freshly generated
• [ ] Type field matches the expected asset class
• [ ] ID is in the 50000+ range
• [ ] All gameplay fields have intentional values (not accidentally omitted)
• [ ] Master bundle pointers are correctly configured and paths match the manifest
• [ ] Localization file is present and contains the expected fields
• [ ] Testing has confirmed every field produces the expected behavior
• [ ] No parsing errors or validation warnings in the console
• [ ] The asset works in both single-player and multiplayer

Troubleshooting common issues

Issue: Asset does not appear in game

If the asset does not appear after following all configuration steps, check the console output for error messages. Common causes include incorrect directory structure, missing MasterBundle.dat, or invalid GUID format.

Issue: Asset appears with wrong values

If the asset appears but behaves differently than expected, check that all field values are spelled correctly and are within valid ranges. The parser silently ignores fields with incorrect names and applies the default value instead.

Issue: Asset works in single-player but not on server

Multiplayer issues are often caused by missing files on the server. Copy all configuration files and master bundles to the server's mod directory. Verify that the server and client have the same mod version.

Issue: Asset causes game crash

If an asset causes the game to crash, check for the following: extremely large field values (such as very high damage numbers), nested dictionaries that exceed the parser's recursion limit, or master bundle references to nonexistent assets.

Validation checklist

Before publishing an asset or configuration, run through this checklist to catch common issues.

• [ ] Configuration file syntax is valid (braces balanced, quotes matched)
• [ ] GUID is 32 hexadecimal characters, no hyphens, no spaces
• [ ] Type field uses the correct class name
• [ ] ID is numeric and does not conflict with other items
• [ ] All referenced GUIDs point to existing, loaded assets
• [ ] Master bundle pointer paths match the manifest exactly
• [ ] Localization file contains all required text entries
• [ ] Asset has been tested in single-player
• [ ] Asset has been tested in multiplayer
• [ ] Console log shows no errors or warnings related to the asset

Glossary

Term	Definition
Asset	A data entity registered in the game's asset system with a unique GUID and Type.
Configuration	The set of key-value pairs that define an asset's properties and behavior.
Default value	The value applied by the parser when a field is omitted from the configuration.
Parsing	The process of reading and interpreting a configuration file's key-value pairs.
Registry	The in-memory database of all loaded assets, indexed by GUID.
Validation	The process of checking that parsed values are within allowed ranges.
Master bundle	A Unity AssetBundle file containing packaged game assets.
Localization	Language-specific display text for assets.
Manifest	A file listing all assets in a master bundle with their paths and types.
Workshop	The Steam platform for distributing mods to players.

Cross-references

• Modding Workflow: End-to-End - previous article.
• Local Asset Testing Workflow - next article.
• Project Folder Structure and GUIDs - related guidance.
• Master Bundle Internal Structure - bundle architecture.

Document history

Version	Date	Author	Notes
1.0	2026-07-26	57 Studios	Initial publication. Complete directory structure reference, folder-to-bundle mapping chain, per-asset-type conventions, Unity project organization.