ItemAPI

ItemAPI

An easy to use ItemAPI for Burglin Gnomes.

Created by Mattcy1.

Features

• Allows for easy custom wearable/hands items!
• Support for custom crafting recipes, and cabinet spawnings!

Documentation

Getting started

Add a reference to ItemAPI.dll in your project, then make ItemAPI a dependency in your plugin's BepInPlugin attribute (or just make sure your plugin loads after it). Inside your plugin's Awake method you always need to call ItemAPI.ItemAPI.Init(Logger), this is what registers your mod's assembly so ItemAPI can find and register your equipment/recipe classes.

Making a custom item

Every item is a class that inherits from ItemAPI.Equipment. This is where you set the name, description, icon, and behavior of your item.

public class ExampleItem: ItemAPI.Equipment

{

public override string Name => "Example Item";

public override string Description => "Keeps the thoughts out.";

public override ItemData.EquipmentType ItemType => ItemData.EquipmentType.Hat;

public override Sprite Icon => ItemAPI.LoadSpriteFromEmbedded("MyMod.Assets.exampleitem.png");

public override GameObject Prefab => ItemAPI.LoadGameObject("mymod.assetbundle", "ExampleItem");

public override int? maxDurability => 50;

public override int? maxStackSize => 1;

public override void OnEquip(GameObject visualObject, PlayerNetworking player)

{

// do stuff when the player puts it on

}

public override void OnUnequip(PlayerNetworking player)

{

// do stuff when it comes off

}

}

You don't need to manually register the class anywhere, ItemAPI finds every class in your assembly that inherits from Equipment and registers it automatically once the game loads its localization tables. Just make sure the class isn't abstract and has a public parameterless constructor.

Available overrides on Equipment:

| Member | What it's for |

|---|---|

| Name | Item name, required |

| Description | Item description, required |

| ItemType | Hat, Hand item, etc, required |

| Icon | Sprite shown in inventory |

| Prefab | The GameObject used both when equipped and when dropped in the world |

| maxDurability | Leave null for no durability tracking |

| maxStackSize | Leave null to default to 1 |

| DroppedSize / DroppedOffset | Scale/position of the item when it's lying on the ground, if you don't set these it'll try to guess something sensible |

| RoomsToSpawn / SpawnChance | Used for cabinet spawning, see below |

And the events you can hook into: OnEquip, OnUnequip, OnLeftClick, OnLost, OnBreak, OnDurabilityChange, OnPickup.

OnLost fires when the item gets dropped from an inventory (not necessarily from being equipped). OnLeftClick fires when the player left clicks while the item is equipped in any slot, with isHolding telling you if it was a quick click or a hold.

OnEquip is where you handle visual via VisualObject which is just a game object loaded from the Prefab Can be parented to the player and all

Durability

If you set maxDurability, you can damage the item with:

ItemAPI.ConsumeItemDurability(myItem.ItemIndex, amountToRemove);

This works fine over the network, it doesn't matter if you're host or client, it'll still reach the server correctly. When durability reaches zero the item breaks, and OnBreak runs instead of OnDurabilityChange.

Spawning items

To spawn an item (or an enemy) into the world:

ItemAPI.RequestSpawn("Example Item", somePosition, "MyUniqueSpawnId");

The unique id is optional (pass null), it just gets passed back through the onItemSpawnedViaRequest / onEnnemySpawnedViaRequest events so you can tell your own spawns apart from everything else.

To give an item straight to a player's inventory instead of dropping it in the world:

ItemAPI.RequestInventoryItem("Example Item", 1);

Both of these work correctly whether the local player is host or client.

Cabinet spawns

If you set RoomsToSpawn and SpawnChance on your Equipment, it will have a chance to spawn inside cabinet drawers automatically whenever a cabinet is opened for the first time,