Better Stats API

paper-api/src/generated/java/io/papermc/paper/registry/keys/StatisticTypeKeys.java

@@ -0,0 +1,97 @@
+package io.papermc.paper.registry.keys;
+
+import static net.kyori.adventure.key.Key.key;
+
+import io.papermc.paper.annotation.GeneratedClass;
+import io.papermc.paper.registry.RegistryKey;
+import io.papermc.paper.registry.TypedKey;
+import io.papermc.paper.statistic.StatisticType;
+import net.kyori.adventure.key.Key;
+import org.jspecify.annotations.NullMarked;
+
+/**
+ * Vanilla keys for {@link RegistryKey#STAT_TYPE}.
+ *
+ * @apiNote The fields provided here are a direct representation of
+ * what is available from the vanilla game source. They may be
+ * changed (including removals) on any Minecraft version
+ * bump, so cross-version compatibility is not provided on the
+ * same level as it is on most of the other API.
+ */
+@SuppressWarnings({
+        "unused",
+        "SpellCheckingInspection"
+})
+@NullMarked
+@GeneratedClass
+public final class StatisticTypeKeys {
+    /**
+     * {@code minecraft:broken}
+     *
+     * @apiNote This field is version-dependant and may be removed in future Minecraft versions
+     */
+    public static final TypedKey<StatisticType<?>> BROKEN = create(key("broken"));
+
+    /**
+     * {@code minecraft:crafted}
+     *
+     * @apiNote This field is version-dependant and may be removed in future Minecraft versions
+     */
+    public static final TypedKey<StatisticType<?>> CRAFTED = create(key("crafted"));
+
+    /**
+     * {@code minecraft:custom}
+     *
+     * @apiNote This field is version-dependant and may be removed in future Minecraft versions
+     */
+    public static final TypedKey<StatisticType<?>> CUSTOM = create(key("custom"));
+
+    /**
+     * {@code minecraft:dropped}
+     *
+     * @apiNote This field is version-dependant and may be removed in future Minecraft versions
+     */
+    public static final TypedKey<StatisticType<?>> DROPPED = create(key("dropped"));
+
+    /**
+     * {@code minecraft:killed}
+     *
+     * @apiNote This field is version-dependant and may be removed in future Minecraft versions
+     */
+    public static final TypedKey<StatisticType<?>> KILLED = create(key("killed"));
+
+    /**
+     * {@code minecraft:killed_by}
+     *
+     * @apiNote This field is version-dependant and may be removed in future Minecraft versions
+     */
+    public static final TypedKey<StatisticType<?>> KILLED_BY = create(key("killed_by"));
+
+    /**
+     * {@code minecraft:mined}
+     *
+     * @apiNote This field is version-dependant and may be removed in future Minecraft versions
+     */
+    public static final TypedKey<StatisticType<?>> MINED = create(key("mined"));
+
+    /**
+     * {@code minecraft:picked_up}
+     *
+     * @apiNote This field is version-dependant and may be removed in future Minecraft versions
+     */
+    public static final TypedKey<StatisticType<?>> PICKED_UP = create(key("picked_up"));
+
+    /**
+     * {@code minecraft:used}
+     *
+     * @apiNote This field is version-dependant and may be removed in future Minecraft versions
+     */
+    public static final TypedKey<StatisticType<?>> USED = create(key("used"));
+
+    private StatisticTypeKeys() {
+    }
+
+    private static TypedKey<StatisticType<?>> create(final Key key) {
+        return TypedKey.create(RegistryKey.STAT_TYPE, key);
+    }
+}

paper-api/src/main/java/io/papermc/paper/InternalAPIBridge.java

@@ -16,6 +16,7 @@
 import org.bukkit.damage.DamageSource;
 import org.bukkit.entity.LivingEntity;
 import org.bukkit.entity.Pose;
+import org.bukkit.scoreboard.Criteria;
 import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.Contract;
 import org.jspecify.annotations.NullMarked;
@@ -104,4 +105,12 @@ class Holder {
     <MODERN, LEGACY> GameRule<LEGACY> legacyGameRuleBridge(GameRule<MODERN> rule, Function<LEGACY, MODERN> fromLegacyToModern, Function<MODERN, LEGACY> toLegacyFromModern, Class<LEGACY> legacyClass);
 
     Set<Pose> validMannequinPoses();
+
+    /**
+     * Gets the criteria for the non-stat built-in scoreboard criteria.
+     *
+     * @param key the key
+     * @return the criteria
+     */
+    Criteria getCriteria(String key);
 }

paper-api/src/main/java/io/papermc/paper/event/player/PlayerRequestStatisticsEvent.java

@@ -0,0 +1,56 @@
+package io.papermc.paper.event.player;
+
+import io.papermc.paper.statistic.Statistic;
+import it.unimi.dsi.fastutil.objects.Object2IntMap;
+import org.bukkit.entity.Player;
+import org.bukkit.event.Cancellable;
+import org.bukkit.event.HandlerList;
+import org.bukkit.event.player.PlayerEvent;
+import org.jetbrains.annotations.ApiStatus;
+import org.jspecify.annotations.NullMarked;
+
+/**
+ * Called when the player requests their statistics.
+ */
+@NullMarked
+public class PlayerRequestStatisticsEvent extends PlayerEvent implements Cancellable {
+
+    private static final HandlerList HANDLER_LIST = new HandlerList();
+
+    private final Object2IntMap<Statistic<?>> statisticMap;
+    private boolean cancelled;
+
+    @ApiStatus.Internal
+    public PlayerRequestStatisticsEvent(final Player player, final Object2IntMap<Statistic<?>> statisticMap) {
+        super(player);
+        this.statisticMap = statisticMap;
+    }
+
+    /**
+     * Gets the statistic map to be sent to the player.
+     *
+     * @return the mutable statistic map
+     */
+    public Object2IntMap<Statistic<?>> getStatisticMap() {
+        return this.statisticMap;
+    }
+
+    @Override
+    public boolean isCancelled() {
+        return this.cancelled;
+    }
+
+    @Override
+    public void setCancelled(final boolean cancel) {
+        this.cancelled = cancel;
+    }
+
+    @Override
+    public HandlerList getHandlers() {
+        return HANDLER_LIST;
+    }
+
+    public static HandlerList getHandlerList() {
+        return HANDLER_LIST;
+    }
+}

paper-api/src/main/java/io/papermc/paper/registry/RegistryKey.java

@@ -3,6 +3,8 @@
 import io.papermc.paper.datacomponent.DataComponentType;
 import io.papermc.paper.dialog.Dialog;
 import io.papermc.paper.registry.tag.TagKey;
+import io.papermc.paper.statistic.CustomStatistic;
+import io.papermc.paper.statistic.StatisticType;
 import net.kyori.adventure.key.Key;
 import net.kyori.adventure.key.KeyPattern;
 import net.kyori.adventure.key.Keyed;
@@ -132,6 +134,16 @@ public sealed interface RegistryKey<T> extends Keyed permits RegistryKeyImpl {
      * @see io.papermc.paper.registry.keys.GameRuleKeys
      */
     RegistryKey<GameRule<?>> GAME_RULE = create("game_rule");
+    /**
+     * Built-in registry for custom statistics.
+     * @see io.papermc.paper.registry.keys.CustomStatisticKeys
+     */
+    RegistryKey<CustomStatistic> CUSTOM_STAT = create("custom_stat");
+    /**
+     * Built-in registry for statistic types.
+     * @see io.papermc.paper.registry.keys.StatisticTypeKeys
+     */
+    RegistryKey<StatisticType<?>> STAT_TYPE = create("stat_type");
 
     /* ********************** *
      * Data-driven Registries *

paper-api/src/main/java/io/papermc/paper/statistic/CustomStatistic.java

@@ -0,0 +1,23 @@
+package io.papermc.paper.statistic;
+
+import net.kyori.adventure.translation.Translatable;
+import org.bukkit.Keyed;
+import org.jetbrains.annotations.ApiStatus;
+
+/**
+ * Represents a statistic of the type {@link StatisticTypes#CUSTOM}.
+ *
+ * @see CustomStatistics
+ */
+@ApiStatus.NonExtendable
+public interface CustomStatistic extends Keyed, Translatable {
+
+    /**
+     * Gets the statistic with the given custom stat.
+     *
+     * @return the statistic for the custom stat
+     */
+    default Statistic<CustomStatistic> stat() {
+        return StatisticTypes.CUSTOM.forValue(this);
+    }
+}