======

This plugin has 2 parts, all contained in a single DLL with no needed dependencies. Firstly, This plugin adds a number of custom items (detailed below) for server hosts to use on their servers. Currently, these items can either be given to Subclasses (using: Advanced Subclassing), spawned around the map at pre-defined locations (valid locations listed below), or via commands. Secondly, This plugin also provides a very powerful API for other developers to use, for the creation of their own unique, custom items. This API includes item tracking, handles reloading weapons with non-standard clip sizes, and much, much more, automatically, with no concious effort from the developer using it. Overrideable methods are provided to hook your weapon into your own custom event handlers for handling it's logic as necessary.

Config settings for the individual items will NOT be found in the default plugin config file. Instead they will be located in ~/.config/EXILED/Configs/CustomItems on Linux or %AppData%\EXILED\Configs\CustomItems on Winblows. The default config file will be named "global.yml" however, the file used can be changed for each SCP server via that server's normal plugin config file, if you wish to run multiple servers with different custom item config settings.

The actual config values for the items should have descriptions and names that make them self-explanatory.

The following list of locations are the only ones that are able to be used in the SpawnLocation configs for each item: (Their names must be typed EXACTLY as they are listed, otherwise you will probably break your item config file)

Inside012
Inside012Bottom
Inside012Locker
Inside049Armory
Inside079Secondary
Inside096
Inside173Armory
Inside173Bottom
Inside173Connector
InsideEscapePrimary
InsideEscapeSecondary
InsideIntercom
InsideLczArmory
InsideLczCafe
InsideNukeArmory
InsideSurfaceNuke
Inside079First
Inside173Gate
Inside914
InsideGateA
InsideGateB
InsideGr18
InsideHczArmory
InsideHid
InsideHidLeft
InsideHidRight
InsideLczWc
InsideServersBottom

Tl;dr - All you need to do is make a class that inherits CustomItem, CustomWeapon or CustomGrenade (depending on what kind of item you're making), override LoadEvents() and UnloadEvents() to register event handlers to the weapon, then inside the event handlers, start everything with

if (CheckItem(ev.Player.CurrentItem))

CheckItem() will accept both a SyncItemInfo or a Pickup, and will return true if it's the custom item THAT BELONGS TO YOUR CLASS. Note that your class is considered a MANAGER, not an individual weapon. Then instantiate the new class and register it as a custom item:

new SomeItem(ItemType, int).RegisterCustomItem();

The parameters needed will depend on what kind of item you're making, weapons will also require you to provide a clip size in the constructor.

Long version:

Each item class is a manager for all items of that type on the server. When you instantiate a new class that inherits from CustomItem, CustomWeapon or CustomGrenade, it will create a new list of both SyncItemInfos and Pickups. CheckItem() will check those lists to see if the object checked is in one of those lists. If it returns true, it's an item your manager is in charge of. If it returns false, it's not your item.

You cannot cast SyncItemInfo or Pickup as a custom item - IE:

TranqGun tranqGun = (TranqGun)ev.Player.CurrentItem();

Will result in an invalid cast exception. If you need to check if an item belongs to specific manager other than the class you're in already, do this:

foreach (CustomItem item in CustomItems.API.API.GetInstalledItems())
    if (item.ItemName == "TG-119" && item.CheckItem(ev.Player.CurrentItem())
    {
        // do stuff
        break;
    }

To create your own custom item, you'll first want to create the class, an example:

public class SomeItem : CustomItem
{
    public SomeItem(ItemType type, int id) : base(type,id)
    {}
    
    public override string ItemName = "SomeItemName";
    protected override string ItemDescription = "Some description of what your item is/does.";
    //If you want this item to have custom spawn locations on the map
    protected override Dictionary<SpawnLocation, float> SpawnLocations = YourPlugin.Singleton.Config.SpawnLocations;
    
    protected override void LoadEvents()
    {
        Exiled.Events.Handlers.Player.SomeEvent += OnSomeEvent;
        base.LoadEvents();
    }
    protected override void UnloadEvents()
    {
       Exiled.Events.Handlers.Player.SomeEvent -= OnSomeEvent;
       base.UnloadEvents();
    }
      
    public void OnSomeEvent(SomeEventEventArgs ev)
    {
      if (CheckItem(ev.Player.CurrentItem))
      {
          // this is your item, do whatever you want with it.
      }
    }
}

And then you would register it either in a way similar to how this plugin registers it's own custom items, or alternatively:

public Plugin : Plugin<Config>
{
    public override void OnEnabled()
    {
        Timing.CallDelayed(5f, () => new SomeItem(ItemType.SomeType, 42).RegisterCustomItem());
    }
}

Do note, if you're registering your item in your plugin's OnEnabled() method, you MUST add a minimum of 5sec delay before registering, to ensure all other plugins are loaded and that the server process has initialized all of it's components and such.

• NeonWizard for the original TranqGun
• Killer0992 for the original Shotgun
• Dimenzio for the SpawnGrenade method
• Michal78900 for SCP-1499
• SebasCapo for slight API rework.