Unturned Mod Folder Structure and GUIDs

Every Unturned™ mod begins with two foundational decisions: how to lay out the project folder, and how to assign GUIDs and item IDs that will never collide with vanilla content or with another modder's work. A mod that gets either decision wrong will not load at all, or will load and then silently overwrite a vanilla item in a way that breaks every server that installs it. This article documents the folder layout that 57 Studios™ and the broader Unturned modding community use, the methods for generating GUIDs that the game accepts, and the ID-range conventions that prevent collisions with vanilla content and with other mods.

The folder structure documented below mirrors the layout the official Smartly Dressed Games modding documentation recommends, extended with the conventions the modding community has converged on over years of mod releases. The GUID and ID-range conventions are drawn from the same sources and from the cohort's documented collision history.

Prerequisites

• Unity editor installed (see Unity Setup).
• Notepad++ installed (see Notepad++) and configured to save .dat files as UTF-8 without BOM, per How to Save a DAT File with Correct Encoding.
• An empty folder under a short top-level path such as C:\Project Folder\MyMod\.
• PowerShell available for the recommended GUID generation method.

What you'll learn

• The recommended top-level mod folder layout and what each subfolder contains.
• How Unturned discovers mod folders at game startup.
• Three methods for generating GUIDs that the game accepts.
• Namespace conventions that prevent GUID collisions when multiple modders work together.
• The ID number ranges that are safe to use and the ranges that are reserved for vanilla content.
• How to inspect existing mods to confirm an ID is unused.

Background: how Unturned loads mod content

Unturned loads mod content from two principal locations: the Workshop folder, where Steam stores subscribed Workshop mods, and the local Bundles/ folder under the game's installation directory. The game enumerates every subfolder of each location at startup, looking for the asset bundle and .dat files that define a mod's content. Each mod folder is a self-contained unit; Unturned does not merge content across folders.

Within a mod folder, the game performs the following operations at load time:

1. Enumerate every subfolder, looking for .dat files at any depth.
2. For each .dat file, parse the file's GUID and ID fields, the Type field, and any type-specific fields.
3. Register the item in the game's internal asset table, keyed by both GUID and ID.
4. Load the referenced master bundle and resolve any prefab references to the bundle's contents.
5. Apply the localized strings from any English.dat (or other language) file in the same folder.

A mod that has a malformed folder layout, a duplicated GUID, or an ID that collides with vanilla content will either fail to load or will silently overwrite the colliding entry. The sections below document the folder layout, GUID assignment, and ID ranges that prevent these failures.

The sequence diagram above models the order in which Unturned loads a mod's content. Each step can fail; the most common failure is the GUID or ID collision detected at the Asset Table step, which causes Unturned to either silently use the last-loaded entry or refuse to register the duplicate.

Recommended top-level folder layout

The folder layout below is the layout 57 Studios uses for every new mod project and matches the layout the Smartly Dressed Games documentation recommends. Every subsequent article in the Items section assumes this layout.

MyUnturnedMod/
├── Bundles/
│   └── mymod.unity3d           <-- master bundle exported from Unity
├── Items/
│   ├── MyPistol/
│   │   ├── MyPistol.dat        <-- item definition
│   │   ├── English.dat         <-- localized strings
│   │   └── Icon.png            <-- inventory icon
│   ├── MyMagazine/
│   │   ├── MyMagazine.dat
│   │   ├── English.dat
│   │   └── Icon.png
│   └── MyAttachment/
│       ├── MyAttachment.dat
│       ├── English.dat
│       └── Icon.png
├── Vehicles/
│   └── MyVehicle/
│       ├── MyVehicle.dat
│       ├── English.dat
│       └── Icon.png
├── Sounds/
│   └── (audio assets if separate from bundle)
├── meta.dat                    <-- mod-level metadata
└── README.md                   <-- modder's own notes

The folder names Bundles, Items, and Vehicles are conventional. Unturned will enumerate .dat files at any depth, so a modder could organize content differently, but the convention is widely used and downstream tooling (server admin tools, Workshop publishers, asset audit scripts) generally expects it.

Did you know?

Unturned does not require items of a given type to live in a folder of the same name. A Vehicle.dat file can live in a folder named Items/ and the game will still register it as a vehicle, because the Type field in the .dat file is the authoritative source. The folder name is purely organisational, for the benefit of the modder and other humans who read the project.

Per-folder purpose reference

Folder	Purpose	Required?	Notes
Bundles/	Holds the master bundle exported from Unity	Yes for any mod with 3D content	One bundle per mod is the cohort norm
Items/	Holds per-item .dat and localization files	Yes for mods with items	Subfolder per item is the convention
Vehicles/	Holds per-vehicle .dat and localization files	Yes for mods with vehicles	Same convention as Items
Sounds/	Holds audio assets if packaged outside the bundle	Optional	Most modders embed audio in the bundle
Animations/	Holds animation assets if packaged outside the bundle	Optional	Same as Sounds
Skins/	Holds reskin definitions	Only for skin mods	Subfolder per skin
meta.dat	Mod-level metadata: name, author, description	Recommended	Used by some server admin tools
README.md	Modder's own notes	Optional	Not read by the game

Pro tip

Use a separate top-level subfolder for each major asset category. The cohort convention is Items/, Vehicles/, Skins/, and so on. The folder names are not enforced by Unturned but they map cleanly to the categories that Workshop browsers and server admin tools recognize.

Per-item folder structure

Within Items/<ItemName>/, the convention is one folder per item. Each folder holds the item's .dat file, a localization file per language, and the icon image. The folder name and the .dat filename do not need to match, but matching them makes the project easier to navigate.

Items/MyPistol/
├── MyPistol.dat       <-- core item definition (GUID, ID, Type, mechanical fields)
├── English.dat        <-- English localized strings (Name, Description)
├── Icon.png           <-- 1024x1024 PNG inventory icon
└── MyPistol_Master.png <-- optional larger master icon

The English.dat file contains the player-facing name and description; the core .dat file contains the GUID, ID, type, and the mechanical fields. Splitting localization from mechanics allows a modder to translate the mod to additional languages by adding French.dat, Spanish.dat, and so on, without modifying the core file.

GUIDs in Unturned

Every item, vehicle, and other registerable asset in Unturned has two unique identifiers: a GUID and an ID. The GUID is the modern, collision-resistant identifier; the ID is the legacy short integer identifier still used in many places (chat commands, save files, server admin tools). Both are required; both must be unique across vanilla content and across every other mod that may be installed alongside.

GUID format

A GUID in Unturned uses the standard 32-character hexadecimal format with no dashes:

GUID 0123456789abcdef0123456789abcdef

The format is identical to the Microsoft GUID format with the dashes removed. Some modders prefer to author the GUID in the dashed form and then strip the dashes; either approach works as long as the final value in the .dat file is the 32-character form.

Common mistake

Pasting a GUID with dashes into the .dat file. Unturned's parser expects exactly 32 hex characters with no separators. A GUID written as 01234567-89ab-cdef-0123-456789abcdef will fail to parse and the item will not load. Always strip the dashes before saving the .dat file.

Method 1: PowerShell

The fastest method for generating a GUID on Windows is PowerShell. The [guid]::NewGuid() static method produces a fresh GUID; piping it through -replace strips the dashes.

([guid]::NewGuid()).ToString("N")

The "N" format specifier produces the 32-character hex form with no dashes. The output is a fresh GUID ready to paste into a .dat file.

For a batch of GUIDs, the same method works in a loop:

1..10 | ForEach-Object { ([guid]::NewGuid()).ToString("N") }

Method 2: Visual Studio Tools → Create GUID

Visual Studio ships with a Create GUID utility under Tools → Create GUID (or as a separate executable in the Visual Studio installation). The utility offers several output formats; the format Unturned expects is the registry-format value (32 hex characters with no dashes), which the utility produces when "Registry Format" is selected and the leading and trailing braces are removed.

The Visual Studio method is useful when the modder is already in Visual Studio for C# work; for modders who do not have Visual Studio installed, the PowerShell method is faster.

Method 3: Online generators

Several online GUID generators produce values in formats suitable for Unturned. The cohort recommendation is to use the PowerShell method whenever PowerShell is available; the online method is offered as a fallback for modders working on a system without PowerShell or Visual Studio.

When using an online generator, the modder should select the "no dashes" or "registry format" option and confirm that the output is exactly 32 hex characters.

Critical warning

Never re-use a GUID from another mod. Every GUID must be globally unique. Copying a GUID from an existing mod and changing the name causes Unturned to register both entries under the same GUID, which produces undefined behaviour. Always generate a fresh GUID for every new item.

Method comparison

Method	Time	Requires	Best for
PowerShell [guid]::NewGuid()	Two seconds	PowerShell (ships with Windows)	Most modders
Visual Studio Create GUID	Ten seconds	Visual Studio installed	C# developers
Online generator	Variable	Internet connection	Fallback only
New-Guid cmdlet	Two seconds	PowerShell 5+	Same as Method 1
.NET Guid.NewGuid() in code	One second per call	C# or .NET runtime	Batch generation

The New-Guid cmdlet is a more readable alias for [guid]::NewGuid() but produces the dashed form by default. Pipe it through .Guid.Replace("-","") or use the .ToString("N") method to produce the no-dashes form Unturned expects.

ID numbers

In addition to the GUID, every item and vehicle in Unturned has a short integer ID. The ID is a 16-bit value (0 through 65535). Many parts of the game and the surrounding tooling still operate on the ID rather than the GUID: chat commands such as /give <player> <id>, save file references, and the in-game console all use the ID. GUID collisions are rare in practice but ID collisions are common, because the ID space is small and many modders pick the same ranges by default.

Reserved ranges

The ranges below are reserved for vanilla content and for established modding conventions. A new mod must avoid these ranges to prevent collisions.

Range	Reserved for	Notes
0–999	Vanilla items (early game)	Includes most vanilla weapons, ammunition
1000–1999	Vanilla items (extended)	Includes vanilla vehicles, clothing
2000–4999	Reserved for future vanilla content	Smartly Dressed Games has used parts of this range in updates
5000–9999	High-traffic community mods	Several long-established mods occupy this range
10000–19999	Community mods (loose convention)	The most contested range; collisions are common
20000–29999	Community mods (loose convention)	Slightly less contested
30000–65535	Available for new mods	The cohort's recommended starting range

Pro tip

The cohort's recommendation for a new mod is to pick a block of consecutive IDs in the 30000–65535 range. Picking a block of 100 or 1000 IDs and reserving them for the mod (even if only a few are used initially) prevents collisions when the mod expands. Document the chosen block in the mod's README so future maintainers do not pick overlapping IDs.

Picking an ID block

The procedure for picking an ID block:

1. Decide on the maximum number of items the mod might eventually contain. A weapon mod might have 30 items (gun, magazines, attachments, ammunition variants); a content overhaul might have 500.
2. Pick a starting ID in the 30000–65535 range that is not yet known to be in use. The cohort's loose convention is to pick a starting ID that aligns with the modder's chosen namespace (see Namespace conventions below).
3. Reserve a block at least twice the projected size. A mod expected to grow to 30 items should reserve a block of 60.
4. Document the block in the mod's README and (if the mod is part of a published series) on the modder's public website or Workshop page.
5. Assign IDs from the block in order as items are added.

Checking an ID is unused

Before assigning an ID, the modder should confirm the ID is not already in use by vanilla content or by a popular mod. The simplest check is to enumerate the vanilla Bundles/ folder and any Workshop mods the modder has installed, and grep for the candidate ID.

A PowerShell one-liner that searches .dat files for a specific ID:

Select-String -Path "C:\Path\To\Unturned\Bundles\*\*.dat" -Pattern "^ID 12345$"

The pattern ^ID 12345$ matches lines that are exactly ID 12345 and nothing else, which is the format the .dat file uses. The command returns the file paths and line numbers of any match. An ID with no matches is safe to use.

Did you know?

Unturned's vanilla content occasionally introduces new items in updates, and those new items occupy IDs in the reserved ranges. A modder who has been using an ID in the 2000–4999 range may find that a future vanilla update collides with the mod. The cohort's defensive practice is to avoid the reserved ranges entirely, even the portions that are not currently used by vanilla content.

Namespace conventions

When multiple modders work together, or when a single modder operates multiple parallel mods, GUID and ID collisions become more likely. A namespace convention reduces the collision risk by giving each modder or mod a known prefix.

GUID prefixes

Some modders use the first few characters of the GUID as a namespace marker. For example, a modder might use GUIDs that all begin with 57 (their cohort or studio prefix), even though the standard GUID format has no such concept. The convention is purely organisational; Unturned does not interpret the prefix.

The cohort convention is to use truly random GUIDs (generated by [guid]::NewGuid() with no prefix manipulation) and to rely on the GUID's 128-bit space for collision avoidance. The probability of two randomly generated GUIDs colliding is negligible.

ID number prefixes

The ID prefix convention is more useful because the ID space is small. A common pattern is for a modder to claim a block such as 32000–32099 and to use only those IDs for the modder's items. The first two digits (32) become the modder's namespace marker.

For mods that produce multiple item types, a finer-grained convention is to use the third digit to indicate the type:

Third digit	Type
0	Weapons (primary)
1	Weapons (secondary)
2	Ammunition and magazines
3	Attachments
4	Clothing
5	Vehicles
6	Storage and inventory
7	Consumables (food, medicine)
8	Miscellaneous
9	Reserved for future use

A modder using the 32000–32099 block would assign IDs 32000–32009 to primary weapons, 32020–32029 to ammunition, 32050–32059 to vehicles, and so on. The convention is not enforced; it is purely a pattern that helps the modder organize the ID space.

The .dat file: GUID and ID fields

Every item's .dat file contains a GUID line and an ID line at the top. The example below shows the first few lines of a typical item .dat file:

GUID 0123456789abcdef0123456789abcdef
ID 32001
Type Gun
Rarity Common
Useable Gun
SizeX 4
SizeY 2

The GUID and ID lines are case-sensitive in older versions of Unturned and case-insensitive in newer versions; the cohort convention is to use the case shown above to maintain compatibility across versions.

Common mistake

Forgetting the GUID line in a .dat file. Some older Unturned mod templates omitted the GUID and relied on the ID alone. Modern Unturned requires both. A .dat file with no GUID may fail to load, or may load with the game synthesising a GUID at runtime (which means the mod will have a different GUID every time the game starts, breaking save files).

Verification

After authoring the folder structure and assigning GUIDs and IDs, the modder should verify the work before moving to the master bundle export step.

Step 1: Confirm the folder layout

Open the mod folder in File Explorer and confirm:

• A Bundles/ folder exists at the top level.
• An Items/ (or appropriate category) folder exists at the top level.
• Each item has its own subfolder under the category folder.
• Each item folder contains at least a .dat file, an English.dat, and an icon PNG.

Step 2: Confirm GUIDs are unique within the mod

Open PowerShell, navigate to the mod folder, and run a uniqueness check:

Get-ChildItem -Path . -Filter "*.dat" -Recurse |
  Select-String -Pattern "^GUID " |
  ForEach-Object { $_.Line } |
  Group-Object |
  Where-Object Count -gt 1

The command groups every GUID line by value and reports any value that appears more than once. The output should be empty; a non-empty output indicates duplicate GUIDs that must be regenerated.

Step 3: Confirm IDs are unique within the mod

Repeat the check for IDs:

Get-ChildItem -Path . -Filter "*.dat" -Recurse |
  Select-String -Pattern "^ID " |
  ForEach-Object { $_.Line } |
  Group-Object |
  Where-Object Count -gt 1

Same expected output: empty. A non-empty output indicates duplicate IDs.

Step 4: Confirm IDs do not collide with vanilla content

Run the ID-check command (Section: Checking an ID is unused) for each ID in the mod, against the vanilla Bundles/ folder of the local Unturned install. Every check should return no matches.

Pro tip

The PowerShell uniqueness checks above are quick to run and catch the majority of collision bugs before they reach the game. The cohort's recommendation is to add the checks to a pre-publish script so they run automatically before every Workshop upload.

Advanced considerations

Multiple mods sharing a project folder

A modder who maintains several mods in parallel can either give each mod its own top-level folder or organize them under a shared parent. The cohort's recommendation is one top-level folder per mod, because Unturned enumerates top-level folders independently and a mod with a malformed .dat file should not be able to break sibling mods.

Workshop folder layout

When a mod is published to the Steam Workshop, the layout the Workshop publisher uploads is the layout the game will see on subscribers' machines. The folder structure documented in this article is the structure to publish; modders should not flatten or rearrange the folders before upload.

Mod versions and ID stability

Once a mod is published, the IDs and GUIDs become part of the mod's contract with players and servers. Changing an ID after publication will break every save file and server config that references the old ID. The cohort's recommendation is to plan the ID block large enough at the outset so that growth does not require renumbering existing items.

Encoding for .dat files

The .dat file encoding must be UTF-8 without BOM. See How to Save a DAT File with Correct Encoding for the Notepad++ configuration. A file saved with a BOM or in UTF-16 will fail to parse, even if every other detail in this article is correct.

Long path support

Mod folders nested deep in the file system may exceed the 260-character Windows path limit. Symptoms include intermittent failures to enumerate .dat files and missing items at game load. The defensive practice is to keep mod folders at short top-level paths such as C:\Project Folder\MyMod\.

Modder coordination on shared servers

When multiple modders contribute items to the same server, ID coordination becomes essential. The cohort's recommendation is for the server's lead modder to maintain a shared ID-block registry (a spreadsheet, a Google Sheet, or a wiki page) where each contributing modder claims a block. The registry is the single source of truth for which blocks are reserved.

Worked example: a small pistol mod

The example below shows the full layout for a small mod with one pistol, one magazine, one attachment, and an English localization. The mod uses GUIDs generated by PowerShell and the ID block 32000–32099.

ExamplePistolMod/
├── Bundles/
│   └── examplepistol.unity3d
├── Items/
│   ├── ExamplePistol/
│   │   ├── ExamplePistol.dat       (GUID a1b2..., ID 32000)
│   │   ├── English.dat
│   │   └── Icon.png
│   ├── ExampleMagazine/
│   │   ├── ExampleMagazine.dat     (GUID c3d4..., ID 32020)
│   │   ├── English.dat
│   │   └── Icon.png
│   └── ExampleSight/
│       ├── ExampleSight.dat        (GUID e5f6..., ID 32030)
│       ├── English.dat
│       └── Icon.png
└── meta.dat

The pistol's .dat file references the magazine and sight by their IDs, allowing the player to attach them in-game. The bundle holds the 3D models for all three items in a single shared file.

Best practice

For small mods (under 20 items), package all 3D assets in a single master bundle. The cohort's measured load time for a mod with a single 50 MB bundle is significantly lower than the load time for the same mod split across ten 5 MB bundles. The single-bundle approach also simplifies the build and publish pipeline.

Frequently asked questions

What format does an Unturned GUID use?

A 32-character hexadecimal string with no dashes. Generate one with PowerShell's ([guid]::NewGuid()).ToString("N") or with Visual Studio's Create GUID utility (registry format, dashes stripped).

How do I generate a GUID for an Unturned mod?

The fastest method on Windows is PowerShell: ([guid]::NewGuid()).ToString("N"). The output is a fresh 32-character GUID ready to paste into the .dat file's GUID line.

What ID ranges are safe to use in Unturned mods?

The cohort recommendation is 30000–65535. The 0–4999 range is reserved for vanilla content; the 5000–29999 range is widely used by established community mods and the collision rate is high.

How do I check if an ID is already in use by another mod?

Run the PowerShell command Select-String -Path "C:\Path\To\Unturned\Bundles\*\*.dat" -Pattern "^ID 12345$" against the vanilla Bundles/ folder and against any Workshop mods installed on the local machine. An ID with no matches is safe to use.

Can two mods share the same GUID?

No. A GUID must be globally unique. If two mods share a GUID, Unturned registers both under the same key and the behaviour is undefined (typically the last-loaded mod overwrites the earlier one, but the order is not guaranteed). Every item in every mod must have its own GUID.

Do I need both a GUID and an ID, or just one?

Both. The GUID is the modern identifier the game uses internally; the ID is the legacy short integer used by chat commands, save files, and many server admin tools. Modern Unturned requires both fields in the .dat file.

What happens if my mod's ID collides with a vanilla item?

The mod overwrites the vanilla item in the game's asset table. Players will receive the modder's item when the game tries to give them the vanilla one. This is almost always a bug from the modder's perspective; the fix is to renumber the modder's item to a non-reserved range.

How do I rename an item without changing its ID?

The item's display name lives in the English.dat (or other language) file under the Name and Description fields. Change those fields without touching the core .dat file's GUID or ID, and the item's identity remains stable across save files and server configs.

Can I reuse the ID of a vanilla item I want to replace?

Technically yes — Unturned will overwrite the vanilla item with the modder's version — but the practice is discouraged because every server that loads the mod loses the original vanilla item. The cohort's recommendation is to add new items in unused ID ranges rather than replace vanilla items.

What does the meta.dat file contain?

meta.dat holds mod-level metadata: the mod's display name, the author's name, a description, and the version number. The file is optional but recommended; some server admin tools read it to display the mod's information to server operators.

Why does my mod load but my new item not appear in the game?

The most common causes are: a duplicate ID with another loaded mod or with a vanilla item (the other entry wins); a malformed .dat file that fails to parse (Unturned logs the parse error to its console); a missing or wrong-encoded English.dat (the item is registered but has no display name and may be hidden by the UI). Check the in-game console for parse errors first.

Does the folder name need to match the .dat file name?

No. Unturned reads the .dat file's contents to determine the item's name and type; the folder name is purely organisational. The cohort convention is to match them for human readability, but the game does not require it.

Can I have multiple items in the same .dat file?

No. Each .dat file defines exactly one item or vehicle. Multiple items require multiple .dat files, typically in separate subfolders.

Best practices

• Use PowerShell's [guid]::NewGuid() for GUID generation. It ships with Windows and produces correctly formatted output.
• Pick an ID block in the 30000–65535 range. Avoid the 0–4999 reserved range and the contested 5000–29999 range.
• Reserve a block at least twice the projected size to allow for growth.
• Document the chosen ID block in the mod's README.
• Run the PowerShell uniqueness checks before every Workshop upload.
• One folder per item; mirror the convention across Items/, Vehicles/, and other category folders.
• One master bundle per mod for small to mid-sized mods; split only when the bundle exceeds approximately 100 MB.
• Save every .dat file as UTF-8 without BOM in Notepad++.

Cross-references

• How to Save a DAT File with Correct Encoding — the encoding configuration .dat files must use to parse correctly.
• Master Bundle Export — the next article in the Items section, which covers the Unity-side bundle export.
• Unity Setup — the Unity install and master bundle tool documentation that the bundle export depends on.
• Notepad++ — the text editor configuration for .dat file authoring.
• Smartly Dressed Games official modding documentation — the upstream reference for Unturned modding.

Document history

Version	Date	Notes
1.0	2024-06-12	Initial publication. Folder layout and GUID generation methods.
1.1	2024-09-08	Added ID range conventions and collision-check PowerShell snippets.
1.2	2025-01-14	Added namespace convention section and worked example.
2.0	2025-05-18	Major revision. Added Mermaid sequence and flowchart, expanded FAQ, added best practices section.

Closing note

The folder structure and ID conventions documented in this article are the foundation every subsequent step in the Items pipeline depends on. A mod with a correctly laid-out folder and a correctly assigned GUID and ID block can move directly to the master bundle export step; a mod with either decision wrong will surface the problem at every later step, often in ways that are difficult to diagnose. The thirty minutes spent getting this article right at the start of a project saves hours of troubleshooting later.

Next steps

Continue to Master Bundle Export to package the mod's 3D content into a Unity asset bundle that Unturned can load. Return to Items for the section overview.