Sometimes you may want to add a custom damage type to your mod, for example if you're adding a custom damaging fluid similar to lava or a block like a magma block. Since 1.19.4, the creation of new damage types has become data-driven, meaning they are created using JSON files. To use your custom damage type in code however, you're going to need to get its RegistryKey and create a new DamageSource using it. In this tutorial, the “tutorial” namespace is used as a placeholder. If you have a separate modid, feel free to use it instead.

First, create a json file for your custom damage type following the format here. It should be placed in your mod's data folder in a new subfolder called damage_type. For example:

data/tutorial/damage_type/custom_damage_type.json

{
  "exhaustion": 0.1,
  "message_id": "custom",
  "scaling": "when_caused_by_living_non_player"
}

Our new custom damage type will now cause 0.1 hunger exhaustion each time a player takes damage of this type, and the if the damage is caused by a living, non-player source (like being hit by a Zombie), the amount of damage dealt will scale with the world's difficulty. You can see all possible keys and values on the respective Minecraft wiki page.

To actually use our new damage type in code, we need to get its RegistryKey and use a method to get the corresponding DamageSource object. Let's create a new class to keep track of our custom damage types and store our helper method.

ModDamageTypes.java

public class ModDamageTypes {
 
    /* 
     * Store the RegistryKey of our DamageType into a new constant called CUSTOM_DAMAGE_TYPE
     * The Identifier in use here points to our JSON file we created earlier.
    */
    public static final RegistryKey<DamageType> CUSTOM_DAMAGE_TYPE = RegistryKey.of(RegistryKeys.DAMAGE_TYPE, new Identifier("tutorial", "custom_damage_type"));
 
    public static DamageSource of(World world, RegistryKey<DamageType> key) {
        return new DamageSource(world.getRegistryManager().get(RegistryKeys.DAMAGE_TYPE).entryOf(key));
    }
}

Our static method of allows us to get the DamageSource we need to actually use our custom damage type in code, as any methods that deal damage will typically take a DamageSource and not a DamageType.

Now let's use our custom damage type. In this example, lets pretend we have a custom Block that implements the onSteppedOn method, similar to the Magma Block. If you haven't created a Block yet, check out the blocks tutorial.

ExampleBlock.java

public class ExampleBlock extends Block {
 
    public ExampleBlock (Settings settings) {
        super(settings);
    }
 
    public void onSteppedOn(World world, BlockPos pos, BlockState state, Entity entity) {
        if(entity instanceof LivingEntity) {
            entity.damage(ModDamageTypes.of(world, ModDamageTypes.CUSTOM_DAMAGE_TYPE), 1.0f);
        }
    }
}

Now whenever a ``LivingEntity`` steps on our custom block, they'll take 1 damage (half a heart) using our custom damage type! However, if you notice, when you die from our custom damage type, the death message will simply be “death.attack.custom”! That's no good. We need to provide a translation for when something dies of our custom damage type! Add an entry to your language file:

en_us.lang

{
    [...]
    "death.attack.custom": "%1$s died from a custom damage type!"
    [...]

If you did everything correctly, when you die of our custom damage type, you'll see a proper death message with your username!

Some types of damage in Minecraft bypass armor, like the Wither potion effect, or drowning damage. If you want to make your custom damage type have effects like bypassing armor or not damaging witches, there are tags for this! You can find a list of Minecraft's damage type tags in data/minecraft/tags/damage_type. To add your custom damage type to one of these tags, create a new json file with the same name in your data/<namespace>/tags/damage_type folder. Note that this file should go in the minecraft namespace, NOT your mod's namespace! Now simply ensure your tag file does not replace the existing tag by adding the replace key, and add your custom damage type into it:

data/minecraft/tags/damage_type/bypasses_armor.json

{
    "replace": false,
    "values": [
        "examplemod:custom_damage_type"
    ]
}

A list of the tags and their effects is as follows: