Local Asset Testing Workflow

Intermediate40-60 minutesWindowsNotepad++Unity Editor

Testing Unturned™ mod assets locally before submitting them to the Steam Workshop is a critical quality assurance step that catches authoring errors before they reach the player community. The local testing workflow covers where to place files for testing, how to force a hot-reload of asset data, how to verify .dat parsing without launching the full game, and how to test every field configuration in single-player mode.

57 Studios™ has documented the complete local testing workflow based on the official SDG documentation and community-validated testing practices. This article covers every step from initial .dat validation to final pre-submission verification.

Documentation source: This article references the official Smartly Dressed Games modding documentation and the Steam Workshop section.

Who this article is for

This article is written for Unturned™ mod authors who are preparing to submit their first mod to the Steam Workshop, experienced mod authors who want a structured testing checklist, and anyone troubleshooting why a mod that works in development does not work after Workshop publication.

The testing directory structure

For local testing, place your mod files in the local Unturned™ installation's Workshop directory. The game scans the Workshop/Content/304930/ directory for mods regardless of whether they have been published on the Workshop.

<Unturned Install>/Workshop/Content/304930/<TestModID>/
├── Bundles/
│   ├── MasterBundle.dat
│   └── <modname>.masterbundle
├── Items/
│   └── <ItemName>/
│       ├── Asset.dat
│       └── English.dat
└── Workshop.dat

The <TestModID> can be any unique identifier. It does not need to be a real Workshop file ID for local testing. Use a memorable number that identifies the test mod.

Validation without launching the game

Before launching Unturned™ to test a new mod, perform these validation steps that do not require the game to run.

.dat syntax validation

Open each .dat file in a text editor and verify:

• All field names are spelled correctly (case-insensitive, but consistent with documentation)
• All values match their expected types (number fields contain numbers, GUIDs are 32 hex characters)
• Curly braces { and } are balanced for dictionaries
• Square brackets [ and ] are balanced for arrays
• Comments use the // prefix correctly

GUID format validation

Verify that every GUID in every .dat file is exactly 32 hexadecimal characters (0-9, a-f). No hyphens. No spaces.

ID uniqueness validation

Check that no two items in the same mod use the same ID value. Check against any other mods that will be loaded simultaneously.

Asset path validation

Confirm that every master bundle pointer's AssetPath matches an entry in the manifest file.

Single-player testing sequence

After launching Unturned™ in single-player mode, follow this testing sequence.

Step 1: Verify the asset loads

Open the in-game console with the tilde key ~ and type @AssetDirectories to confirm the mod directory is being scanned. If the mod directory is not listed, the folder structure may be incorrect.

Step 2: Spawn the item

Use the @give <itemID> command to spawn the item. If the item does not appear in the inventory, the ID may be wrong, the Type may be incorrect, or the master bundle may not be loaded.

Step 3: Visual inspection

Examine the item in the inventory. Verify:

• The icon renders correctly
• The model is visible when equipped
• The texture is correct (not pink)
• The scale is appropriate

Step 4: Functional testing

Test every field that has gameplay implications:

• Equip the item and confirm it appears in the correct slot
• Fire/use the item and confirm damage values match expectations
• Test reload behavior (for guns)
• Test durability degradation (if applicable)
• Test attachment compatibility (for weapons)

Step 5: Edge case testing

Test edge cases:

• Drop the item and pick it up again
• Save the game, reload, and confirm the item still works
• Equip and unequip the item multiple times
• Test with other mods loaded to check for conflicts

The console log

The game's console output is the primary diagnostic tool for asset loading issues. Common messages and their meanings:

Console message	Meaning	Action
Loaded asset: <GUID>	Asset registered successfully	None - normal behavior
Failed to load asset: <path>	Asset file found but parsing failed	Check .dat syntax
GUID conflict: <GUID>	Two assets share the same GUID	Regenerate one GUID
Missing master bundle: <name>	MasterBundle.dat points to nonexistent file	Verify the bundle file exists
Asset not found: <path>	Path in master bundle pointer is wrong	Check against manifest
ID conflict: <ID>	Two items share the same ID	Change one item's ID

Diagnostic table

Symptom	Most likely cause	Resolution
Item does not appear after @give	Wrong ID or incorrect folder structure	Verify the ID in the command matches the .dat ID; check folder path
Item appears but is invisible when equipped	Prefab not found in bundle	Verify Name field matches prefab name in bundle
Pink/white material	Shader not included in bundle	Re-export with multiplatform enabled
Wrong item appears	ID collision between two items	Use unique IDs in the 50000+ range
Item works in single-player but not on server	Server mod directory is different	Copy the mod to the server's Workshop directory
.dat changes not reflected after game restart	File was not saved in UTF-8 encoding	Re-save as UTF-8 without BOM
Master bundle not loaded	MasterBundle.dat is missing or misconfigured	Verify Asset_Bundle_Name matches the .masterbundle filename

Best practices

• Test every change in single-player before publishing to the Workshop.
• Keep a test save file with the necessary @give commands pre-typed.
• Check the console output after every game launch for warnings or errors.
• Use the manifest file to verify bundle contents after every export.
• Test with a clean mod directory to rule out stale file interference.
• Maintain a local copy of every published mod version for regression testing.

Frequently asked questions

How do I force a hot-reload without restarting the game?

Unturned™ does not support hot-reloading of asset files. You must restart the game to pick up changes to .dat files or master bundles. The only exception is server-side configuration files, which can be reloaded through commands.

Can I test Workshop mods before publishing?

Yes. Place the mod files in the Workshop/Content/304930/<anyID>/ directory as described above. The game loads them regardless of whether they have been published.

How do I verify .dat parsing without launching the game?

Check the .dat file structure manually: verify field names against documentation, check value types, and confirm GUID format. A dedicated .dat validator tool is not provided by SDG, but community tools may be available.

What should I check in the console output after launching?

Look for lines containing "Loaded asset", "Failed to load", "GUID conflict", "ID conflict", and "Missing". Any line containing "Error" or "Warning" related to your mod's content should be investigated.

How do I test attachment compatibility?

Spawn the base weapon and each attachment type using @give. Attach each attachment and verify the visual appearance and gameplay effects. Test with all attachment slots filled simultaneously.

Appendix A: Testing checklist

• [ ] .dat syntax validated (braces balanced, fields correct)
• [ ] GUID is 32 hex characters, no hyphens
• [ ] ID is unique within the mod (50000+ range recommended)
• [ ] Master bundle pointer paths verified against manifest
• [ ] MasterBundle.dat present with correct Asset_Bundle_Name
• [ ] Mod appears in @AssetDirectories output
• [ ] Item spawns with @give <ID>
• [ ] Visual model correct (not pink, correct scale)
• [ ] Gameplay fields function as expected
• [ ] Save and reload test passed
• [ ] No errors or warnings in console related to the mod

Appendix B: External references

• Smartly Dressed Games official modding documentation - the official field reference.
• Unturned on Steam - the Unturned store page.
• Mod Project Directory Structure - the previous article.
• Modding Workflow: End-to-End - the full workflow.

Testing with community mod tools

The Unturned modding community has developed several tools that can assist with local testing.

.dat validator tools

Community-created .dat validator tools can check your .dat files for syntax errors without launching the game. These tools typically check for balanced braces, valid field names, and correct value types. While not official SDG tools, they are widely used in the modding community.

Bundle inspection utilities

Tools that read and display the contents of .manifest files can help verify that the master bundle contains the expected assets. Some community tools also provide graphical browsing of bundle contents.

Testing framework scripts

Some community mod authors publish PowerShell or batch scripts that automate the testing workflow: copying files to the test directory, launching the game, and capturing console output. These scripts can be adapted for individual workstations.

Local testing for curated item submissions

When preparing a curated item submission for the Steam Workshop stockpile, the local testing workflow includes additional steps specific to the submission process.

Unity package verification

After testing the item locally, export a Unity package (.unitypackage) that includes the source files. Verify that the package opens correctly in a fresh Unity project.

Curated item guidelines compliance

Verify that the item follows the curated item guidelines for resolution, contrast, edge treatment, and art style. These guidelines are documented in the curated items section of the official SDG documentation.

Mythical effect placement verification

If the item is a cosmetic that supports mythical effects, verify that the "Effect" child transform is correctly positioned on both the Item.prefab and the clothing prefab. The official documentation specifies that +Z is the mythical's up direction and +Y is the mythical's forward direction.

Local testing by mod distribution method

Different distribution methods require different testing approaches.

Manual distribution mods

For mods distributed through direct file sharing (GitHub, Discord, direct download), test the mod on a clean Unturned installation that has never loaded the mod before. This simulates the end-user experience.

Workshop mods

For Workshop-distributed mods, create a local test with the Workshop directory structure and verify that the mod loads correctly from that location. Test the mod on a separate computer if possible to simulate a fresh download.

Server mods

For server-side mods, test on a local dedicated server before deploying to a production server. Verify that the mod works correctly in the server context and does not cause performance issues.

Glossary

Term	Definition
Local testing	Testing a mod on a single-player game instance before Workshop publication.
Console	The in-game command interface opened with the tilde key.
@give	The console command to spawn an item by ID.
@AssetDirectories	The console command to list all scanned mod directories.
Test save	A game save file used exclusively for mod testing.
Clean mod directory	A mod folder containing only the files for the current test.
Curated item	A community-created cosmetic submitted for Stockpile consideration.
Unity package	A .unitypackage file used to transfer Unity assets between projects.

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.

Configuration file management

Version numbering

Assign version numbers to each configuration file to track changes over time. Include the version number in a comment at the top of the file. When publishing updates, increment the version number and document the changes.

Change documentation

Maintain a changelog file alongside the configuration files. Record the date, version, author, and description of each change. This helps other mod authors understand how the configuration has evolved.

File naming conventions

Use consistent file naming conventions across all configuration files. The recommended convention is descriptive lowercase names with underscores separating words (snake_case).

Frequently asked questions (continued)

How do I roll back a configuration change?

Restore the previous version from version control. If version control is not in use, restore from a manual backup. This is why version control is strongly recommended.

What information should I include in a changelog entry?

Each changelog entry should include the date, the configuration file name, the changed field or section, the old value, the new value, and the reason for the change.

How do I share configuration best practices with my team?

Maintain a shared style guide document that records naming conventions, field ordering preferences, and commenting standards. Review pull requests to ensure compliance.

Cross-references

• Mod Project Directory Structure - the previous article.
• Modding Workflow: End-to-End - the full workflow.
• Steam Workshop Submission - the publishing workflow.
• Master Bundle Export - bundle export for testing.

Document history

Version	Date	Author	Notes
1.0	2026-07-26	57 Studios	Initial publication. Complete local testing workflow, directory structure, pre-launch validation, single-player testing sequence, diagnostic table.