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 LabAPI provides configuration options to control plugin behavior and debugging features.
Configuration file
The configuration is stored in config.yml in your plugin’s configuration directory. The file is automatically created when the plugin first loads.
Available options
Debug
Enables debug logging for CustomItems LabAPI.
Type: bool
Default: false
When enabled:
- Logs item registration and unregistration
- Logs spawning and giving operations with serial numbers
- Logs custom item events (usage, pickup, drop, etc.)
- Shows detailed information about item interactions
Example debug output:
[DEBUG] Registered item 'EMP Grenade' with ID 0 and type GrenadeHE.
[DEBUG] Spawned item 'EMP Grenade' (0) at (10.5, 2.0, 15.3) with serial 1234.
[DEBUG] EMP Grenade exploded at (10.5, 2.0, 15.3) in room LCZ_Crossing.
if (CustomItemsPlugin.Instance.Config.Debug)
{
Log.Debug("Custom debug message");
}
TestItemSpawning
Spawns a test item in every room at round start for debugging purposes.
Type: bool
Default: false
DO NOT ENABLE IN PRODUCTION! This is purely for debugging and will spawn items in every single room, which can cause performance issues and gameplay disruption.
- Spawns a test item in every non-destroyed room
- Uses
GetRandomPositionInRoom() for each spawn
- Runs automatically at round start
- Useful for testing item appearance and spawn mechanics
Use cases:
- Testing item models and appearances
- Verifying spawn position algorithms
- Debugging item visibility and hints
- Checking item physics and collisions
EnableExampleItems
Registers the example items included with CustomItems LabAPI.
Type: bool
Default: true
When enabled:
- Automatically registers all example items from
CustomItems.API.Example namespace
- Items are registered using
CustomItems.RegisterAll() during plugin enable
- Items are unregistered during plugin disable
Example items included:
- EMP Grenade - Locks doors and flickers lights in the room where it explodes
- Healing Syringe - Applies gradual healing over time when used
When to disable:
- When you want to use only your custom items
- In production servers where example items aren’t needed
- When testing your own items without interference
Complete configuration example
# Enable debug logging
Debug: true
# DO NOT enable in production - spawns test items in every room
TestItemSpawning: false
# Register example items (EMP Grenade, Healing Syringe)
EnableExampleItems: true
Loading configuration in your plugin
If you’re creating a plugin that uses CustomItems LabAPI, you can access the configuration:
using CustomItems;
public class MyPlugin : Plugin
{
public override void Enable()
{
// Access CustomItems configuration
bool debugEnabled = CustomItemsPlugin.Instance.Config.Debug;
if (debugEnabled)
{
Log.Debug("CustomItems debug mode is enabled");
}
// Check if example items are enabled
if (CustomItemsPlugin.Instance.Config.EnableExampleItems)
{
Log.Info("Example items are available");
}
}
}
Creating custom configuration
For your own plugin using CustomItems LabAPI, you can create a custom configuration class:
using System.ComponentModel;
using LabApi.Loader.Features.Plugins;
public class MyItemsConfig
{
[Description("Enable custom item spawning")]
public bool EnableSpawning { get; set; } = true;
[Description("Number of items to spawn per round")]
public int SpawnCount { get; set; } = 5;
[Description("List of rooms where items can spawn")]
public List<string> AllowedRooms { get; set; } = new()
{
"LCZ_ClassDSpawn",
"HCZ_Armory",
"EZ_Intercom"
};
}
public class MyPlugin : Plugin
{
public MyItemsConfig Config { get; private set; }
public override void LoadConfigs()
{
base.LoadConfigs();
if (!this.TryLoadConfig("my_items_config.yml", out Config))
{
Log.Error("Failed to load configuration!");
}
}
public override void Enable()
{
if (Config.EnableSpawning)
{
Log.Info($"Will spawn {Config.SpawnCount} items per round");
}
}
}
Configuration best practices
Use descriptive names
public class CustomItemsConfig
{
[Description("Enable debug logging for item operations")]
public bool Debug { get; set; } = false;
[Description("Maximum number of custom items a player can hold")]
public int MaxItemsPerPlayer { get; set; } = 3;
}
Provide sensible defaults
// Good: Safe default that won't break gameplay
public bool EnableSpawning { get; set; } = false;
// Bad: Dangerous default that could cause issues
public bool SpawnInEveryRoom { get; set; } = true;
Add descriptions for clarity
[Description("PURELY FOR DEBUGGING! DO NOT ENABLE IN PRODUCTION!")]
public bool TestItemSpawning { get; set; } = false;
Validate configuration values
public override void LoadConfigs()
{
base.LoadConfigs();
if (!this.TryLoadConfig("config.yml", out Config))
{
Log.Error("Invalid configuration!");
Config = new MyItemsConfig(); // Use defaults
}
// Validate ranges
if (Config.SpawnCount < 0)
{
Log.Warn("SpawnCount cannot be negative, using 0");
Config.SpawnCount = 0;
}
if (Config.SpawnCount > 100)
{
Log.Warn("SpawnCount too high, capping at 100");
Config.SpawnCount = 100;
}
}
Troubleshooting
Configuration not loading
If your configuration isn’t loading:
- Check that
LoadConfigs() is being called before Enable()
- Verify the YAML syntax is correct
- Enable debug mode to see detailed loading information
- Check file permissions on the config directory
Invalid configuration values
public override void LoadConfigs()
{
base.LoadConfigs();
if (!this.TryLoadConfig("config.yml", out Config))
{
Log.Error("Failed to load config - using defaults");
Config = new CustomItemsConfig();
_hasIncorrectSettings = true;
}
}
public override void Enable()
{
if (_hasIncorrectSettings)
{
Log.Warn("Plugin running with default configuration due to errors");
}
}
Debug mode not working
Ensure you’re using the Log.Debug() method and that debug mode is enabled:
if (CustomItemsPlugin.Instance.Config.Debug)
{
Log.Debug("This message will only appear when Debug is true");
}
// Or use directly (will respect global debug settings)
Log.Debug("Debug message");