9) Items and Potions

Items and Potions

These two are a special case - each in-game potion is also an item, for the purposes of inventory and unlocks. In fact, every potion will function perfectly well when forced into the item slot due to some leftover code from before potion bar was a thing.

Because of that, both are treated as one kind of an item in FP2Lib - if you are adding a potion, you would have to define every item-related field anyway. A potion really is just an item with extra steps.

Still, ItemHandler is here to make adding both of them easier. It remains up to you to actually implement the effect itself however.

Usage

An Item (or Potion) can be registered by calling following method on FP2Lib.Item.ItemHandler

If you wish to register an item, you might call:

RegisterItem(string uid, string name, Sprite inventorySprite, string description, IAddToShop shop, int starCards, int goldGemsPrice, float gemsBonus)

Registering a potion can be done with:

RegisterPotion(string uid, string name, Sprite inventorySprite, Sprite spriteBottleBottom, Sprite spriteBottleMid, Sprite spriteBottleTop,
            string description, string effectDescription, PAddToShop shop, int starCards, int goldGemsPrice, float effectPercent)

Due to the amount of the parameters, you might wish to pre-make the ItemData object yourself, and register it with:

RegisterItemDirect(ItemData item)

This method works for both items and potions.

Return values indicate if the process was successful. Returns true on success. Value of false might imply an item with this uid was already initialised.

Field Explanation

        /// Unique identifier of the item
        public string uid;

        /// Name of the item
        public string name;

        /// Generic description of the item.
        /// Used when others are not set, and for custom characters.
        public string descriptionGeneric;

        /// Description of the item when playing as Lilac.
        /// Leave empty to use default description.
        public string descriptionLilac;

        /// Description of the item when playing as Carol.
        /// Leave empty to use default description.
        public string descriptionCarol;

        /// Description of the item when playing as Milla.
        /// Leave empty to use default description.
        public string descriptionMilla;

        /// Description of the item when playing as Neera.
        /// Leave empty to use default description.
        public string descriptionNeera;

        /// Description of the item when playing as a custom character.
        /// Key is the character UID, value is the description.
        public Dictionary<string,string> descriptionCustom = [];


        /// Sprite shown in inventory, item list, and equipment slots.
        internal Sprite sprite;

        /// How many star cards are needed to unlock the item.
        public int starCards;

        /// Price of the item in Gold Gems.
        public int goldGemsPrice;

        /// Gem Bonus granted at the end of the stage.
        /// By default does nothing for potions, unless you let the player equip it as an item.
        public float gemBonus = 0f;

        /// Which shop should the *item* appear in
        /// Defaults to "None".
        public IAddToShop itemShopLocation


        /// Set for items which exist as equivalent to a registered potion.
        /// This enables the following fields and makes it not count as an item for item shops.
        public bool isPotion = false;

        /// The effect amount per one potion slot taken. Can be full number, can be float, whatever fits the text below.
        /// This value is thrown into equation of "Potion slots filled x Effect Percentage". 
        /// Defaults to 0.
        public float effectPercentage = 0f;

        /// The text following the calculated effect percentage
        /// Doesn't really need to be a percentage. Can be anything. 5 more gems per gem. 0.25% each frame for Foxy jumpscare.
        /// Defaults to text below so the player knows you goofed up.
        public string effect = " of nothing. The mod is not installed, silly!";

        /// Sprite for the middle slots in the bottle preview.
        public Sprite spriteBottleMid = null;

        /// Sprite for the top (last) slot in the bottle.
        public Sprite spriteBottleTop = null;

        /// Sprite for the bottom (first) slot in the bottle.
        public Sprite spriteBottleBottom = null;

        /// Which shop should the *potion* appear in
        /// Defaults to none. Has no effect for items.
        public PAddToShop potionShopLocation = PAddToShop.None;

Selecting any of the NPC merchants will also automatically assume you want the item to be present in classic mode shop (as they are not accessible there).

Other Methods

If you need to access the Item after it has been registered (maybe you want the already loaded Sprites, or maybe to edit it for your custom character) you can obtain a reference to the data object storing it using:

ItemData GetItemDataByUid(string uid)

Be aware that if you request an item which does not exist, this method will return Null.

Because of internal workings of FP2, each Potion has 2 distinct ID numbers - one belonging to it's item part (used in player inventory, loading sprites) as well as it's own potion ID (used for the potion bar and some other parts of the code). Items which are not potions, have potion ID of -1.

You can locate items and potions by both their IDs using:

ItemData GetItemDataByRuntimeItemID(int id)
ItemData GetItemDataByRuntimePotionID(int id)

To ensure your mod doesn't load without the lib (and therefore explode horribly) you can add a Bepinex dependency:

[BepInDependency("000.kuborro.libraries.fp2.fp2lib")]

Compatibility

Best effort was made to not break Potion Seller but that mod makes few assumptions where it's the only one modifying some structures. Some patches handling adding items will therefore wait for Potion Seller to hook in first.

Because of that, item IDs start at 100 and every non-taken ID below that belongs to that mod. Since that creates gap between ID 45 and 80, if you don't want to use FP2Lib's item features these 35 IDs are free for the taking :3