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:
/MyAwesomeProject/MyAwesomeItem.cs
public class MyAwesomeItem : CustomItem{ /* ... */}There's only one method that you need to implement - SetupDetails:
/MyAwesomeProject/MyAwesomeItem.cs
public class MyAwesomeItem : 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:
/MyAwesomeProject/MyAwesomeItem.cs
[ItemCategories(RogueCategories.Usable, RogueCategories.Weird, "MyAwesomeCategory")]public class MyAwesomeItem : 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.
Initialization
Just call the CreateCustomItem method with your item's type as a parameter:
/MyAwesomeProject/MyAwesomeItem.cs
public class MyAwesomeItem : CustomItem{ [RLSetup] public static void Setup() { RogueLibs.CreateCustomItem<MyAwesomeItem>(); }}note
See more about the RLSetup attribute here.
You can set your item's name and description using WithName and WithDescription methods:
/MyAwesomeProject/MyAwesomeItem.cs
public class MyAwesomeItem : CustomItem{ [RLSetup] public static void Setup() { RogueLibs.CreateCustomItem<MyAwesomeItem>() .WithName(new CustomNameInfo("My Awesome Item")) .WithDescription(new CustomNameInfo("My Awesome Item is very cool and does a lot of great stuff, and it's also awesome.")); }}You can do the same with sprites and unlocks:
/MyAwesomeProject/MyAwesomeItem.cs
public class MyAwesomeItem : CustomItem{ [RLSetup] public static void Setup() { RogueLibs.CreateCustomItem<MyAwesomeItem>() .WithName(new CustomNameInfo("My Awesome Item")) .WithDescription(new CustomNameInfo("My Awesome Item is very cool and does a lot of great stuff, and it's also awesome.")) .WithSprite(Properties.Resources.MyAwesomeItem) .WithUnlock(new ItemUnlock { UnlockCost = 10, CharacterCreationCost = 5, LoadoutCost = 4 }); }}info
See Custom Names, Custom Sprites, Custom Unlocks for more info.
Unlock Properties
You can use the following properties when initializing ItemUnlocks:
| Property | Default | Description |
|---|---|---|
UnlockCost | 0 | Unlock cost of the item, in nuggets. If set to 0, it will unlock automatically, once all prerequisites are unlocked. |
CharacterCreationCost | 1 | Cost of the item in Character Creation, in points. |
LoadoutCost | 1 | Cost of the item in Loadout, in nuggets. |
IsAvailable | true | Determines whether the item is available in the Rewards menu. |
IsAvailableInCC | true | Determines whether the item is available in the Character Creation menu. |
IsAvailableInItemTeleporter | true | Determines whether the item is available in Item Teleporter's menu. |
Prerequisites | Determines what unlocks must be unlocked in order to unlock this item. | |
Recommendations | Just 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 name | Description |
|---|---|
itemType | Determines how the item will work in the game and stuff. |
initCount | Determines the initial amount of the item. |
rewardCount | (optional) Determines the amount of the item that you will get from quests. Defaults to initCount |
itemValue | Determines 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. |
stackable | Determines 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. |
- Food/Consumable
- Tool
- Wearable
- Weapon
- Quest Item
| Field name | Description |
|---|---|
healthChange | Determines how much health the item will restore. |
statusEffect | Determines the status effect that the item has. Also means that the item can be used on the Air Conditioner. |
contents | Just like statusEffect, but as a list. |
stackableContents | ??? |
goesInToolbar | Determines whether the item can be set to the toolbar and then be used with 1-5 keys. |
| Field name | Description |
|---|---|
goesInToolbar | Determines whether the item can be set to the toolbar and then be used with 1-5 keys. |
hasCharges | Determines whether the item has charges. It means that the item cannot be splitted in multiplayer. |
canBeUsedOn_____ | Determines whether the item can be used on these objects. |
| Field name | Description |
|---|---|
armorDepletionType | Determines how the item's durability will decrease. "MeleeAttack" (when attacking, not being attacked), "Bullet", "Everything" or "FireAndEverything". |
chanceToWear | Determines the chance of the armor being worn by NPCs, in percents. Default is 100. |
canFix | Determines whether the armor can be fixed. It won't be destroyed when its durability reaches 0. |
_____Mod | Determines how wearer's stats will change, when worn. Only works with positive values. |
contents | Determines the list of effects that the wearer will get, when worn. |
stackableContents | ??? |
- Body
- Head
| Field name | Description |
|---|---|
isArmor | If your item is a body armor, set this to true. |
| Field name | Description |
|---|---|
isArmorHead | If your item is a head gear, set this to true. |
behindHair | Puts the worn item behind hair. |
cantShowHair | Cuts off the upper half of the wearer's hair. |
cantShowHairAtAll | Doesn't show hair at all. |
permanentHeadpiece | ??? |
| Field name | Description |
|---|---|
isWeapon | If your item is a weapon, set this to true. |
weaponCode | Set this to your weapon type's code. |
weaponToBeLoaded | Determines whether initially the item is not loaded, and has to be loaded/charged (like Water Pistol). |
- Melee weapon
- Thrown weapon
- Projectile weapon
| Field name | Description |
|---|---|
meleeDamage | Set this to your weapon's damage. |
nonLethal | If it doesn't do damage, like Sticky Glove or Chloroform, set this to true. |
meleeNoHit | Set to true, if your weapon doesn't actually hit and knock back NPCs. |
hitSoundType | Sound used when you hit something with the weapon. "Normal" or "Cut". |
specialMeleeTexture | Determines whether to use special sprites when held(?). |
| Field name | Description |
|---|---|
throwDistance | Maximum distance that the item can be thrown at. |
throwExtraDist | Determines whether the item should be thrown a little bit further than aimed at. Set this to true, if your item is a regular thrown weapon. Set this to false, if it's a trap, so it stays exactly in the position that you want to throw it in. |
- Thrown
- Trap
| Field name | Description |
|---|---|
throwDamage | Set this to your weapon's damage. |
| Field name | Description |
|---|---|
touchDamage | Set this if your trap activates on touch. |
incendiaryDamage | Set this if your trap activates when exploded. |
otherDamage | Set this, if your trap deals some kind of non-touch non-explosion damage. |
reactOnTouch | Set this if your trap activates when hit by something, anything at all. |
dontFlash | Set to true if you don't want the trap to flash red once placed. |
| Field name | Description |
|---|---|
maxAmmo | Determines the weapon's max ammo. Defaults to initCount. |
initCountAI | Determines how much of the item NPCs will get. Defaults to 1. |
doesNoDamage | If it doesn't do damage, like Research Gun or Leaf Blower, set this to true. |
gunKnockback | Determines the shooter's knockback. Machine Gun (15), Revolver (30), Rocket Launcher/Shotgun (60). |
rapidFire | Determines whether the left mouse button can be held to fire the weapon. |
longerRapidFire | Determines if NPCs should shoot for about 1-2 seconds instead of just shooting a few projectiles. |
shortRangeProjectile | Determines whether NPCs should come closer to the opponent to use the weapon. |
noRefills | Set this to true if you don't want your item to be refillable in the Ammo Dispenser. |
| Field name | Description |
|---|---|
questItem | Set this to true if it's a quest item. |
questItemCanBuy | Set this to true if it can be bought. |
- Limitations
- Graphics
- Other
- AI and Automation
| Field name | Description |
|---|---|
canRepeatInShop | Determines whether there can be two of these items in a shop. |
nonStackableInShop | Determines whether shops should have only 1 item per slot. |
cantBeCloned | Determines whether the item shouldn't be cloneable with the Clone Machine. |
cantStoreInATMMachine | Determines whether players shouldn't be able to store the item in the ATM. |
notInLoadoutMachine | Determines whether the item will not appear in Loadout-O-Matic when selected as a starting item. |
destroyAtLevelEnd | Determines whether the item will be destroyed on the next level. |
cantDrop | Determines whether the item cannot be dropped. |
doSpill | Determines whether the item should drop from NPCs. Default: true. |
cantDropNPC | The opposite of doSpill. You probably should set these at the same time. Default: false. |
cantDropSpecificCharacter | Set 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. |
characterExclusive | Set this to true, if your item is exclusive to a specific agent and custom characters. |
characterExclusiveSpecificCharacter | Set this to the agent's name, if it's exclusive to a specific agent and custom characters. |
| Field name | Description |
|---|---|
noCountText | Determines whether the item's count should not be displayed in the inventory. |
noShadow | Determines whether the item shouldn't have a shadow. |
shadowOffset | Determines the location of the shadow. It's pretty complicated, so I'll make a preview for that in the code generator. |
lowCountThreshold | Determines below what count the text becomes red. Default: 0 - it doesn't become red. |
| Field name | Description |
|---|---|
colliderSize | Determines the size of the collider. null for default, or "Big" for a larger collider. |
canCatchFire | Determines whether the item can catch fire. In the game it's used only on Factory Meat. |
| Field name | Description |
|---|---|
dontAutomaticallySelect | Determines whether a weapon or armor should not be equipped automatically. |
dontSelectNPC | The same thing but for NPCs. |
canHaveStartingOwner | Determines whether the item can have a starting owner. Defaults to true. |
thiefCantSteal | Determines whether Thiefs should not be able steal this item. Usually because you don't want Thiefs to use the stolen item against the player. |