Damage Types 1.21.11

Learn how to add custom damage types.

WARNING

This page is written for version 1.21.11. Documentation for older versions may be incomplete.

Damage types define types of damage that entities can take. Since Minecraft 1.19.4, the creation of new damage types has become data-driven, meaning they are created using JSON files.

Creating a Damage Type

Let's create a custom damage type called Tater. We start by creating a JSON file for your custom damage. This file will be placed in your mod's data directory, in a subdirectory named damage_type.

resources/data/example-mod/damage_type/tater.json

It has the following structure:

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

This custom damage type causes 0.1 increase in hunger exhaustion each time a player takes damage, when the damage is caused by a living, non-player source (e.g., a block). Additionally, the amount of damage dealt will scale with the world's difficulty

INFO

Refer to the Minecraft Wiki for all the possible keys and values.

Accessing Damage Types Through Code

When we need to access our custom damage type through code, we will use it's ResourceKey to build an instance of DamageSource.

The ResourceKey can be obtained as follows:

public static final ResourceKey<DamageType> TATER_DAMAGE = ResourceKey.create(Registries.DAMAGE_TYPE, Identifier.fromNamespaceAndPath(ExampleMod.MOD_ID, "tater"));

Using Damage Types

To demonstrate the use of custom damage types, we will use a custom block called Tater Block. Let's make is so that when a living entity steps on a Tater Block, it deals Tater damage.

You can override stepOn to inflict this damage.

We start by creating a DamageSource of our custom damage type.

DamageSource damageSource = new DamageSource(
		level.registryAccess()
				.lookupOrThrow(Registries.DAMAGE_TYPE)
				.get(ExampleModDamageTypes.TATER_DAMAGE.identifier()).get()
);

Then, we call entity.damage() with our DamageSource and an amount.

entity.hurtServer(serverLevel, damageSource, 5.0f);

The complete block implementation:

public class TaterBlock extends Block {
	public TaterBlock(Properties settings) {
		super(settings);
	}

	@Override
	public void stepOn(Level level, BlockPos pos, BlockState state, Entity entity) {
		if (entity instanceof LivingEntity && level instanceof ServerLevel serverLevel) {
			DamageSource damageSource = new DamageSource(
					level.registryAccess()
							.lookupOrThrow(Registries.DAMAGE_TYPE)
							.get(ExampleModDamageTypes.TATER_DAMAGE.identifier()).get()
			);
			entity.hurtServer(serverLevel, damageSource, 5.0f);
		}
	}
}

Now whenever a living entity steps on our custom block, it'll take 5 damage (2.5 hearts) using our custom damage type.

Custom Death Message

You can define a death message for the damage type in the format of death.attack.message_id in our mod's en_us.json file.

{
  "death.attack.tater": "%1$s died from Tater damage!"
}

Upon death from our damage type, you'll see the following death message:

Damage Type Tags

Some damage types can bypass armor, bypass mob effects, and such. Tags are used to control these kinds of properties of damage types.

You can find existing damage type tags in data/minecraft/tags/damage_type.

INFO

Refer to the Minecraft Wiki for a comprehensive list of damage type tags.

Let's add our Tater damage type to the bypasses_armor damage type tag.

To add our damage type to one of these tags, we create a JSON file under the minecraft namespace.

data/minecraft/tags/damage_type/bypasses_armor.json

With the following content:

{
  "values": [
    "example-mod:tater"
  ]
}

Ensure your tag does not replace the existing tag by setting the replace key to false.