Modding Workflow: End-to-End

Intermediate40-60 minutesWindowsNotepad++Unity Editor

The Unturned™ modding workflow spans five distinct hops that transform a Unity project asset into a playable in-game item. Each hop produces an artifact that the next hop consumes: Unity project assets become .unity3d or .masterbundle files; asset definitions become .dat files; the .dat files reference the bundle assets; the bundle and .dat files are placed in the game's mod directory; and the game loads and validates everything at startup.

57 Studios™ has documented the complete end-to-end workflow across all five hops, covering the content identity chain from authoring to testing. This article walks through the entire pipeline using a single item as a trace example, identifies common failure points at each hop, and provides a Mermaid flowchart of the full workflow sequence.

Documentation source: This article synthesizes information from the official Smartly Dressed Games modding documentation across multiple sections: Asset Bundles (Chapter 4), Asset Definitions (Chapter 5), Data File Format (Chapter 6), and Introduction to Items (Chapter 14).

Who this article is for

This article is written for new Unturned™ mod authors who have not yet completed a full modding workflow, experienced mod authors who want a reference checklist, and anyone troubleshooting why a mod that loads correctly in the Unity Editor does not appear in-game.

The five-hop workflow

Hop 1: Unity Project

The workflow begins in the Unity Editor. The mod author creates or imports 3D models, textures, materials, audio clips, and animation files into a Unity project. The project must use the same Unity version that Unturned™ uses (currently Unity 2022 LTS). Assets are organized in folders that mirror the intended in-game structure.

Hop 2: Master Bundle Export

Using the Master Bundle Tool (Window > Unturned > Master Bundle Tool), the mod author tags assets for bundling, configures the export path, and builds the .masterbundle file. The export generates the bundle file, optional platform-specific files, and the .manifest and .hash files.

Hop 3: .dat Authoring

The mod author creates .dat files that define the asset's properties: GUID, Type, ID, and all gameplay-specific fields. The .dat file's Name field (or the folder name) links to the prefab name in the bundle. The English.dat file provides the display name and description.

Hop 4: Mod Directory Setup

The .dat files and the master bundle are placed in the correct mod directory structure under Workshop/Content/304930/<modID>/. The directory structure must match the structure expected by the game's asset scanning system.

Hop 5: Game Load and Validation

The game scans the mod directory at startup, loads the master bundle, parses the .dat files, validates GUIDs and IDs, and registers the assets. If validation fails, the asset may load with default values or not appear at all.

Worked trace example: creating a custom gun

The following trace follows a custom gun item through all five hops.

Hop 1: Unity Project

The mod author creates a Unity project with a 3D model of the gun, a texture, and a material. The model is set up as a prefab named Item with the correct tag (4: Item) and layer (13: Item). An animations prefab is created with an Equip animation. An Equip audio clip is included.

Assets/MyGunMod/
├── MyGun.fbx (3D model)
├── MyGun_Albedo.png (texture)
├── MyGun_Metallic.png (metallic texture)
├── Item.prefab (tagged as 4: Item, layered as 13: Item)
└── Animations.prefab (with Equip animation)

Hop 2: Master Bundle Export

The mod author selects the Assets/MyGunMod folder in the Unity Project window, tags it in an asset bundle named mygunmod, enables the master bundle checkbox, chooses an export destination, and clicks Export. The following files are generated:

mygunmod.masterbundle
mygunmod.masterbundle.manifest

Hop 3: .dat Authoring

The mod author creates the gun's .dat file:

GUID a1b2c3d4e5f64a7b8c9d0e1f2a3b4c5d
Type Gun
ID 50001
Name MyGun
Rarity Common
Slot Primary
Size_X 4
Size_Y 2
Player_Damage 40
Zombie_Damage 50
Caliber 5001
Magazine_Caliber_ID 5001

And the English.dat file:

Name My Custom Gun
Description A custom assault rifle with custom stats.

Hop 4: Mod Directory Setup

The mod author creates the directory structure:

Workshop/Content/304930/1234567890/
├── Bundles/
│   └── mygunmod.masterbundle
├── Items/
│   └── MyGun/
│       ├── Asset.dat
│       └── English.dat
└── Workshop.dat

Hop 5: Game Load and Validation

The mod author launches Unturned™ in single-player mode. The game scans the mod directory, finds the Asset.dat file, loads the mygunmod.masterbundle, registers the gun asset with GUID a1b2c3d4..., and makes it available. The mod author spawns the gun with @give 50001 and verifies it appears correctly.

Common failure points

Hop	Failure point	Symptom	Resolution
1	Wrong Unity version	Bundle loads but assets are invisible or broken	Check ProjectSettings/ProjectVersion.txt against the Unturned version
1	Missing tag/layer on prefab	Item does not render correctly when equipped	Set tag to 4: Item, layer to 13: Item
2	Export path incorrect	Bundle file not found at runtime	Verify MasterBundle.dat points to the correct file name
2	Assets not selected for bundling	Bundle exports but missing assets	Verify assets are tagged in an asset bundle
2	Multiplatform not enabled	Shaders missing on other platforms	Re-export with multiplatform enabled
3	GUID conflict	Another asset overwrites this one	Generate a fresh, unique GUID
3	ID conflict	Another item uses the same ID	Use IDs in the 50000+ range
3	Type mismatch	Parser does not recognize the fields	Use the correct Type value
4	Wrong folder structure	Asset not found by the game scanner	Follow the Workshop/Content/304930/<ID>/ convention
4	Missing MasterBundle.dat	Master bundle not loaded	Add MasterBundle.dat in the Bundles directory
5	Asset loads but does not appear	The asset registered but is not spawnable	Verify the Type and Useable fields
5	Asset appears with wrong stats	Default values used due to invalid fields	Check the engine log for parsing errors

Best practices

• Use the same Unity version as the current Unturned release (2022 LTS).
• Generate a fresh GUID for every new asset.
• Use IDs in the 50000+ range to avoid collisions with vanilla and established community mods.
• Test each hop independently before proceeding to the next.
• Keep the Unity project, the .dat files, and the bundle export in version control.
• Document the asset's GUID and ID in a project-level registry file.
• Verify the manifest file after each export to confirm all assets are included.

Frequently asked questions

What is the minimum toolchain for modding?

The minimum toolchain is a text editor (Notepad++ or equivalent) for .dat files and the Unity Editor (Unity 2022 LTS) for asset bundling. No additional tools are required for basic item mods. Vehicle mods and complex items may require a 3D modeling tool (Blender) and an image editor (GIMP or Photoshop).

Do I need to rebuild the master bundle for every .dat change?

No. .dat files are loaded separately from the master bundle. Changes to .dat fields (stats, IDs, names) take effect on the next game launch without rebuilding the bundle. Only changes to 3D models, textures, or other Unity assets require a bundle rebuild.

How do I know which Unity version Unturned uses?

Check ProjectSettings/ProjectVersion.txt in the Unity project provided by SDG. The current version is Unity 2022 LTS. The Asset_Bundle_Version value 6 corresponds to this version.

What happens if I skip the MasterBundle.dat file?

Without a MasterBundle.dat, the game does not know to look for a master bundle in that directory. The game will fall back to looking for individual .unity3d bundles, which may not exist for your mod. Always include a MasterBundle.dat when using master bundles.

Can I skip the Unity project and hand-author a master bundle?

No. Master bundles are Unity AssetBundle files that must be built through the Unity Editor. There is no supported way to hand-author or reverse-engineer a valid master bundle. The Unity Editor is a mandatory tool in the workflow.

Workflow troubleshooting by hop

Each hop in the modding workflow has specific failure modes and diagnostic techniques.

Hop 1 troubleshooting (Unity Project)

If the Unity project has missing scripts or references, the bundle may fail to build. Check the Unity Console for errors before attempting to export. Verify that all prefabs have the correct tag (4: Item) and layer (13: Item).

Hop 2 troubleshooting (Master Bundle Export)

If the export produces a bundle file with zero bytes or a very small file size, the selected assets may not have been properly tagged for bundling. Verify that each asset folder is assigned to an asset bundle in the Unity Inspector using the AssetBundle dropdown.

Hop 3 troubleshooting (.dat Authoring)

If the game logs parsing errors for the .dat file, verify that all braces and brackets are balanced, all field names are spelled correctly, and all values match their expected types.

Hop 4 troubleshooting (Mod Directory Setup)

If the game does not scan the mod directory, verify the folder structure follows the Workshop/Content/304930/<ID>/ convention. The <ID> can be any unique value for local testing.

Hop 5 troubleshooting (Game Load)

If the asset loads but does not appear in the game, check the console for warnings about missing master bundle pointers, incorrect Type fields, or ID conflicts.

Workflow optimization for different mod types

The modding workflow can be optimized for different mod types by adjusting the emphasis on each hop.

Fast item mod (text only)

A mod that modifies only .dat fields (changing stats, adding localization) without changing 3D assets can skip Hop 1 and Hop 2 entirely. The mod author only needs to create the .dat file and set up the directory structure.

Texture replacement mod

A mod that replaces textures without changing models only requires Hops 1, 2, 4, and 5. The Unity project only needs the new texture and the material file; no model changes are needed.

Full 3D model mod

A mod with custom 3D models requires all five hops. The model authoring in Hop 1 is the most time-consuming phase.

Vehicle mod

Vehicle mods follow the same five-hop workflow but the Unity project is more complex, requiring wheel colliders, engine components, and vehicle-specific scripts.

Modding workflow design patterns

The incremental iteration pattern

Make one change at a time and test after each change. This pattern minimizes the debugging scope when something breaks. For example, change the Player_Damage field in the .dat file, test the change, then move to the next field.

The template-first pattern

Create template .dat files for each asset type based on the field reference articles in this knowledge base. Copy the template for each new asset and fill in the values. This pattern reduces authoring errors by providing a complete starting point.

The export-once pattern for .dat-only changes

Since .dat files are loaded separately from the master bundle, .dat-only changes do not require a bundle rebuild. The mod author can iterate on .dat values rapidly without the overhead of the Unity export pipeline.

Appendix A: Workflow hop reference

Hop	Input	Output	Tool
1	3D model, textures, materials	Unity prefabs	Unity Editor, Blender, GIMP
2	Unity prefabs	.masterbundle file	Unity Master Bundle Tool
3	Asset specifications	.dat file, English.dat	Text editor
4	.dat, .masterbundle	Mod directory structure	File Explorer
5	Mod directory	Loaded in-game assets	Game engine

Appendix B: External references

• Smartly Dressed Games official modding documentation - the official field reference.
• Unturned on Steam - the Unturned store page.
• Manifest File Reference - the previous article.
• Mod Project Directory Structure - the next article.
• Master Bundle Export - detailed export workflow.

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

• Manifest File Reference - the previous article.
• Mod Project Directory Structure - the next article.
• Master Bundle Export - detailed export workflow.
• Asset Definitions Reference - .dat file format.
• Data File Format Reference - .dat syntax.

Document history

Version	Date	Author	Notes
1.0	2026-07-26	57 Studios	Initial publication. Complete five-hop workflow, trace example, failure point table, best practices.