Introduction to Items
Items in Unturned encompass anything that can be carried in a player’s in-game inventory. All items will share certain properties, but each item type may have its own unique properties as well. Please refer to Asset Definitions and Asset Bundles for the full documentation regarding assets and asset bundles.
Unity Asset Bundle Contents
An example of an item being set up in the Unity editor.
To get started, create a new folder for your custom item. The name of this folder will be relevant when further configuring your item after it has been exported from Unity.
Item (Prefab)
Inside this folder, create a new Prefab named “Item”. This should be tagged as 4: Item, and layered as 13: Item. Open the “Item” Prefab.
Items can have multiple colliders including different types, but just attaching a Box Collider component to the root GameObject will usually suffice. It is recommended to use a minimum dimension of (0.2, 0.2, 0.2), because the large colliders are less likely to fall through a thin surface in a single physics tick.
If your item only has one LOD, you can attach Mesh Filter and Mesh Renderer components directly to the root GameObject. Configure these components as desired.
It is recommended to have multiple LODs for your item, so that less needs to be rendered when the item is far away. If your item should have multiple LODs, attach a LOD Group component to the root GameObject. Create a child GameObject for each LOD, named “Model_#” (e.g., “Model_0”, “Model_1”). Attach the Mesh Filter and Mesh Renderer components to each one. Configure these components as desired.
Add a new child GameObject named “Icon” to the root GameObject. This will be used to draw an icon with an orthographic camera. By default, the game will automatically calculate the position and size of the camera – so the only thing that needs to be configured is its orientation. To test the orientation of your icon, temporarily attach a Camera component with its Projection property set to “Orthographic”. When satisified, delete the Camera component.
Animations (Prefab)
For equippable items, a Prefab named “Animations” is required. The Prefab and the animations included can either be created from scratch, or they can be duplicated from the provided Unity packages.
If you have installed the ExampleAssets.unitypackage we provide, you can find the vanilla animations for most item types in the game. Prefabs can be found along the CoreMasterBundle/Items path, while the raw animation files can be found along Game/Sources/Animations.
To create the Prefab from scratch instead, add a new Prefab named “Animations” in your custom item’s folder. Add an Animation component to the root GameObject of the “Animations” Prefab.
Every equippable item should have an animation named “Equip”. If your weapon should be inspectable, it should also have an “Inspect” animation.
Equip (Audio Clip)
To have a sound play when the item is equipped, include an Audio Clip named “Equip” in your custom item’s folder.
Skin Base Textures
Note
We should eventually add more documentation about this, but items support texture masking. This is rarely relevant for modders creating their own items, but it is important for skins. Items can optionally include Albedo_Base.png, Metallic_Base.png, or Emission_Base.png textures in their asset-bundled files. When using certain skins, those parts will be masked out and retain their original material.
Game Data File
The GUID, Type, and ID properties are required by all item assets. Most item assets will usually want (or need) to include the Rarity, Useable, Slot, Size_X, and Size_Y properties as well, with only a few excepions.
Properties
Property Name |
Type |
Default Value |
|---|---|---|
See description |
||
|
||
|
||
deprecated |
||
|
||
See description |
||
See description |
||
|
||
|
||
|
||
|
||
See description |
||
|
||
|
||
See description |
||
See description |
||
|
||
|
||
|
||
|
||
|
||
|
||
See description |
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
EEquipableModelParent Enumeration
Named Value |
Description |
|---|---|
|
Item is attached to Right_Hook. |
|
Item is attached to Left_Hook. |
|
Item is attached to Spine. |
|
Item is attached to Spine_Hook, an optional extra child bone of the Spine bone. |
EUseableType Enumeration
Named Value |
Description |
|---|---|
|
Does not correspond to any useable type. |
|
Corresponds to the “Clothing” useable type. |
|
Corresponds to the “Gun” useable type. |
|
Corresponds to the “Consumeable” useable type. |
|
Corresponds to the “Melee” useable type. |
|
Corresponds to the “Fuel” useable type. |
|
Corresponds to the “Carjack” useable type. |
|
Corresponds to the “Barricade” useable type. |
|
Corresponds to the “Structure” useable type. |
|
Corresponds to the “Throwable” useable type. |
|
Corresponds to the “Grower” useable type. |
|
Corresponds to the “Optic” useable type. |
|
Corresponds to the “Refill” useable type. |
|
Corresponds to the “Fisher” useable type. |
|
Corresponds to the “Cloud” useable type. |
|
Corresponds to the “Arrest_Start” useable type. |
|
Corresponds to the “Arrest_End” useable type. |
|
Corresponds to the “Detonator” useable type. |
|
Corresponds to the “Filter” useable type. |
|
Corresponds to the “Carlockpick” useable type. |
Property Descriptions
Add_Default_Actions bool
If true, actions are automatically created for refill ammo, repair, and salvage blueprints. Defaults to true if no Actions are specified.
Allow_Manual_Drop bool true
Item can be manually dropped by the player.
Amount uint8 1
Maximum capacity for container-like items, such as ammunition boxes. Typically used with Count_Min and Count_Max.
Bypass_Hash_Verification bool false
Disable hash verification check, and allow for mismatched files.
Bypass_ID_Limit flag
Allows for using an ID value within the range reserved for official content.
Can_Player_Equip bool
Controls whether or not this item can be equipped by the player. This property technically requires that Useable has been configured to any value other than None, as items are not equippable without the functionality provided by having a Useable class.
While the inclusion of this property may seem unorthodox, it does have some niche uses. For example, you could create a gun that can only be used by sentries.
This property defaults to true if the Useable property has been set. Otherwise, this defaults to false.
Can_Use_Underwater bool
Item can be used while underwater. If the Slot property has not been set to Primary, then this defaults to true. Otherwise, this defaults to false.
Count_Min uint8 1
Minimum amount to generate, for container-like items. Typically used with Count_Max and Amount.
Count_Max uint8 1
Maximum amount to generate, for container-like items. Typically used with Count_Min and Amount.
Destroy_Item_Colliders bool true
If false, colliders are not destroyed when the “Item” Prefab is attached to the character. For example equipped vanilla guns do not have any colliders, but some mods (e.g., riot shields) may have relied on child colliders not being destroyed.
Equipable_Movement_Speed_Multiplier float32 1
Multiplies character movement speed while equipped in the player’s hands. If a gun is equipped, then any gun attachment multipliers are combined as well.
EquipableModelParent EEquipableModelParent
Overrides which transform to attach the item to when equipped by the player. Spine may be a better interpolation space for items with animations moving the model between hands.
Normally, this property defaults to RightHook. However, items using the deprecated Backward flag will cause this to instead use LeftHook.
EquipablePrefab Master Bundle Pointer
Overrides the model spawned when this item is equipped. For example, the “Equipable” Prefab could use an animated skinned mesh component while the regular “Item” Prefab only needs a static mesh component.
EquipAudioClip Master Bundle Pointer Equip
AudioClip to play when equipping.
GUID GUID
Refer to GUID documentation. Item assets are required to have this property.
Tip
If the GUID property has been omitted from the asset file, then the game will automatically attempt to assign a random (and unique) GUID during a successful load.
ID uint16 0
Must be a unique identifier. Item assets are required to have this property.
Ignore_TexRW flag
Read/writeable texture errors regarding this asset should be hidden from the error logs.
InspectAudioDef Master Bundle Pointer
AudioClip or OneShotAudioDefinition to play when item is inspected.
Instantiated_Item_Name_Override string
Name to use when instantiating “Item” Prefab. By default, the value of ID is used. Since Unity’s built-in Animation component references GameObjects by name, this property can help share animations between items.
InventoryAudio Master Bundle Pointer
AudioClip or OneShotAudioDefinition to play when item is picked up, moved within the inventory, and dropped. Default value is dependent on the child asset.
Left_Handed_Characters_Mirror_Equipable bool true
If false, the equipped item model is mirrored to counteract the mirrored character.
Override_Show_Quality bool false
Override to forcefully show item quality.
Pro flag
This is a Steam Economy item.
Procedurally_Animate_Inertia bool true
Whether viewmodel should accumulate angular velocity from animations. Useful for low-quality older animations, but should probably be disabled for high-quality newer animations.
Quality_Max uint8 90
Maximum quality to generate. Typically used with Quality_Min.
Quality_Min uint8 10
Minimum quality to generate. Typically used with Quality_Max.
Rarity EItemRarity Common
Rarity of the item, as text shown in menus and colors used for highlights.
Should_Delete_At_Zero_Quality bool false
Item should be deleted when at 0% quality.
Should_Drop_On_Death bool true
Item should be dropped on death.
Size_X uint8 1
In slots, the total width of the inventory space (i.e., the number of columns).
Size_Y uint8 1
In slots, the total height of the inventory space (i.e., the number of rows).
Size_Z float32 -1
Manually specify orthogonal camera size for item icons. This directly corresponds to the value of a Camera component’s Size property in Unity.
Size2_Z float32 -1
Orthogonal camera size for economy icons.
Slot ESlotType None
Which equipped item slot an item is valid to be equippable in. This is only relevant if your property has configured the Useable property.
Nonerestricts the useable item to hotkeys.Primaryrestricts the useable item to the primary slot.Secondaryrestricts the useable item to the primary or secondary slots.Tertiaryis not implemented by this asset.Anyhas no restrictions on slots or hotkeying.
Type EItemType
Designates the item’s class. Item assets are required to have this property.
Use_Auto_Icon_Measurements bool true
Automatically calculate axis-aligned item icon camera size from bounds.
Use_Auto_Stat_Descriptions bool true
If true, properties like damage, storage, health, etc. are appended to the description.
Useable EUseableType Enumeration None
Setting this property adds functionality from a corresponding Useable class. Unless Can_Player_Equip has been configured otherwise, this at least means the item is equippable.
This property is often used in conjunction with the Slot property, which determines where an item can be equipped from.
Blueprints and Actions
In addition to the properties already described, item assets can utilize properties for crafting blueprints and context menu actions.
Localization
Name string: Item name in user interfaces.
Description Rich Text: Item description in user interfaces.