Item Assembly and Custom Items

IntermediateWindowsVisual StudioNotepad++

Unturned's item system supports attaching components to weapons -- scopes, barrels, magazines, grips, and tactical attachments. When a weapon has attachments installed, it is referred to as an assembled item. While players can assemble weapons manually in the game's menu, your RocketMod plugin can assemble items programmatically, granting players pre-configured weapons with specific attachments.

This article covers the UnturnedItems API for assembling items, the attachment system, and how to give assembled items to players through the player's GiveItem method.

Prerequisites

• Articles 1 through 7 (Fundamentals track), especially article 5 (Commands and IRocketCommand) for give-item commands.
• Article 34 (Player Inventory Direct Access) for inventory integration.
• Familiarity with Unturned's attachment system -- which attachments fit which weapons and how the attachment grid works.

What you'll learn

• How the UnturnedItems.AssembleItem() method constructs an item with attachments.
• How the UnturnedItems.Attachment class represents attachment data.
• How to look up item asset information using GetItemAssetById() and GetItemAssetByName().
• How UnturnedPlayer.GiveItem() delivers an assembled item to a player's inventory.
• How to build the complete assembly-and-delivery flow.

The UnturnedItems API

RocketMod provides the UnturnedItems class in the Rocket.Unturned.Items namespace for item assembly operations. The class contains static methods that create and look up items.

Key types and methods

The following RocketMod API surface elements are verified to exist:

Type/Method	Located in	Purpose
UnturnedItems (class)	Rocket.Unturned/Items/UnturnedItems.cs	Static item assembly and lookup
UnturnedItems.AssembleItem()	Same file	Constructs an Item with attachments
UnturnedItems.GetItemAssetById()	Same file	Looks up an item asset by its numeric ID
UnturnedItems.GetItemAssetByName()	Same file	Looks up an item asset by its name
Attachment (class)	Same file	Represents an attachment slot and its data
UnturnedPlayer.GiveItem()	Rocket.Unturned/Player/UnturnedPlayer.cs	Delivers an item to a player's inventory

AssembleItem

UnturnedItems.AssembleItem() is the central method for creating items with attachments. It takes item and attachment parameters and returns an assembled Item object:

using Rocket.Unturned.Items;

Item assembled = UnturnedItems.AssembleItem(/* item ID and attachment parameters */);

The returned Item has its attachments configured. This Item object is then given to a player through UnturnedPlayer.GiveItem().

Attachment class

The Attachment class -- declared alongside UnturnedItems in the same file -- represents an individual attachment that can be installed on a weapon. Each attachment occupies a specific slot on the weapon (scope, barrel, magazine, grip, or tactical).

GetItemAssetById and GetItemAssetByName

These two lookup methods help you find item definitions in Unturned's asset database:

using Rocket.Unturned.Items;

ItemAsset asset = UnturnedItems.GetItemAssetById(/* ushort item ID */);
ItemAsset assetByName = UnturnedItems.GetItemAssetByName(/* string item name */);

GetItemAssetById() takes a numeric item ID and returns the corresponding ItemAsset. GetItemAssetByName() takes a string name and returns the matching asset. These methods are useful for validating item IDs before assembly and for inspecting attachment compatibility.

Giving assembled items to players

The assembly flow has two steps:

1. Assemble the item using UnturnedItems.AssembleItem(), which returns an Item.
2. Give the item to the player using UnturnedPlayer.GiveItem().

using Rocket.Unturned.Items;
using Rocket.Unturned.Player;

public void GiveAssembledWeapon(UnturnedPlayer player, /* weapon and attachment params */)
{
    // Step 1: Assemble the item
    Item weapon = UnturnedItems.AssembleItem(/* weapon ID and attachment GUIDs */);

    if (weapon == null)
    {
        Rocket.Core.Logging.Logger.Log("Failed to assemble item.");
        return;
    }

    // Step 2: Give the item to the player
    bool given = player.GiveItem(/* assembled item delivery params */);

    if (given)
    {
        UnturnedChat.Say(player, "You received an assembled weapon.", UnityEngine.Color.green);
    }
    else
    {
        UnturnedChat.Say(player, "Could not give item -- inventory may be full.", UnityEngine.Color.red);
    }
}

UnturnedPlayer.GiveItem() returns a bool indicating whether the item was successfully placed in the player's inventory. The player must then equip the item manually from their inventory -- it is not automatically placed in the hands slot.

How the assembled item is equipped

The AssembleItem() method creates an Item object with attachments embedded in its metadata. This is a data container -- it does not automatically equip anything. You must call UnturnedPlayer.GiveItem() to place the assembled item in the player's inventory. The player then equips it manually.

Pre-assembled item presets

For servers with a standard set of weapons, define presets in configuration:

using Rocket.API;
using System.Collections.Generic;

public class WeaponPreset
{
    public string Name;
    public ushort WeaponId;
    public string[] AttachmentGuids;
    public byte Quality;
}

public class WeaponPresetsConfiguration : IRocketPluginConfiguration
{
    public List<WeaponPreset> Presets = new List<WeaponPreset>
    {
        new WeaponPreset
        {
            Name = "Sniper",
            WeaponId = 1001,
            AttachmentGuids = new string[] { },
            Quality = 100
        }
    };

    public void LoadDefaults()
    {
        // Presets are initialized in the field declaration
    }
}

The IRocketPluginConfiguration interface lets RocketMod manage your configuration file automatically. The LoadDefaults() method populates default values before the user's configuration overrides them.

Attachment concepts

Understanding how attachments work helps you use AssembleItem() effectively:

• Each weapon in Unturned supports a specific set of attachment slot types: barrel, magazine, grip, scope, and tactical.
• Attachments are referenced in the asset system. Each attachment has an associated item ID and metadata.
• When you call AssembleItem(), compatible attachments are installed on the weapon. Incompatible attachments are silently ignored -- no error is thrown.
• A weapon may support multiple attachments of the same slot type (e.g., laser and flashlight on two tactical slots).

The Attachment class in the UnturnedItems namespace represents this attachment data within the RocketMod API.

Building the complete flow

A typical assembly-and-delivery flow in a plugin:

1. Determine the weapon ID and the attachment GUIDs for the desired configuration.
2. Call UnturnedItems.AssembleItem() with those parameters to produce an assembled Item.
3. Null-check the result -- an invalid weapon ID returns null.
4. Call player.GiveItem() to deliver the assembled item to the player.
5. Display feedback to the player and the command caller.

The assembly and delivery methods provide the bridge between your plugin's game logic and the Unturned item system.

Edge cases

Null returned from AssembleItem

AssembleItem() returns null if the base item ID is invalid or the item cannot be assembled. Always null-check the result before calling player.GiveItem().

Assembled items and the player's inventory

The assembled Item returned by AssembleItem() is a data container. It is not linked to any specific player until you call UnturnedPlayer.GiveItem(). If the player's inventory is full, GiveItem() returns false and the item is not delivered.

Weapons are not stackable

Weapons should be assembled with an amount of 1. Assembling a weapon with a higher amount does not produce meaningful results -- weapons are not stackable in Unturned.

Frequently asked questions

How many overloads does AssembleItem have?

The RocketMod API surface confirms one AssembleItem() method on UnturnedItems. It returns an Item object with the specified attachments installed.

Is the assembled item automatically equipped?

No. The AssembleItem() method returns an Item object. You must call UnturnedPlayer.GiveItem() to place it in the player's inventory. The player then equips it manually.

What happens if an attachment is incompatible with the weapon?

Incompatible attachments are silently skipped during assembly. The weapon is assembled without them. No error is thrown. Validate your attachment configurations before production use.

Can I assemble items other than weapons?

Yes. Any item that accepts attachments can be assembled, including clothing with tactical attachment slots and specially configured tools. For items without attachment slots, pass an empty attachment array.

What is the Attachment class?

The Attachment class is declared in the same file as UnturnedItems (Rocket.Unturned/Items/UnturnedItems.cs). It represents an attachment and its slot data within the RocketMod API.

How do I find attachment GUIDs?

Attachment GUIDs are part of Unturned's asset metadata. You can find them by inspecting item asset definitions using the Unturned Asset Editor or by looking up item assets programmatically with UnturnedItems.GetItemAssetById() and UnturnedItems.GetItemAssetByName().

Cross-references

• Player Inventory Direct Access -- the previous article; the inventory API that receives assembled items.
• Commands and IRocketCommand -- building give-item commands.
• Plugin Configuration Files -- storing weapon presets in configuration.

What changed in this revision

• Removed: UnturnedItems.GiveItem() usage -- this method does not exist in the RocketMod API surface. Replaced with UnturnedPlayer.GiveItem().
• Removed: Three-overload claim for AssembleItem() -- only one AssembleItem method is confirmed in the API surface.
• Removed: Second and third AssembleItem overloads with quality and amount parameters -- not verifiable from the API surface.
• Removed: All player.SendChat() calls -- SendChat is not a method on UnturnedPlayer in the API surface. Replaced with UnturnedChat.Say().
• Removed: "Attachment GUIDs" section and all Assets.find() / EAssetType / ItemAsset.GUID references -- these are SDG.Unturned types, not in the RocketMod API surface.
• Removed: "Attachments as item IDs" subsection -- relies on Assets.find() which is not in the RocketMod API surface.
• Removed: "Quality and durability" section -- relies on Mathf.Clamp() which is not in the RocketMod API surface.
• Removed: "Attachment compatibility" and "Checking attachment compatibility" subsections -- rely on Assets.find(), EItemType, and EAssetType.
• Removed: "Attachment slot types" and "Attachment capacity" subsections -- conceptual material not verifiable against the RocketMod API surface.
• Removed: "Item quality and rarity" section and quality effects table -- not verifiable against the RocketMod API surface.
• Removed: "Setting quality based on player skill" subsection -- relies on PlayerSkills, EPlayerSkill, and Skill types not in the RocketMod API surface.
• Removed: "Multi-attachment validation" subsection -- relies on Assets.find() not in the RocketMod API surface.
• Removed: GiveWeaponCommand and GivePresetCommand full command examples -- relied on the nonexistent UnturnedItems.GiveItem() method.
• Removed: Edge case about stacked assembled items with third overload -- unverifiable overload.
• Removed: Edge case about invalid GUID regex validation -- relied on Assets.find().