Registering your Fire - Crystal-Nest/soul-fire-d GitHub Wiki

To make the API aware of your custom fire you need to register it.
It's very important to register your fire inside your mod constructor.
Let's break down in small steps how registering is done:

1. Creating a Fire:
   A Fire instance is nothing more than a representation of your fire within the API. You need to register one to make the API aware of your fire and handle its behaviors.
2. Getting a FireBuilder:
   To create a Fire instance you need a FireBuilder.
   To get one simply call FireManager#fireBuilder() and pass your Fire Type (either a ResourceLocation/Identifier or your Mod Id and Fire Id).
3. Tweaking the Fire:
   The Fire about to be built will be constructed using the Fire Type provided to the FireBuilder during initialization or reset.
   However you may want to change some other properties from their default value, for example the damage. More on this below.
4. Building the Fire:
   It's as simple as calling FireBuilder#build().
5. Registering the Fire:
   Once you have built your Fire instance, pass it as parameter to FireManager#registerFire(Fire).

For example, here's how Soul Fire is registered using the API:

// Inside Soul Fire'd mod class
FireManager.registerFire(
  FireManager.fireBuilder(FireManager.SOUL_FIRE_TYPE)
    .setDamage(2)
    .setFireAspectConfig(builder -> builder.setEnabled(SoulFiredConfig::getEnableSoulFireAspect))
    .setFlameConfig(builder -> builder.setEnabled(SoulFiredConfig::getEnableSoulFlame))
  .build()
);

It's also possible, and suggested, to save and reuse a single FireBuilder instance if you have to register multiple fires. FireBuilder#reset() can be used to reset each value to its default. If you use the FireBuilder#reset(String) overload the Mod Id will not be reset.
Trying to register multiple Fires with the same Fire Id won't throw, but only the first Fire will be registered and an error will be logged for the other ones.

The damage value can even be negative, in which case it will heal instead of hurting. More on this below.

Here's a description of each FireBuilder method, one by one with detailed explanation and also a description of the related Fire property:

• setDamage(float)
  Related property: Fire#damage, fire damage per second.
  Sets the damage, defaults to 1.0F.
  The damage can be either positive or negative. If negative the Fire will harm, if positive it will heal.
  What just said can change when applied to undead mobs such as zombies and skeleton as explained below.
• setInvertHealAndHarm(boolean)
  Related property: Fire#invertHealAndHarm, whether to invert harm and heal for mobs that have potion effects inverted (e.g. undeads).
  Sets the flag for inverting heal and harm for undeads, defaults to false.
  Determines whether to invert heal and harm for undeads: if when false it harms all entities the same, when true it will harm normal entities and heal undeads like zombies and skeletons. Vice versa if when false it heals, when true it will heal normal entities but harm undeads.
• setInFire()
  Related property: Fire#inFire, DamageSource for when an entity is in or on a block providing fire.
  Sets the inFire DamageSource, defaults to normal fire IN_FIRE DamageSource.
  Creates a new DamageSource with the message id equal to "in_mod_id_fire_id_fire", where mod_id is the Mod Id and fire_id is the Fire Id.
• setOnFire()
  Related property: Fire#onFire, DamageSource for when the entity is burning.
  Sets the onFire DamageSource, defaults to normal fire ON_FIRE DamageSource.
  Creates a new DamageSource with the message id equal to "on_mod_id_fire_id_fire", where mod_id is the Mod Id and fire_id is the Fire Id.
• setHurtSound(SoundEvent)
  Related property: Fire#hurtSound, sound to use when the player is taking fire damage.
  Sets the hurt sound to play when a player is taking damage from the Fire, defaults to the hurt sound of normal fire.
• setSource(ResourceLocation)
  Related property: Fire#source, fire block considered as the source for the Fire.
  Sets the ResourceLocation/Identifier for the fire block source, defaults to "mod_id:fire_id_fire", where mod_id and fire_id are the Mod Id and Fire Id.
  This is used to make sure that the source block will set entities on the correct kind of fire.
  The default value is recommended unless you're registering another mod fire.
• removeSource()
  Related property: Fire#source, fire block considered as the source for the Fire.
  Removes the association with the source block. To be used if your fire shouldn't have any source block associated.
• setCampfire(ResourceLocation)
  Related property: Fire#campfire, campfire associated with the Fire.
  Sets the ResourceLocation/Identifier for the associated campfire, defaults to "mod_id:fire_id_campfire", where mod_id and fire_id are the Mod Id and Fire Id.
  This is used to make sure that the campfire will damage entities referring to the correct kind of fire.
  The default value is recommended unless you're registering another mod fire.
• removeCampfire()
  Related property: Fire#campfire, campfire associated with the Fire.
  Removes the association with the campfire. To be used if your fire shouldn't have any campfire associated.
• setFireAspectConfig(Function<FireAspectBuilder, FireAspectBuilder>)
  Related property: Fire#fireAspect, FireTypedFireAspectEnchantment (fire aspect) for the fire
  Sets the Fire Aspect enchantment configuration to use to build the enchantment, defaults to the default configuration.
  See Tweaking enchantments for details on how to tweak the enchantment configuration.
• removeFireAspect()
  Related property: Fire#fireAspect, FireTypedFireAspectEnchantment (fire aspect) for the fire
  Prevents the generation of the Fire Aspect enchantment for the fire, to be used if you never want the enchantment to exist.
  If you wish instead to make the enchantment available depending on your mod configuration, see Tweaking enchantments.
• setFlameConfig(Function<FlameBuilder, FlameBuilder>)
  Related property: Fire#flame, FireTypedFlameEnchantment (flame) for the fire
  Sets the Flame enchantment configuration to use to build the enchantment, defaults to the default configuration.
  See Tweaking enchantments for details on how to tweak the enchantment configuration.
• removeFlame()
  Related property: Fire#flame, FireTypedFlameEnchantment (flame) for the fire
  Prevents the generation of the Flame enchantment for the fire, to be used if you never want the enchantment to exist.
  If you wish instead to make the enchantment available depending on your mod configuration, see Tweaking enchantments.
• reset(ResourceLocation) / reset(String, String) / reset(String)
  Resets all values cached in the FireBuilder to their default.
  The reset(String) overload will not reset the Mod Id, useful if you need to register multiple fires of the same mod.
• build()
  Returns a new Fire instance.

Once registering is done, everything is set for the Fire to work properly.
This means you can also register another mod's fire and it will work!
However you need to make sure the Setup is thoroughly followed, possibly adding the missing translations for enchantments or a texture pack to setup the fire sprites correctly.

Each registered Fire comes by default with its own Fire Aspect and Flame enchantments, each with its own configuration.
To remove altogether an enchantment, just call its remove method when building your Fire.
To instead tweak the configuration of an enchantment you need to call its set config method when building your Fire and using the provided FireEnchantmentBuilder instance to change what you'd like to change. For example, when registering Soul Fire I do:

.setFireAspectConfig(builder -> builder.setEnabled(SoulFiredConfig::getEnableSoulFireAspect))
.setFlameConfig(builder -> builder.setEnabled(SoulFiredConfig::getEnableSoulFlame))

This way whether the enchantments are enabled depends on the value read from the mod configuration. Another example may be calling FireEnchantmentBuilder#setRarity(Rarity) to change the rarity of the enchantment.
Each FireEnchantmentBuilder method has an overload that instead of taking directly the value, it takes a Supplier of that value, this to allow a dynamic configuration for enchantments.
The only exceptions to this are FireEnchantmentBuilder#setEnabled(Supplier<Boolean>), FireEnchantmentBuilder#setCompatibility(Function<Enchantment, Boolean>) and FireEnchantmentBuilder#setRarity(Rarity) that only have the mentioned signatures.
Since version 3.2.1.0, it is possible to tweak the applied flame duration too by setting the duration property when building the enchantment. Like most other properties, it can either take a supplier (actually a TriFunction giving access to the attacker, target, and default duration) or a raw value. It defaults to Vanilla Fire Aspect and Flame durations.
If you need the enchantment level when calculating the duration for a Fire Aspect, you can just divide by 4 the default duration.

For Server side compatibility there's a part of the API that's only for the Client side. As such it must never be used Server side and if you really need to use it you need to check your current environment to avoid crashes.
For example a strategy could be to isolate your Client sided code in a package and use a static class of that package as an intermediary.
This way you can safely check your environment and then, only if Client side, call your static methods.
The Client sided API contains just the part responsible for handling the Fire sprites.
FireClientManager contains a copy of the list of registered Fires, with the difference being that all Fires in here are FireClients and just have references to the Mod Id, Fire Id and the sprites.
It is possible to get any Fire sprite using the apposite methods in FireClientManager.