Custom Item Definitions

Works with

About Custom Item Definitions

Quote

This plugin does not have its own functionality. This plugin is only used as a library for other plugins.

This library allows developers to create their own ItemDefinitions, which will allow them to create custom items with their own unique values.

What is an ItemDefinition created with the library?
It is a full-fledged ItemDefinition just like the other ones created by Rust developers, a new item definition is created based on an existing one with modified settings.
It has its own shortname and itemid, and can also have its own itemMods created by the developer, which is very convenient.
You can use the give command, item.info.[anything], and any other way you want.

A simple example of item creation:

using Oxide.Core.Plugins;
using System;
using System.Collections.Generic;

namespace Oxide.Plugins
{
    [Info("CIDLibraryDemo", "0xF", "0.0.0")]
    partial class CIDLibraryDemo : RustPlugin
    {
        [PluginReference]
        private Plugin CustomItemDefinitions;

        public static CIDLibraryDemo Instance;
        private static readonly ItemDefinition PARENT_DEFINITION = ItemManager.FindItemDefinition("longsword");

        void Init()
        {
            Instance = this;
            Unsubscribe(nameof(OnCIDLoaded));
        }

        void Loaded()
        {
            Subscribe(nameof(OnCIDLoaded));
            if (CustomItemDefinitions != null)
                OnCIDLoaded();
        }

        void OnCIDLoaded(Plugin library = null)
        {
            CustomItemDefinitions ??= library;
            RegisterItems();
        }

        private void CheckCID()
        {
            if (CustomItemDefinitions == null)
                throw new Exception("The library CustomItemDefinitions not installed or loaded. Please download it from https://codefling.com/extensions/custom-item-definitions");

            if (CustomItemDefinitions.Version.Major < 2)
                throw new Exception("The version of the CustomItemDefinitions library being used is outdated for use by this plugin. Use version 2.* or higher.");
        }

        private void RegisterItems()
        {
            CheckCID();

            CustomItemDefinitions.Call<ItemDefinition>("Register", new
            {
                // Not all available fields are listed here.
                // You can view all available fields by looking at the CustomItemDefinition class in the library.
                shortname = "test.demoitem",
                parentItemId = PARENT_DEFINITION.itemid,
                maxStackSize = 1,
                category = ItemCategory.Weapon,
                defaultName = "Name for an item with multilingual support", // autogenerate from string OR new Translate.Phrase("some_token_for_name", "english-version")
                defaultDescription = "Description for an item with multilingual support", // autogenerate from string OR new Translate.Phrase("some_token_for_desc", "english-version")
                defaultSkinId = 2973264769,
                staticOwnerships = new List<(Translate.Phrase label, Translate.Phrase text)>
                {
                    new ("TEST 1", "Test 1 ToolTip"), // OR new (new Translate.Phrase("lang_static_ownership_label_1", "TEST 1"), new Translate.Phrase("lang_static_ownership_text_1", "Test 1 ToolTip")) 
                    new ("TEST 2", "Test 2 ToolTip"), 
                },
                itemMods = new ItemMod[]
                {
                    PARENT_DEFINITION.GetComponent<ItemModEntity>(), // This modifier is responsible for the sword's Held Entity and is present in the parent, but you can create your own.
                    new ItemModTest()
                    {
                        onItemCreatedLogMessage = "Custom item created with ID: {0}"
                    }
                }
            }, this);
        }

        private class ItemModTest : ItemMod
        {
            public string onItemCreatedLogMessage;

            public override void ModInit()
            {
                base.ModInit();
                CIDLibraryDemo.Instance.Puts("ModInit");
            }

            public override void OnItemCreated(Item item)
            {
                base.OnItemCreated(item);
                if (!string.IsNullOrEmpty(onItemCreatedLogMessage))
                    CIDLibraryDemo.Instance.Puts(string.Format(onItemCreatedLogMessage, item.uid));
            }

            // Used when a player is attacked for an item with the ItemModWearable mod when ItemModWearable.ProtectsArea().
            // Not applicable to the item in the example, only mentioned for illustrative purposes.
            // There are other methods of overriding.
            public override void OnAttacked(Item item, HitInfo info)
            {
                base.OnAttacked(item, info);
                CIDLibraryDemo.Instance.Puts(string.Format("OnAttacked | Item ID: {0}", item.uid));
            }
        }
    }
}

What are some things to keep in mind?

Follow the example;
The author will not do your work for you; learn how items and mods work. You can start here: wiki.facepunch.com
You must take care to register unique shortname.
ItemId should never be changed in your plugin, as items created with an old itemId will break if they don't have their definition.
After your plugin is unloaded, all items created with your item definitions will lose interaction, as all ItemMods will be removed. This is done for safety, don't worry, after loading the plugin back in, all items will work again as before.

CustomItemDefinition class structure:

public class CustomItemDefinition : Pool.IPooled
{
            public int parentItemId; // required
            public string shortname; // required
            public int? itemId;
            public Translate.Phrase defaultName;
            public Translate.Phrase defaultDescription;
            public ulong defaultSkinId;
            public int? maxStackSize;
            public ItemCategory? category;
            public ItemDefinition.Flag flags;
            public ItemMod[] itemMods; // required
            public bool repairable;
            public bool craftable;
            public List<ItemAmount> blueprintIngredients;
            public int workbenchLevelRequired;
            public List<(Translate.Phrase label, Translate.Phrase text)> staticOwnerships;
}

ItemMods details:
ItemMods are overwritten, this means the new item definition will not include the itemMods of the parent.
If you need to import an item mod from the parent, you can use

PARENT_DEFINITION.GetComponent<ItemModWhatYouNeed>()

if you need to import everything ItemMods

PARENT_DEFINITION.itemMods

Custom itemMods are added using the method of creating a new class, i.e.

new YourItemMod()

Here you can also specify the fields you want, example:

new YourItemMod() {
      field: value
}

Quick answers to questions:

Items have become coal, what does that mean?
This is a fallback ItemDefinition in case the plugin providing this item is no longer available. The items will be restored if the plugin is returned.
Will there be a video?
No, it's library.
Where can I learn more about this?
Disassembling and self-study. Explore the workings of ItemDefinition and their mods on your own.
Here's a little overview on items from Facepunch: https://wiki.facepunch.com/rust/Items_Overview