Skip to main content
The project's repository is archived as part of the GitHub Archive Program. RogueLibs' code and the documentation will no longer be updated.

Creating a Custom Item

RogueLibs provides classes and methods to create: usable, combinable, targetable (and targetable+) items. All custom items derive from the CustomItem class, which provides all of the basic item functionality. You can derive your custom item's class from specialized interfaces to expand its functionality (IItemUsable, IItemCombinable, IItemTargetable, IItemTargetableAnywhere). Custom items are initialized and integrated into the game using the RogueLibs.CreateCustomItem<TItem>() method.

CustomItem class​

To make a custom item, you need to create a class deriving from CustomItem:

MyCustomItem.cs
public class MyCustomItem : CustomItem
{
    /* ... */
}

There's only one method that you need to implement - SetupDetails:

MyCustomItem.cs
public class MyCustomItem : CustomItem
{
    public override void SetupDetails()
    {
        Item.itemType = ItemTypes.Tool;
        Item.itemValue = 200;
        Item.initCount = 1;
        Item.rewardCount = 1;
        Item.stackable = true;
        Item.hasCharges = true;
    }
}

This method is called only once, when the item is created or spawned. See more info later on this page.

You should add categories using the ItemCategories attribute instead of adding them in SetupDetails:

MyCustomItem.cs
[ItemCategories(RogueCategories.Usable, RogueCategories.Weird, "MyCustomCategory")]
public class MyCustomItem : CustomItem
{
    /* ... */
}
Pro-tip: String consts

Use static types with string consts, like RogueCategories and ItemTypes. This way you won't make a typo. Typos can be critical sometimes, since neither the game nor RogueLibs track all existing item categories (although it's an interesting idea, maybe I'll do something like that).

Initialization​

Just call the CreateCustomItem method with your item's type as a parameter:

MyCustomItem.cs
public class MyCustomItem : CustomItem
{
    [RLSetup]
    public static void Setup()
    {
        RogueLibs.CreateCustomItem<MyCustomItem>();
    }
}
note

See more about the RLSetup attribute here.

You can set your item's name and description using WithName and WithDescription methods:

MyCustomItem.cs
public class MyCustomItem : CustomItem
{
    [RLSetup]
    public static void Setup()
    {
        RogueLibs.CreateCustomItem<MyCustomItem>();
            .WithName(new CustomNameInfo("My Custom Item"))
            .WithDescription(new CustomNameInfo("My Custom Item is very cool and does a lot of great stuff"));
    }
}

You can do the same with sprites and unlocks:

MyCustomItem.cs
public class MyCustomItem : CustomItem
{
    [RLSetup]
    public static void Setup()
    {
        RogueLibs.CreateCustomItem<MyCustomItem>();
            .WithName(new CustomNameInfo("My Custom Item"))
            .WithDescription(new CustomNameInfo("My Custom Item is very cool and does a lot of great stuff"));
            .WithSprite(Properties.Resources.MyCustomItem)
            .WithUnlock(new ItemUnlock { UnlockCost = 10, CharacterCreationCost = 5, LoadoutCost = 4, });
    }
}
info

See Custom Names, Custom Sprites for more info.

Unlock Properties​

You can use the following properties when initializing ItemUnlocks:

PropertyDefaultDescription
UnlockCost0Unlock cost of the item, in nuggets. If set to 0, it will unlock automatically, once all prerequisites are unlocked.
CharacterCreationCost1Cost of the item in Character Creation, in points.
LoadoutCost1Cost of the item in Loadout, in nuggets.
IsAvailabletrueDetermines whether the item is available in the Rewards menu.
IsAvailableInCCtrueDetermines whether the item is available in the Character Creation menu.
IsAvailableInItemTeleportertrueDetermines whether the item is available in Item Teleporter's menu.
PrerequisitesDetermines what unlocks must be unlocked in order to unlock this item.
RecommendationsJust shows these unlocks in a separate Recommendations paragraph in the menus.

Other properties should not be used during initialization.

Implementing SetupDetails​

Alright, while the code generator is being worked on, use the following tables:

Field nameDescription
itemTypeDetermines how the item will work in the game and stuff.
initCountDetermines the initial amount of the item.
rewardCount(optional) Determines the amount of the item that you will get from quests. Defaults to initCount
itemValueDetermines the cost of a single unit of the item. Costs of weapons are calculated differently - cost of a weapon with 100 durability, or cost of a weapon with its maxAmmo.
stackableDetermines whether the item is stackable or has charges or something like that. If not set, the item's count is not displayed.
noCountText(optional) Determines whether the item's count should not be displayed, even if the field above is set to true.
Field nameDescription
healthChangeDetermines how much health the item will restore.
statusEffectDetermines the status effect that the item has. Also means that the item can be used on the Air Conditioner.
contentsJust like statusEffect, but as a list.
stackableContents???
goesInToolbarDetermines whether the item can be set to the toolbar and then be used with 1-5 keys.

Field nameDescription
canRepeatInShopDetermines whether there can be two of these items in a shop.
nonStackableInShopDetermines whether shops should have only 1 item per slot.
cantBeClonedDetermines whether the item shouldn't be cloneable with the Clone Machine.
cantStoreInATMMachineDetermines whether players shouldn't be able to store the item in the ATM.
notInLoadoutMachineDetermines whether the item will not appear in Loadout-O-Matic when selected as a starting item.
destroyAtLevelEndDetermines whether the item will be destroyed on the next level.
cantDropDetermines whether the item cannot be dropped.
doSpillDetermines whether the item should drop from NPCs. Default: true.
cantDropNPCThe opposite of doSpill. You probably should set these at the same time. Default: false.
cantDropSpecificCharacterSet to the agent's name, if it shouldn't be droppable by that agent or by custom characters that have it as a starting item.
characterExclusiveSet this to true, if your item is exclusive to a specific agent and custom characters.
characterExclusiveSpecificCharacterSet this to the agent's name, if it's exclusive to a specific agent and custom characters.

The project's repository is archived as part of the GitHub Archive Program. RogueLibs' code and the documentation will no longer be updated.