Hello, this is a modding guide for adding your own Portraits to the mod, as well as explaining a few of our API functions.

To add a portrait for your custom character, you first need to create the following folder in your mod folder:
or the following folder for a tainted character:

Once the folder is created, you will need to add your custom portrait there, and name it using the same name value you used on the players.xml file. For example, if in the xml you name your character "Evan", the portrait file will need to be named "Evan.png" (you need to respect upper/lowercase letters, naming your file "evan.png" will leave the file unused by the mod).

Aside from the character.png file, you will also want to add a file titled "character_text.png" under the same root. This file will be used to display the character's name and stats. If your custom character has an unlock method, you can also add a file titled "character_text_locked.png", which will display a unique text variant when the character is locked in the menu.

The mod also counts with a few API functions for more elaborate characters, I will go over them one by one in this section.

But first, in order to use the API functions, you must first write a block like this:

Otherwise the mod will error if Fancy Character Menu is not enabled.

CCO.FANCY_MENU.addAlias(name, alias)
This function is used whenever your character's internal name contains special characters that cannot be read through the game's file loader. For example, in the mod we use this function to give Blue Baby his own unique portrait.

- name: The name you wrote in the players.xml file,
- alias: The name you want to use on your character.png file.

Example:

CCO.FANCY_MENU.addUniqueAnim(playerType, anm2Root)
This function is used whenever you want to give your character a unique menu animation. For example, in the mod we use this function for multiple characters, such as Azazel, The Forgotten or Tainted Eden. Bear in mind your animation will have to follow the same guidelines as the ones our mod uses, we recommend using Tainted Apollyon's custom anm2 file as a base.

NOTE: You should still add a regular portrait even if your character has a custom animation, as the portrait.png file is the one used for the character switch animations. The unique anims are only used when the character is static, i.e. when the switch animation is finished.

- playerType: The player id you get through Isaac.GetPlayerTypeByName()
- anm2Root: The file path for your custom animation.

Example:

CCO.FANCY_MENU.addPortraitUpgrade(playerType, filename, condition)
This function is used to give the player a new unique portrait when certain conditions are met. At the moment, this function is only used on Isaac, to show a different portrait depending on whether or not the "Isaac now holds the D6" achievement has been unlocked.
It is worth noting that this function can be used multiple times on the same character to add more conditional sprites, we go more in-depth about this in the next section.

- playerType: The player id you get through Isaac.GetPlayerTypeByName()
- filename: The name of the portrait file (just the name, not the full root).
- condition: A function that acts as a check for the mod to know when to use the portrait.

Example:
- gameData is a value we pass into the function for ease of access, the variable is just a hook for Isaac.GetPersistentGameData().

CCO.FANCY_MENU.addTextUpgrade(playerType, filename, condition)
This function is used to give the player a new description when certain conditions are met. The best example of this function being used in our mod is for Keeper, where we use it to give them a different description for every unlockable addon they have (such as Store Key and the extra Penny).
It is worth noting that this function can be used multiple times on the same character to add more conditional descriptions. The mod will pick the last description to return true on its condition, so the order you write the chain in matters! Pay attention to the example to better understand what I mean.

- playerType: The player id you get through Isaac.GetPlayerTypeByName()
- filename: The name of the text file (just the name, not the full root).
- condition: A function that acts as a check for the mod to know when to use the description.

Example:
- gameData is a value we pass into the function for ease of access, the variable is just a hook for Isaac.GetPersistentGameData().

CCO.FANCY_MENU.addUniqueAnimUpgrade(playerType, anm2Root, condition)
This function is used to give the player a new unique animation when certain conditions is met. This function is currently unused by the mod, but is still fully functional.
It is worth noting that this function can be used multiple times on the same character to add more conditional animations. Refer to the previous function for more information.

- playerType: The player id you get through Isaac.GetPlayerTypeByName()
- filename: The root for your custom anm2 file.
- condition: A function that acts as a check for the mod to know when to use the animation.

Example:
- gameData is a value we pass into the function for ease of access, the variable is just a hook for Isaac.GetPersistentGameData().
- NOTE: We recommend adding a portrait upgrade that correlates to the new animation, to avoid the portrait flickering between the default version and the new animation.