Legacy ID Availability

Intermediate40-60 minutesWindowsNotepad++Unity Editor

Before GUIDs were introduced to Unturned™, the engine identified every item, object, vehicle, and resource using a 16-bit unsigned integer called a legacy ID. The legacy ID system is a 0-through-65535 numeric namespace shared across all vanilla content and every mod loaded simultaneously at runtime. Because the namespace is finite and uncoordinated, two mods that independently assign the same legacy ID produce a collision: one asset silently overwrites the other at load time, and the overwritten asset becomes unreachable. The legacy ID system remains in active use for certain asset categories, and every mod developer must understand how to select an available legacy ID, how to verify availability, and when to use a GUID instead.

This article is the 57 Studios™ canonical reference for the legacy ID system. It documents the complete reserved-range table, the in-game Export Asset IDs workflow, the Legacy ID Availability.csv file format, the asset categories that still require legacy IDs (and those that do not), the relationship between legacy IDs and GUIDs during the ongoing asset-system migration, and the cohort-validated conventions for picking a safe ID block for a new mod project. The article assumes familiarity with the GUID system and the project folder layout; readers who are new to Unturned™ modding should read Project Folder Structure and GUIDs and GUID Type Reference before this article.

Documentation source: This article references Chapter 148 ("Legacy ID Availability") of the official Smartly Dressed Games modding documentation for the export workflow and the legacy-ID-to-GUID transition guidance. ID range conventions are validated against the shipped Unturned™ asset set and the cohort's documented collision history.

Who this article is for

This article is written for Unturned™ mod authors who are planning a new mod project, who are adding items to an existing mod, or who are troubleshooting ID collisions between mods. Readers should already understand the .dat file format, the folder structure for a mod project, and the GUID system. If you have never authored a .dat file, start with Item Asset Anatomy and return here after you have completed your first item.

What you'll learn

• The technical definition of a legacy ID: a 16-bit unsigned integer, range 0 through 65535
• The reserved ranges for vanilla content and the ranges that are safe for mod content
• How to use the in-game Export Asset IDs tool to verify ID availability
• The structure and purpose of the Legacy ID Availability.csv files
• Which asset categories still depend on legacy IDs and which have fully migrated to GUIDs
• How legacy IDs and GUIDs coexist in the current Unturned™ asset system
• The cohort-validated conventions for picking an ID block for a new mod
• How to diagnose and resolve legacy ID collisions between mods

Background: the legacy ID system and why it persists

The legacy ID system was the original identity mechanism for Unturned™. Every item, object, vehicle, effect, and resource received a uint16 identifier, and the engine indexed all loaded assets in a flat array keyed by this identifier. The system was simple and fast-a single integer lookup resolved any asset reference-but it had a fundamental mathematical limit: 65536 slots for all assets across all vanilla content and all mods loaded simultaneously. When the vanilla asset set grew past a few thousand items and the modding community began producing content at scale, the 16-bit address space became a coordination problem that no amount of convention could fully solve.

The GUID system was introduced to remove the address-space limit. A GUID is a 128-bit value, providing an address space so large (2^128, or approximately 3.4 x 10^38) that independently generated GUIDs do not collide in practice. The SDG documentation states that GUIDs "can be generated without coordination or registration between developers." Assets that have been upgraded to the GUID-only identity model use GUIDs as their primary identity key, and legacy IDs become a backwards-compatibility shim that is only required for asset categories that have not yet completed the migration.

The migration is ongoing. As of the current Unturned™ release, the following asset categories have completed or are nearing completion of the GUID migration:

Asset category	Legacy ID required?	GUID migration status
Items (guns, melee, magazines, throwables, clothing, consumables)	Yes, for /give commands, save files, and spawn tables	GUIDs supported; legacy IDs still required for chat commands and legacy save compatibility
Objects (structures, barricades, world objects)	No	Fully migrated to GUIDs
Vehicles	No	Fully migrated to GUIDs
Resources (trees, rocks, ore nodes)	No	Fully migrated to GUIDs
Effects (particle effects, audio cues)	No	Fully migrated to GUIDs
Spawn tables	No (can reference items by GUID)	Partially migrated; some spawn tables still reference by legacy ID
NPC clothing	No (can reference items by GUID)	GUID references supported
Blueprint recipes	No (use GUID references exclusively)	Fully migrated

The table shows that items remain the primary category where legacy IDs are still required. A mod that adds a custom gun, melee weapon, magazine, or clothing item must still assign a legacy ID, because players will use the /give command to spawn the item, and the /give command operates on the legacy ID. Certain server plugins and admin tools also operate on legacy IDs. For this reason, every mod item should carry both a legacy ID (for backwards compatibility with the /give command and legacy tooling) and a GUID (for modern identity resolution and cross-asset referencing).

As shown in the flowchart above, the legacy ID system has not been removed but has been progressively supplemented by the GUID system. The dual-identity model is the current operating reality for mod developers.

How the Export Asset IDs tool works

The official SDG documentation describes a built-in tool for auditing legacy ID usage across all loaded content. The tool exports a set of CSV files that list every legacy ID, the asset category it belongs to, and whether it is reserved for core (vanilla) content or available for mod use.

Step-by-step export procedure

1. Launch Unturned™ and arrive at the main menu.
2. Press F1 to open the Workshop sub-menu. (The F1 key is the default shortcut; if the key has been rebound, access the Workshop menu through the main menu navigation.)
3. In the Workshop sub-menu, locate and click the Export Asset IDs button.
4. Wait for the export to complete. The export operation reads every loaded asset (vanilla and mod) and writes the CSV files to disk. The operation may take several seconds on a large mod loadout.
5. Open the Extras/AssetIDs/All Assets/Grouped by Legacy Category/ folder relative to the Unturned™ installation directory. The typical path is C:\Program Files (x86)\Steam\steamapps\common\Unturned\Extras\AssetIDs\All Assets\Grouped by Legacy Category\.

The Grouped by Legacy Category folder contains one CSV file per legacy asset category. Each file is named after the category it documents. For example, the Items category produces Legacy ID Availability - Items.csv.

CSV file format

Each Legacy ID Availability.csv file is a standard comma-separated values file with a header row and one data row per legacy ID. The format is:

Column	Content	Example
A (first column)	Legacy ID (integer)	15
B (second column)	Asset name or internal identifier	Eaglefire
C (third column)	Reserved status	Reserved or empty (available)

An ID marked Reserved in the third column is occupied by vanilla content and must not be used by a mod. An ID with an empty third column is available for mod use. The cohort recommendation is to treat every Reserved ID as permanently off-limits, even if the modder does not currently have that vanilla asset loaded. A future game update could introduce a new vanilla item at any reserved ID, and a mod that was using that ID would break when the update released.

Interpreting the export for mod planning

The export produces a complete snapshot of the legacy ID namespace as it exists on the modder's current installation. A modder planning a new mod should:

1. Run the Export Asset IDs tool with all planned mod content loaded (vanilla plus any mods the developer expects players to commonly install alongside).
2. Open the CSV file for the relevant asset category (Items, for most mod content).
3. Scan for a contiguous block of available IDs in the 30000-65535 range.
4. Note the block and record it in the mod's documentation.

The flowchart above documents the complete export-and-scan workflow. The modder should re-run the export periodically, especially after major game updates that introduce new vanilla content, to confirm that the chosen ID block remains available.

Reserved legacy ID ranges

The 16-bit legacy ID namespace is partitioned into ranges that are reserved for vanilla content, ranges that are contested (occupied by established community mods), and ranges that are safe for new mod development. The table below documents the current known ranges.

ID range	Reserved for	Status for mod use
0-999	Vanilla items (early game)	Reserved. Do not use.
1000-1999	Vanilla items (extended), vanilla vehicles, vanilla clothing	Reserved. Do not use.
2000-4999	Reserved for future vanilla content	Reserved. Do not use. SDG has used portions of this range in past updates.
5000-9999	High-traffic community mods	Contested. Several long-established mods occupy this range. Use only if you have confirmed the specific ID is unoccupied and you accept the risk of future collisions.
10000-19999	Community mods (loose convention)	Contested. The most heavily used community range. Collisions are common.
20000-29999	Community mods (loose convention)	Contested. Slightly less traffic than the 10000-19999 range.
30000-49999	Available for new mods	Safe. The cohort's recommended starting range. Low collision risk.
50000-65535	Available for new mods	Safe. The cohort's strongly recommended range for new mod projects. Highest available range with the lowest collision risk.

The 50000-65535 range is the cohort's strong recommendation for new mod projects. The range is high enough that no vanilla content occupies it, few established community mods use it, and the risk of collision with another new mod is minimised. A modder who picks a block in this range and documents the choice is unlikely to encounter an ID collision across the entire lifecycle of the mod.

The relationship between legacy IDs and GUIDs

A mod item in the current Unturned™ asset system carries both a legacy ID and a GUID. The two identifiers serve different roles:

Role	Legacy ID	GUID
Bit width	16 bits	128 bits
Address space	0 through 65535	2^128 possible values
Uniqueness guarantee	None. Coordination required between modders.	Probabilistically guaranteed by address space size and random generation.
Used by /give command	Yes. @give 50001 spawns the item with legacy ID 50001.	No. The /give command does not accept GUIDs.
Used by blueprint recipes	Rarely. Blueprints primarily use GUIDs.	Yes. Blueprint InputItems and OutputItems reference assets by GUID.
Used by spawn tables	Yes, in legacy spawn tables.	Yes, in modern GUID-aware spawn tables.
Used by NPC clothing config	Rarely.	Yes. Modern NPC clothing configuration references items by GUID.
Used by save files	Yes, for legacy save compatibility.	No. Save files store legacy IDs.
Visibility in the Export Asset IDs CSV	Yes. Listed with reserved/available status.	No. GUIDs do not appear in the legacy ID audit tool.
Required for all items?	Yes, for items.	Yes, for all asset types.

A mod item that omits the legacy ID will not be spawnable via the /give command, will not appear in the Export Asset IDs tool, and may not function correctly in legacy save files. A mod item that omits the GUID will not be reachable via blueprint recipes, spawn tables, or any GUID-based reference system. Every mod item should carry both identifiers.

Common mistake

Assigning a legacy ID but omitting the Bypass_ID_Limit field. Items with IDs above 2000 require Bypass_ID_Limit True in the .dat or .asset file. Without this field, the engine rejects IDs above the 2000 threshold. Every mod item with an ID in the 50000+ range must carry Bypass_ID_Limit True.

Asset categories that still rely on legacy IDs

The SDG documentation states: "Ideally, new content should use GUIDs when possible. Certain asset types-such as items-still rely heavily on legacy IDs." The documentation additionally notes that items "can be referenced by GUID in many cases. For example, NPC clothing and item spawn tables can reference items by GUID."

The categories that still have a hard dependency on legacy IDs are:

Category	Dependency	Notes
Items	/give command, save files, legacy spawn tables	The /give command requires a numeric legacy ID. This is the primary reason mod items must carry legacy IDs.
Legacy spawn tables	Spawn table entries	Spawn tables authored in the legacy format reference items by legacy ID. Modern (GUID-aware) spawn tables can reference items by GUID.
Legacy save files	Item references in player saves	Player inventories and world save files store legacy IDs. GUID-only items may not restore correctly from legacy saves.

For all other asset categories (objects, vehicles, resources, effects, modern spawn tables, NPC configuration, blueprint recipes), GUIDs are the recommended and in many cases the only accepted identity key. A mod that adds only vehicles does not need to assign legacy IDs to the vehicle assets (though doing so does not cause harm and provides backwards compatibility with any legacy tooling that might reference vehicles by ID).

How legacy IDs interact with the /give command

The /give command is the primary in-game mechanism for spawning items by their legacy ID. The command syntax is:

@give <player> <legacyID>

When a player types @give MySteamName 50001, the engine looks up legacy ID 50001 in the global asset registry and spawns a number of the corresponding item. If no asset is registered at ID 50001, the command returns an error indicating that the ID is unknown.

The /give command does not accept GUIDs. A player cannot type @give MySteamName a1b2c3d4e5f64a7b8c9d0e1f2a3b4c5d. The command parser expects a numeric argument and will reject hexadecimal GUID strings. This is the single most practically important reason that mod items must carry legacy IDs: players need to be able to spawn them, and the only universally available spawning command operates on legacy IDs.

Some server plugins and admin tools have extended the /give command to accept GUIDs or item names, but these are third-party extensions. The baseline Unturned™ /give command operates exclusively on legacy IDs.

Picking a safe legacy ID block: the cohort convention

The cohort convention for picking a legacy ID block for a new mod project is documented below. The convention is validated against years of mod releases and collision reports across the Unturned™ modding community.

Step 1: Choose a starting ID in the 50000-65535 range

The highest available range minimises collision risk with vanilla content (which occupies the 0-4999 range) and with established community mods (which cluster in the 5000-29999 range). A starting ID of 50000 is the default cohort recommendation for a modder's first project.

Step 2: Reserve a block at least twice the projected item count

A mod expected to grow to 20 items should reserve a block of at least 40 IDs (e.g., 50000-50039). A mod expected to grow to 100 items should reserve at least 200 IDs. The 2x multiplier provides headroom for expansion: a mod that starts with 10 items and reserves a block of 20 may outgrow the block within a few updates, forcing a disruptive renumbering of every item.

Step 3: Document the block

Record the chosen block in the mod's README.md file and, if the mod is part of a published series, on the modder's public website or Workshop page. The documentation should state the block range, the date the block was reserved, and the modder's contact information (so that another modder who accidentally picks the same block can coordinate).

Step 4: Assign IDs sequentially from the block

Assign IDs in order as new items are added: the first item gets the first ID in the block, the second item gets the second ID, and so on. Sequential assignment makes it easy to see at a glance which IDs are occupied and which are still free. Avoid skipping around within the block unless there is a deliberate organisational scheme (e.g., reserving sub-ranges for different item types).

Step 5: Re-verify after major game updates

After a major Unturned™ update that introduces new vanilla items, re-run the Export Asset IDs tool and confirm that the chosen block remains available. A vanilla update that introduces a new item at an ID within the chosen block is unlikely (the reserved ranges are well-separated from the 50000+ range) but possible if SDG changes its ID allocation policy.

ID collisions: detection, diagnosis, and resolution

An ID collision occurs when two mods register an item at the same legacy ID. The engine loads mods in filesystem enumeration order, which is not guaranteed to be consistent across installations. The item registered second overwrites the item registered first in the global asset table. The overwritten item becomes unreachable by its legacy ID: the /give command for that ID spawns the second item, not the first. The overwritten item may still be reachable by its GUID (if it has one), but legacy-ID-based references (spawn tables, save files) will resolve to the second item.

Detection

The symptoms of an ID collision are:

• A known item (from a mod that the player has installed and used before) fails to spawn via the /give command, and a different item spawns instead.
• A spawn table that previously spawned Item A now spawns Item B.
• A saved game that previously loaded correctly now loads with incorrect items in the player's inventory.

The Export Asset IDs tool is the definitive diagnostic. Run the export and open the CSV for the relevant category. If two rows share the same legacy ID, the later row is the one that overwrote the earlier one.

Diagnosis

To confirm an ID collision:

1. Run the Export Asset IDs tool.
2. Open the CSV file for the relevant category.
3. Search for the ID that is misbehaving.
4. If the CSV shows two entries for the same ID, note both asset names.
5. The asset listed second in the CSV is the one currently registered at that ID.
6. The asset listed first has been overwritten.

Resolution

There are three documented resolutions for an ID collision, in order of preference:

1. Change the ID of the conflicting mod item. If the modder controls both mods (or controls the newer mod that is overwriting the older mod), change the legacy ID of one item to an available value. Re-run the Export Asset IDs tool to confirm the new ID is available, then update the .dat or .asset file. This is the cleanest resolution.

2. Change the load order of the conflicting mods. If the modder does not control one of the mods, changing the load order (by renaming the mod folder, which affects filesystem enumeration order) can swap which item overwrites which. This is a fragile resolution that breaks if the load order changes again. It is not recommended as a permanent fix.

3. Use a redirector asset to point the overwritten ID to the correct item. A Redirector Asset with the AssetCategory field set to the appropriate category and TargetAsset set to the correct item's GUID can transparently redirect legacy ID references to the intended asset. This resolution works for asset types that support redirectors and does not require changing either conflicting mod's files.

Critical warning

An ID collision between a mod item and a vanilla item is the most damaging type of collision. The mod item that overwrites a vanilla item at ID 15 (the Eaglefire) will cause the Eaglefire to be replaced by the mod item in every player's game. Players who join a server that requires the Eaglefire for a crafting recipe or a quest will find the recipe or quest broken. Never assign a legacy ID that falls within the 0-4999 reserved range.

The Bypass_ID_Limit field

The Bypass_ID_Limit field is a boolean flag that tells the engine to accept legacy IDs above the 2000 threshold. Without this field, the engine rejects any asset with an ID greater than 2000. The field is required for every mod item that uses a legacy ID above 2000-which is to say, every mod item that follows the cohort convention of using IDs in the 50000+ range.

Field	Type	Required	Default	Purpose
Bypass_ID_Limit	bool	Yes (for IDs above 2000)	Not set	When True, the engine accepts legacy IDs above the 2000 threshold.

The Bypass_ID_Limit field is placed at the root level of the .dat or .asset file, at the same nesting level as ID, GUID, and Type. The field accepts True or False as its value.

ID 50001
GUID a1b2c3d4e5f64a7b8c9d0e1f2a3b4c5d
Type Gun
Name CustomRifle
Bypass_ID_Limit True

Omitting Bypass_ID_Limit True from a mod item with an ID above 2000 is among the most common first-time mod authoring errors. The item will parse correctly (the .dat syntax is valid) but will fail to register at load time. The engine will not produce an error message visible to the player; the item will simply not appear in the asset registry and will not be spawnable via /give.

When to skip the legacy ID entirely

The SDG documentation's recommendation is "ideally, new content should use GUIDs when possible." For asset categories that have fully migrated to GUIDs (objects, vehicles, resources, effects), the legacy ID field can be omitted from the .asset file. The asset will register under its GUID and will be reachable via GUID-based references only.

For items, the legacy ID is still required because of the /give command dependency. However, a modder who is authoring an item that is never intended to be spawned by players (e.g., an internal dependency item used as a blueprint ingredient but never given to players directly) may consider omitting the legacy ID. The item must still be reachable through its GUID in blueprint recipes, and the /give command will not be able to spawn it, which is acceptable for internal-use items.

The cohort's recommendation for internal-use items is to assign a legacy ID anyway, because:

• It costs nothing-an unused legacy ID in the 50000+ range has no performance impact.
• It future-proofs the item: a future update to the mod that makes the item player-spawnable does not require renumbering or compatibility shims.
• It appears in the Export Asset IDs CSV, which makes the mod's full asset inventory auditable in one tool.

Legacy ID allocation for mod series and team development

When multiple modders collaborate on a mod series, or when a single modder maintains multiple parallel mods, the ID allocation problem compounds. Each mod in the series must have its own non-overlapping ID block, and the blocks must be documented so that contributors do not accidentally pick IDs from a block that another contributor's mod uses.

Centralised ID registry (cohort convention)

The cohort convention for multi-mod development is a centralised ID registry-a single document or spreadsheet that lists every ID block claimed by every mod in the series:

Mod name	ID block	First assigned	Last reviewed	Maintainer
Combat Rifle Pack	50000-50049	2025-01-15	2025-06-01	Primary modder
Pistol Expansion	50050-50099	2025-02-20	2025-06-01	Secondary modder
Attachment Pack	50100-50149	2025-03-10	2025-06-01	Primary modder
Ammunition Types	50150-50199	2025-04-05	2025-06-01	Secondary modder

The registry is version-controlled alongside the mod files. Every contributor consults the registry before assigning a new ID. The registry prevents the most common multi-mod collision pattern: two contributors independently picking the same ID range because neither was aware of the other's choice.

Sub-block allocation by item type

Within a mod's ID block, a finer-grained sub-block allocation by item type is sometimes useful for large mods:

Sub-block	Item type	Example IDs
xx000-xx019	Primary weapons	50000-50019
xx020-xx039	Secondary weapons	50020-50039
xx040-xx059	Magazines and ammunition	50040-50059
xx060-xx079	Attachments (sights, grips, barrels)	50060-50079
xx080-xx099	Clothing and gear	50080-50099
xx100-xx119	Consumables and medical items	50100-50119
xx120-xx139	Melee weapons	50120-50139
xx140-xx159	Throwables and deployables	50140-50159

The sub-block convention is optional but useful for large mods that ship dozens of items across multiple categories. The convention makes it possible for a contributor to glance at an ID and infer the item type without consulting the registry.

Worked example: assigning legacy IDs for a new rifle mod

The following worked example traces the complete legacy ID assignment workflow for a hypothetical new rifle mod that adds a custom assault rifle, two magazine variants, and a barrel attachment.

Step 1: Determine the item count

The mod adds:

• 1 rifle (primary weapon)
• 2 magazines (standard box, extended drum)
• 1 barrel attachment

Total: 4 items.

Step 2: Reserve a block with 2x headroom

4 items x 2 = 8 IDs. Reserve a block of 10 IDs for round-number convenience. The block 50000-50009 is selected after consulting the Export Asset IDs CSV and confirming the range is available.

Step 3: Assign IDs

ID	Item name	Item type	Notes
50000	CustomRifle_AR	Gun	Primary weapon
50001	CustomRifle_BoxMag	Magazine	Standard 30-round box
50002	CustomRifle_DrumMag	Magazine	Extended 60-round drum
50003	CustomRifle_Barrel	Barrel attachment	Suppressor-compatible

Step 4: Document in the mod README

## ID Block
This mod uses legacy IDs 50000-50009.
Reserved: 2025-06-01.
Contact: [modder contact information].

Step 5: Verify with the Export Asset IDs tool

After authoring all four .dat files, run the Export Asset IDs tool and confirm that each ID appears exactly once in the Items CSV, with the correct asset name, and with no Reserved flag.

The worked example above is the minimum viable ID assignment for a small mod. A larger mod would reserve a proportionally larger block, and a mod series would additionally register the block in the centralised ID registry.

The Export Asset IDs CSV in detail: reading the reserved flag

The third column of each Legacy ID Availability.csv file is the reserved flag. The flag is either the literal string Reserved or an empty cell. The flag does not indicate who reserved the ID, when it was reserved, or what asset occupies it. It indicates only that the ID is currently occupied by a loaded asset and should not be used for new content.

The reserved flag is a snapshot of the current loadout. If the Export Asset IDs tool is run with no mods loaded, the CSV will only show vanilla reserved IDs. If the tool is run with mods loaded, the CSV will additionally show IDs occupied by those mods. A modder who plans to share a server with specific other mods should run the export with those mods loaded to see the full ID occupancy picture.

The CSV file does not distinguish between a vanilla Reserved and a mod-occupied ID. Both are marked Reserved. The distinction must be inferred from the ID value: IDs below 5000 that carry the Reserved flag are almost certainly vanilla; IDs above 50000 that carry the Reserved flag are almost certainly mod-occupied. IDs in the contested ranges (5000-29999) require manual investigation to determine whether the occupying mod is vanilla or third-party.

Exporting IDs on a dedicated server

Dedicated servers do not have a main menu with an F1 Workshop sub-menu. The Export Asset IDs tool is a client-side feature. A server administrator who needs to audit the legacy ID usage across the server's mod pack must run the export on a client installation that has the same mod loadout as the server. The procedure is:

1. Install the server's full mod pack on a client installation.
2. Launch the client, arrive at the main menu, press F1, and click Export Asset IDs.
3. The exported CSV will reflect the same ID occupancy as the server, because the same mods are loaded.

Server administrators should perform this export before deploying a new mod pack and after adding any new mod to an existing pack. A single ID collision in a server's mod pack can break player inventories, spawn tables, and /give commands across every player on the server.

Legacy IDs and the /give command: edge cases and behaviour

The /give command with an item that has no legacy ID

If an item has a GUID but no legacy ID, the /give command cannot spawn it. The command parser expects a numeric argument and returns "unknown ID" when the argument cannot be resolved. Players who need to spawn GUID-only items must use a server plugin or admin tool that extends the /give command to accept GUIDs or item names. The cohort recommendation is to assign legacy IDs to every player-facing item so that the baseline /give command works without requiring third-party extensions.

The /give command with an item that has a legacy ID but the ID collides

When two items share the same legacy ID (a collision), the /give command spawns the item that was loaded last. The load order is determined by filesystem enumeration, which is not guaranteed to be consistent. A player who types @give MyName 50001 may receive a different item on different game sessions if the load order changes between sessions. This is the most confusing ID collision symptom and the one that generates the most support requests from players.

The /give command and quantity arguments

The /give command accepts an optional quantity argument: @give <player> <ID> <quantity>. For example, @give MyName 50001 10 spawns ten units of the item with legacy ID 50001. The quantity argument is passed to the game's item-spawning code, which respects stack limits. A magazine item with a stack limit of 1 will produce ten separate stack entries in the player's inventory, not a single stack of ten. Consumable items with higher stack limits will be consolidated into as few stacks as the stack limit allows.

Common legacy ID allocation failure modes in published mods

The failure modes below are documented from the cohort's collision history. Each mode represents a specific way that a seemingly correct ID assignment produces a collision in the field.

Failure mode 1: The default-ID trap

A modder creates a new item by copying an existing .dat file as a template and editing the mechanical fields (damage, range, capacity) without changing the legacy ID. The item registers under the template's legacy ID, overwriting the template item. The modder tests the new item in single-player, where it works correctly because the template item is not loaded, and publishes the mod. Players who install the mod alongside the original template item discover that the template item has been overwritten. The fix is to always change the legacy ID (and the GUID) when copying an existing .dat file as a template, even if the new item is similar to the template.

Failure mode 2: The forgotten-block-reservation

A modder runs the Export Asset IDs tool, finds a block of available IDs in the 10000-10019 range, and builds a ten-item mod. A second modder, unaware of the first modder's choice, runs the same tool independently, finds the same block (it appears available because neither mod has loaded the other's content), and builds a five-item mod in the 10000-10004 range. Both mods publish. A server that installs both mods discovers an ID collision on the overlapping IDs. The fix is to always use the 50000-65535 range (where the risk of independent selection of the same block is lower) and to document the chosen block publicly so that other modders can discover it before selecting overlapping IDs.

Failure mode 3: The update-expansion collision

A modder ships a mod with five items in the 50000-50004 range and documents the block as 50000-50009 (twice the projected size, per the cohort convention). A game update introduces a new vanilla item at ID 50005, which falls within the mod's documented block even though the mod does not yet use that ID. The modder later expands the mod to include a sixth item, assigns it ID 50005 (the next available ID in the block), and publishes. Players who have updated their game discover that the new mod item overwrites the new vanilla item. The fix is to re-run the Export Asset IDs tool after every major game update and to adjust the block boundaries if a vanilla item has moved into the reserved range. This failure mode is rare (vanilla items typically stay in the 0-4999 range) but is the reason the cohort convention includes the post-update re-verification step.

Frequently asked questions

What happens if I omit the legacy ID from an item .dat file?

The item will not be registered in the legacy ID table. The /give command will not be able to spawn the item. The item will still be reachable by its GUID (for blueprint recipes, spawn tables, and NPC configuration that use GUID references), but any system that depends on legacy IDs (the /give command, legacy save files, legacy spawn tables) will not see the item.

Can I change a legacy ID after the mod is published?

Technically yes-change the ID field in the .dat or .asset file to the new value. Practically, this breaks every player who has the item in their save file or who uses the /give command with the old ID. Players who have the item in their inventory from the old ID will find the item missing after the update because the save file references the old ID, which no longer resolves. The cohort recommendation is to never change a published legacy ID. If a collision is discovered after publication, use a Redirector Asset to point the old ID to the correct item rather than changing the ID.

What is the difference between a legacy ID and a GUID?

A legacy ID is a 16-bit unsigned integer (0-65535) used for backwards compatibility with the /give command, save files, and legacy spawn tables. A GUID is a 128-bit hexadecimal identifier used for modern asset identity and cross-asset referencing (blueprint recipes, modern spawn tables, NPC configuration). Both are required on every mod item. The legacy ID is scoped to a finite 65536-slot namespace shared across vanilla and all mods; the GUID is scoped to a 2^128 address space and is probabilistically unique.

Why does the /give command not accept GUIDs?

The /give command predates the GUID system. It was designed when the only identity key was the legacy ID, and its parser expects a numeric argument. Updating the /give command to accept GUIDs would be a breaking change to the command's interface and to every script, server plugin, and admin tool that invokes it. SDG has not indicated whether a GUID-capable /give variant is planned.

How do I know if an ID is safe to use?

Run the Export Asset IDs tool (F1 at the main menu, click Export Asset IDs) and open the CSV file for the target asset category. Any ID row where the third column is empty (not marked Reserved) is available. Additionally, confirm the ID falls in the 50000-65535 range, which is the cohort's recommended range for new mod projects.

Can two mods use the same legacy ID if they are never loaded together?

Yes. The collision only manifests when both mods are loaded simultaneously by the same game instance. If two mods are never installed on the same server or the same player's client, the shared ID causes no practical problem. However, the cohort recommendation is to avoid shared IDs even when the mods are unlikely to be used together, because a player who installs both mods as part of a server's mod pack may encounter the collision unknowingly.

What asset types can use GUIDs instead of legacy IDs?

Objects, vehicles, resources, effects, and modern spawn tables can use GUIDs exclusively. Items, legacy spawn tables, and legacy save files require legacy IDs. The SDG documentation explicitly states that items "still rely heavily on legacy IDs" and recommends that items carry both identifiers.

How do I find the legacy IDs used by vanilla items?

Run the Export Asset IDs tool. The generated CSV files list every vanilla ID with the Reserved flag in the third column. The IDs in the 0-4999 range are almost exclusively vanilla-reserved. A modder can also browse the Bundles/Items/ folder in the Unturned™ installation directory and open individual .dat files to find the ID field.

What is the maximum number of items a mod can have?

A mod can have as many items as the modder can fit into the chosen ID block. The theoretical maximum across all mods loaded simultaneously is 65536 (the total legacy ID namespace), minus the IDs occupied by vanilla content (approximately 4000-5000), leaving approximately 60000 IDs for mod content. A single mod is unlikely to approach this limit; the largest published mods typically contain fewer than 500 items.

Do I need a legacy ID for an item that is only used as a blueprint ingredient?

The cohort recommendation is to assign a legacy ID anyway. The item may later become player-spawnable, and assigning the ID now avoids renumbering later. The /give command's inability to spawn the item is acceptable for internal-use items, but the legacy ID costs nothing and provides future flexibility.

How do I handle a situation where my chosen ID block is partially occupied by a recently published mod?

If the Export Asset IDs tool shows that some IDs in the chosen block are occupied by another mod, pick a different block entirely. Overlapping blocks-even if only a few IDs overlap-produce partial-collision behaviour that is harder to diagnose than a full-block collision. A player who installs both mods and tries to spawn an item at one of the overlapped IDs will encounter unpredictable results.

Can legacy IDs be reused after an item is removed from a mod?

Yes, but the cohort strongly advises against it. Players who have the removed item in their save file will find the save file referencing the legacy ID, which now resolves to a different item. The result is item corruption in the player's inventory. If an item must be removed, retire its legacy ID permanently. Do not reassign it to a new item.

Best practices

• Pick an ID block in the 50000-65535 range for every new mod project.
• Reserve a block at least twice the projected item count.
• Run the Export Asset IDs tool before assigning any IDs to confirm availability.
• Document the chosen ID block in the mod's README.
• Add Bypass_ID_Limit True to every mod item with an ID above 2000.
• Never change a published legacy ID. Use a redirector asset to handle collisions discovered after publication.
• Assign IDs sequentially within the block to make occupancy visible at a glance.
• For multi-mod series, maintain a centralised ID registry that all contributors consult before assigning new IDs.
• Re-run the Export Asset IDs tool after major game updates to confirm the block remains available.
• Treat every Reserved ID in the CSV export as permanently off-limits, regardless of whether the vanilla asset is currently loaded.

Appendix A: Legacy ID quick-reference card

Property	Value
Type	uint16
Range	0 through 65535
Reserved (vanilla)	0-4999
Contested (community)	5000-29999
Safe (cohort recommended)	30000-65535 (strong preference: 50000-65535)
Filed in	.dat or .asset root level
Field syntax	ID 50001
Companion field	Bypass_ID_Limit True (required for IDs above 2000)
Audit tool	Export Asset IDs (F1 at main menu)
Audit output path	Extras/AssetIDs/All Assets/Grouped by Legacy Category/
Still required for	Items (for /give command, legacy save files, legacy spawn tables)
Not required for	Objects, vehicles, resources, effects (fully migrated to GUIDs)

Appendix B: Export Asset IDs workflow quick reference

Step	Action	Notes
1	Launch Unturned to the main menu	Load all mod content you want to audit
2	Press F1	Opens the Workshop sub-menu
3	Click Export Asset IDs	Wait for the export to complete
4	Navigate to Extras/AssetIDs/All Assets/Grouped by Legacy Category/	Relative to the Unturned installation directory
5	Open the CSV for the target category	e.g., Legacy ID Availability - Items.csv
6	Scan for available IDs	Empty third column = available; Reserved = occupied
7	Record the chosen block	Document in mod README

Appendix C: Diagnostic table for legacy ID problems

Symptom	Most likely cause	Resolution
Item not spawnable via /give	ID above 2000 and Bypass_ID_Limit missing	Add Bypass_ID_Limit True to the .dat file
/give spawns wrong item	ID collision with another mod	Run Export Asset IDs; change ID or use redirector
Item appears in Export CSV as Reserved	ID falls in vanilla reserved range	Change to an ID in the 50000+ range
Item works in single-player but not on server	Server has a mod with a conflicting ID	Compare ID blocks across installed mods on the server
Save game loads with incorrect items after mod update	Published ID was changed	Restore original ID; use redirector for collision resolution
Export Asset IDs button greyed out or unresponsive	Export already in progress or permissions issue	Wait for current export to complete; check write permissions on Extras/ folder
CSV file empty for a category	No content loaded for that category	Load a map or mod content that includes the target category
Two rows share the same ID in CSV	ID collision detected	Identify the conflicting mods; change one ID
Item loads but has no name in inventory	English.dat missing or not in same folder as .dat	Create English.dat with Name and Description fields
/give command returns "unknown ID"	ID not registered, typo in ID field, or file not loaded	Confirm ID in .dat matches /give argument; confirm file path is under a loaded mod folder

Appendix D: External references

• Smartly Dressed Games official modding documentation - Chapter 148: Legacy ID Availability - the authoritative source for the Export Asset IDs workflow and the legacy-ID-to-GUID migration guidance.
• Unturned on Steam - the Unturned™ store page and community hub.
• GUID Type Reference - the companion article covering the 128-bit GUID type in full detail, including generation, lifecycle, and collision avoidance.
• Project Folder Structure and GUIDs - covers the folder layout, GUID generation methods, and ID range conventions.
• Redirector Asset Reference - the next article in this section; covers the redirector asset type used to resolve legacy ID collisions.
• Item Asset Anatomy - the shared field reference for all item types; documents the ID, GUID, and Bypass_ID_Limit fields.

Document history

Version	Date	Author	Notes
1.0	2025-05-18	57 Studios	Initial publication. Complete legacy ID system reference: reserved ranges, Export Asset IDs workflow, CSV format, ID block conventions, collision diagnosis and resolution, cohort allocation conventions.

Cross-references

• Redirector Asset Reference - the next article in this section; covers the redirector asset type used to transparently resolve legacy ID collisions without changing published IDs.
• GUID Type Reference - the companion data-types article covering the 128-bit GUID identity system that supplements and is progressively replacing legacy IDs.
• Project Folder Structure and GUIDs - covers the folder layout, GUID generation workflow, and ID range conventions.
• Item Asset Anatomy - the shared field reference; documents the ID, GUID, and Bypass_ID_Limit fields used on every item asset.
• Smartly Dressed Games modding documentation - official field reference and the authoritative source for the Export Asset IDs workflow.
• Unturned on Steam - game page and community hub.