Documentation Index
Fetch the complete documentation index at: https://mintlify.com/Bill3621/CustomItems/llms.txt
Use this file to discover all available pages before exploring further.
CustomItems is the central static class for managing all custom items in your plugin. It provides methods to register custom items, spawn them in the world, give them to players, and retrieve registered items.
Properties
A list of all registered custom items. This is a read-only copy of the internal registry.
CurrentItems
Dictionary<ushort, CustomItem>
A dictionary mapping item serial numbers to their corresponding custom item instances. This tracks all active custom items currently in the game world or player inventories.
Registration Methods
Register
Registers a single custom item with the CustomItems system.
public static void Register(CustomItem item)
The custom item instance to register
InvalidOperationException - If an item with the same name is already registered
Example:
var healingCandy = new HealingCandy();
CustomItems.Register(healingCandy);
RegisterAll
Automatically discovers and registers all custom item types in the calling assembly.
public static List<CustomItem> RegisterAll()
List<CustomItem> - A list of all successfully registered items.
Example:
public override void OnEnabled()
{
var registeredItems = CustomItems.RegisterAll();
Log.Info($"Registered {registeredItems.Count} custom items");
}
Unregistration Methods
Unregister
Unregisters a single custom item from the CustomItems system and removes all active instances.
public static void Unregister(CustomItem item)
The custom item instance to unregister
InvalidOperationException - If the item is not currently registered
Example:
var healingCandy = CustomItems.AllItems.FirstOrDefault(i => i.Name == "Healing Candy");
if (healingCandy != null)
{
CustomItems.Unregister(healingCandy);
}
UnregisterAll
Unregisters all custom items from the calling assembly.
public static List<CustomItem> UnregisterAll()
List<CustomItem> - A list of all unregistered items.
Example:
public override void OnDisabled()
{
var unregisteredItems = CustomItems.UnregisterAll();
Log.Info($"Unregistered {unregisteredItems.Count} custom items");
}
Retrieval Methods
GetById
Retrieves a registered custom item by its unique ID.
public static CustomItem GetById(ushort id)
The unique ID of the custom item
CustomItem - The custom item with the specified ID, or null if not found.
Example:
var item = CustomItems.GetById(0);
if (item != null)
{
Log.Info($"Found item: {item.Name}");
}
GetIdByName
Retrieves the ID of a registered custom item by its name.
public static ushort GetIdByName(string name)
The name of the custom item
ushort - The ID of the custom item.
Throws:
KeyNotFoundException - If no item with the specified name is found
Example:
try
{
ushort id = CustomItems.GetIdByName("Healing Candy");
Log.Info($"Healing Candy ID: {id}");
}
catch (KeyNotFoundException)
{
Log.Error("Healing Candy not found!");
}
Spawn Methods
TrySpawn
Attempts to spawn a custom item in the world at the specified position.
public static bool TrySpawn(ushort id, Vector3 position, out Pickup pickup)
The ID of the custom item to spawn
The world position where the item should be spawned
Output parameter that receives the created pickup object, or null if spawning failed
bool - True if the item was spawned successfully, false otherwise.
Example:
ushort candyId = CustomItems.GetIdByName("Healing Candy");
Vector3 spawnPos = new Vector3(0, 2, 0);
if (CustomItems.TrySpawn(candyId, spawnPos, out Pickup pickup))
{
Log.Info($"Spawned item at {spawnPos}");
}
else
{
Log.Error("Failed to spawn item");
}
TryGive
Attempts to give a custom item to a player.
public static bool TryGive(ushort id, Player player, out Item item, ItemAddReason addReason = ItemAddReason.Undefined)
The ID of the custom item to give
The player who should receive the item
Output parameter that receives the created item object, or null if giving failed
addReason
ItemAddReason
default:"ItemAddReason.Undefined"
The reason the item is being added to the player’s inventory
bool - True if the item was given successfully, false otherwise.
Example:
ushort candyId = CustomItems.GetIdByName("Healing Candy");
if (CustomItems.TryGive(candyId, player, out Item item))
{
player.SendHint("You received a Healing Candy!");
}
else
{
Log.Error("Failed to give item to player");
}
Utility Methods
GetRandomPositionInRoom
Finds a random valid position within a specific room for spawning items.
public static Vector3 GetRandomPositionInRoom(Room room)
The room to find a position in
Vector3 - A valid spawn position within the room, or the room center as a fallback.
Example:
var lcz173 = Room.List.FirstOrDefault(r => r.Name == "LCZ_173");
if (lcz173 != null)
{
Vector3 pos = CustomItems.GetRandomPositionInRoom(lcz173);
CustomItems.TrySpawn(itemId, pos, out _);
}
GetRandomPosition
Finds a random valid position in any room on the map.
public static Vector3 GetRandomPosition()
Vector3 - A random valid spawn position on the map.
Example:
Vector3 randomPos = CustomItems.GetRandomPosition();
CustomItems.TrySpawn(itemId, randomPos, out _);
Complete Example
using CustomItems.API;
using LabApi;
using LabApi.Features.Wrappers;
using LabApi.Modules.CustomCommands;
using System.Linq;
public class CustomItemsPlugin : Plugin
{
public override void OnEnabled()
{
// Register all custom items in this assembly
var items = CustomItems.RegisterAll();
Log.Info($"Registered {items.Count} custom items:");
foreach (var item in items)
{
Log.Info($" - {item.Name} (ID: {item.Id})");
}
}
public override void OnDisabled()
{
// Unregister all custom items from this assembly
CustomItems.UnregisterAll();
}
}
[Command("spawnitem", "Spawns a custom item")]
public class SpawnItemCommand : PlayerCommand
{
public override void Execute(Player sender, string[] args)
{
if (args.Length < 1)
{
sender.SendHint("Usage: spawnitem <name>");
return;
}
string itemName = string.Join(" ", args);
try
{
ushort id = CustomItems.GetIdByName(itemName);
Vector3 spawnPos = sender.Position + sender.Transform.forward * 2;
if (CustomItems.TrySpawn(id, spawnPos, out Pickup pickup))
{
sender.SendHint($"Spawned {itemName}!");
}
else
{
sender.SendHint("Failed to spawn item.");
}
}
catch (KeyNotFoundException)
{
sender.SendHint($"Item '{itemName}' not found.");
}
}
}
[Command("giveitem", "Gives a custom item to yourself")]
public class GiveItemCommand : PlayerCommand
{
public override void Execute(Player sender, string[] args)
{
if (args.Length < 1)
{
sender.SendHint("Usage: giveitem <name>");
return;
}
string itemName = string.Join(" ", args);
try
{
ushort id = CustomItems.GetIdByName(itemName);
if (CustomItems.TryGive(id, sender, out Item item, ItemAddReason.AdminCommand))
{
sender.SendHint($"You received {itemName}!");
}
else
{
sender.SendHint("Failed to give item.");
}
}
catch (KeyNotFoundException)
{
sender.SendHint($"Item '{itemName}' not found.");
}
}
}