A well-documented quirk of how the Binding of Isaac Modding API works is that certain game resources such as spritesheets and animation files are cached and not reloaded upon mods downloading or being enabled/disabled. As such, it is necessary for users to restart the game to update these resources. Unfortunately, Custom Health API relies on the "gfx/ui/ui_hearts.anm2" file in order to properly display it's custom HP types, which is one of the files affected by this quirk of the API.
As such, upon downloading any mod containing the CHAPI library, it is necessary to restart your game to be able to have the proper UI display. It is also necessary to restart your game after enabling/disabling any mods containing the CHAPI library, or else issues will occur. An error message has been added to the mod to communicate this behaviour to players, as shown below:
Certain users have reported experiencing that this error message persists after restarting the game. The following common issues have been identified as possible causes for this issue:
1. A download failure has occurred:
It is well-documented within the Binding of Isaac modding community that mods downloaded off of the Steam Workshop occasionally do not download fully or are added to user's mods folders incomplete. In such cases, it is possible that the "gfx/ui/ui_hearts.anm2" file necessary for Custom Health API to operate is missing. If such a case has occurred, it is recommended that the following steps be taken to correct the issue:
- Identify the mod causing the error.
- Unsubscribe to the mod.
- Launch TBOI and wait for the mod to be uninstalled and the title screen to appear.
- Close TBOI.
- Resubscribe to the mod, and wait for the mod to fully download.
- Launch Isaac and wait for the mod to be fully installed and the title screen to appear. Do not close Isaac during this time, even if it appears frozen.
- Close and restart TBOI.
Mods known to include the Custom Health API system include, but may not be limited to, the following:
- Fiend Folio
- Repentance+
- TeamShuffle Collab
If the issue is indeed caused by a download failure, then the issue should be fixed after these steps are carried out.
2. Another mod is overwriting the "gfx/ui/ui_hearts.anm2" file:
Due to the nature of how CHAPI operates, it is naturally incompatible with other mods that overwrite the "gfx/ui/ui_hearts.anm2" file. In such cases, this issue is only fixable by identifying and disabling the conflicting mods, then restarting the game. Mods known to also overwrite the "gfx/ui/ui_hearts.anm2" file include, but may not be limited to, the following:
- Mantle Rework
- Visible Holy Mantles
- Visible Lost Health
If you find another mod that also is incompatible with Custom Health API due to this issue, please report so here. We will do our best to reach out to any mods incompatible with CHAPI and get them to work together in the future.