Statistics 26.1.2

Learn how to create and use custom player statistics.

Statistics (or Stats) are a way to keep track of certain actions or time that the player spends in the world. Vanilla tracks statistics for common actions like jumping, traveling in boats, interactions with blocks, usage of items and much more. It's also possible to add your own statistic to track some custom interaction.

Creating a Statistic

To add a custom statistic, create an Identifier which will be used to register and increase the stat:

public static final Identifier FRIENDSHIPS_MADE = register("friendships_made", StatFormatter.DEFAULT);

Then register the statistic:

public class ModStats {
	public static final Identifier FRIENDSHIPS_MADE = register("friendships_made", StatFormatter.DEFAULT);

	private static Identifier register(String name, StatFormatter formatter) {
		Identifier id = Identifier.fromNamespaceAndPath(ExampleMod.MOD_ID, name);
		Registry.register(BuiltInRegistries.CUSTOM_STAT, name, id);
		Stats.CUSTOM.get(id, formatter);
		return id;
	}
}

When adding the stat to the Statistics screen via Stats.CUSTOM.get(), you can also specify the stat formatter, which determines how the number is displayed in the stat list. Vanilla provides the following formatters:

• DEFAULT: Displays the number directly.
• DIVIDE_BY_TEN: Displays the number as a decimal, divided by ten.
• DISTANCE: Displays the number as distance: Depending on the size of the number, this will be shown in centimeters, meters, or kilometers.
• TIME: Displays the number as time. Depending on the size of the number, this will be shown in seconds, minutes, hours, or days.

Don't forget to initialize the ModStats class in your mod's initializer:

public static void initialize() {
}

public class ExampleModStats implements ModInitializer {
	@Override
	public void onInitialize() {
		ModStats.initialize();
	}
}

Using the Statistic

For this example, we will create a Friends block, which makes friends with its neighbors. We shall track how many friendships the player has formed with the block.

To do this, we will use the Player#awardStat(stat, amount) method to increment the stat by the amount of neighbors the block has when placed:

public class FriendsBlock extends Block {
	@Override
	public void setPlacedBy(Level level, BlockPos pos, BlockState state, @Nullable LivingEntity by, ItemStack itemStack) {
		super.setPlacedBy(level, pos, state, by, itemStack);

		if (!(by instanceof Player player)) return;

		int neighborCount = 0;

		for (Direction dir : Direction.values()) {
			if (!level.isEmptyBlock(pos.relative(dir))) {
				neighborCount++;
			}
		}

		player.awardStat(ModStats.FRIENDSHIPS_MADE, neighborCount);
	}
}

You can also use Player#awardStat(stat) to increment the stat by 1.

Since Friends blocks are very attached to each other, breaking one means breaking all friendships. Let's make it so that breaking a Friends block will reset the player's stat back to 0, by using Player#resetStat():

@Override
public BlockState playerWillDestroy(Level level, BlockPos pos, BlockState state, Player player) {
	player.resetStat(Stats.CUSTOM.get(ModStats.FRIENDSHIPS_MADE));

	return super.playerWillDestroy(level, pos, state, player);
}