Add combat tracker API

build-data/paper.at

@@ -128,6 +128,7 @@ public net.minecraft.world.BossEvent overlay
 public net.minecraft.world.CompoundContainer container1
 public net.minecraft.world.CompoundContainer container2
 public net.minecraft.world.SimpleContainer items
+public net.minecraft.world.damagesource.CombatTracker getMostSignificantFall()Lnet/minecraft/world/damagesource/CombatEntry;
 public net.minecraft.world.damagesource.DamageSource <init>(Lnet/minecraft/core/Holder;Lnet/minecraft/world/entity/Entity;Lnet/minecraft/world/entity/Entity;Lnet/minecraft/world/phys/Vec3;)V
 public net.minecraft.world.effect.MobEffect attributeModifiers
 public net.minecraft.world.effect.MobEffect$AttributeTemplate
@@ -701,6 +702,10 @@ public-f net.minecraft.server.dedicated.DedicatedServer settings
 public-f net.minecraft.server.dedicated.DedicatedServerProperties pauseWhenEmptySeconds
 public-f net.minecraft.server.level.TicketType timeout
 public-f net.minecraft.server.players.PlayerList maxPlayers
+public-f net.minecraft.world.damagesource.CombatTracker entries
+public-f net.minecraft.world.damagesource.CombatTracker inCombat
+public-f net.minecraft.world.damagesource.CombatTracker mob
+public-f net.minecraft.world.damagesource.CombatTracker takingDamage
 public-f net.minecraft.world.entity.LivingEntity combatTracker
 public-f net.minecraft.world.entity.LivingEntity invulnerableDuration
 public-f net.minecraft.world.entity.Mob goalSelector

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

@@ -1,9 +1,14 @@
 package io.papermc.paper;
 
+import io.papermc.paper.world.damagesource.CombatEntry;
+import io.papermc.paper.world.damagesource.FallLocationType;
 import net.kyori.adventure.util.Services;
 import org.bukkit.damage.DamageEffect;
+import org.bukkit.damage.DamageSource;
+import org.bukkit.entity.LivingEntity;
 import org.jetbrains.annotations.ApiStatus;
 import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
 
 /**
  * Static bridge to the server internals.
@@ -35,5 +40,28 @@ class Holder {
      * @return the damage effect.
      */
     DamageEffect getDamageEffect(String key);
+
+    /**
+     * Creates a new combat entry.
+     * <br>
+     * The fall location and fall distance will be calculated from the entity's current state.
+     *
+     * @param entity entity
+     * @param damageSource damage source
+     * @param damage damage amount
+     * @return new combat entry
+     */
+    CombatEntry createCombatEntry(LivingEntity entity, DamageSource damageSource, float damage);
+
+    /**
+     * Creates a new combat entry
+     *
+     * @param damageSource damage source
+     * @param damage damage amount
+     * @param fallLocationType fall location type
+     * @param fallDistance fall distance
+     * @return combat entry
+     */
+    CombatEntry createCombatEntry(DamageSource damageSource, float damage, @Nullable FallLocationType fallLocationType, float fallDistance);
 }
 

paper-api/src/main/java/io/papermc/paper/world/damagesource/CombatEntry.java

@@ -0,0 +1,79 @@
+package io.papermc.paper.world.damagesource;
+
+import io.papermc.paper.InternalAPIBridge;
+import org.bukkit.damage.DamageSource;
+import org.bukkit.entity.Entity;
+import org.bukkit.entity.LivingEntity;
+import org.jetbrains.annotations.ApiStatus;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
+
+/**
+ * Represents a combat entry
+ *
+ * @since 1.21.4
+ */
+@NullMarked
+@ApiStatus.Experimental
+@ApiStatus.NonExtendable
+public interface CombatEntry {
+
+    /**
+     * Gets the damage source
+     *
+     * @return the damage source
+     */
+    DamageSource getDamageSource();
+
+    /**
+     * Gets the amount of damage caused
+     *
+     * @return the amount of damage caused
+     */
+    float getDamage();
+
+    /**
+     * Gets the fall location at the time of this damage
+     *
+     * @return the fall location
+     */
+    @Nullable FallLocationType getFallLocation();
+
+    /**
+     * Gets the fall distance at the time of this damage
+     *
+     * @return the fall distance
+     */
+    float getFallDistance();
+
+    /**
+     * Creates a new combat entry.
+     * <br>
+     * The fall location and fall distance will be calculated from the entity's current state.
+     *
+     * @param entity entity
+     * @param damageSource damage source
+     * @param damage damage amount
+     * @return combat entry
+     * @see #combatEntry(DamageSource, float, FallLocationType, float)
+     */
+    static CombatEntry combatEntry(LivingEntity entity, DamageSource damageSource, float damage) {
+        return InternalAPIBridge.get().createCombatEntry(entity, damageSource, damage);
+    }
+
+    /**
+     * Creates a new combat entry
+     *
+     * @param damageSource damage source
+     * @param damage damage amount
+     * @param fallLocationType fall location type
+     * @param fallDistance fall distance
+     * @return a new combat entry
+     * @see LivingEntity#calculateFallLocationType()
+     * @see Entity#getFallDistance()
+     */
+    static CombatEntry combatEntry(DamageSource damageSource, float damage, @Nullable FallLocationType fallLocationType, float fallDistance) {
+        return InternalAPIBridge.get().createCombatEntry(damageSource, damage, fallLocationType, fallDistance);
+    }
+
+}

paper-api/src/main/java/io/papermc/paper/world/damagesource/CombatTracker.java

@@ -0,0 +1,106 @@
+package io.papermc.paper.world.damagesource;
+
+import net.kyori.adventure.text.Component;
+import org.bukkit.entity.LivingEntity;
+import org.jetbrains.annotations.ApiStatus;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
+
+import java.util.List;
+
+/**
+ * Represents entity's combat tracker
+ *
+ * @since 1.21.4
+ */
+@NullMarked
+@ApiStatus.Experimental
+@ApiStatus.NonExtendable
+public interface CombatTracker {
+
+    /**
+     * Gets the entity behind this combat tracker
+     *
+     * @return the entity behind this combat tracker
+     */
+    LivingEntity getEntity();
+
+    /**
+     * Gets the list of recorded combat entries.
+     * <br>
+     * The returned list is a copy, so any modifications
+     * to its contents won't have an effect on this entity's
+     * combat history.
+     *
+     * @return the list of combat entries
+     * @see #setCombatEntries(List)
+     */
+    List<CombatEntry> getCombatEntries();
+
+    /**
+     * Sets the entity's combat history.
+     * <br>
+     * Note that overriding the entity's combat history won't
+     * have an effect on the entity's current or new combat state.
+     * Reset the current combat state and register new combat entries instead
+     * if you want the new history to have an effect on the combat state.
+     *
+     * @param combatEntries combat entries
+     * @see #resetCombatState()
+     * @see #addCombatEntry(CombatEntry)
+     */
+    void setCombatEntries(List<CombatEntry> combatEntries);
+
+    /**
+     * Calculates the most significant fall damage entry
+     *
+     * @return the most significant fall damage entry
+     */
+    @Nullable CombatEntry getMostSignificantFall();
+
+    /**
+     * Checks whether the entity is in combat,
+     * i.e. has taken damage from an entity
+     * since the combat tracking has begun
+     *
+     * @return whether the entity is in combat
+     */
+    boolean isInCombat();
+
+    /**
+     * Checks whether the entity has started recording damage,
+     * i.e. its combat tracking is active
+     *
+     * @return whether the entity has started recording damage
+     */
+    boolean isTakingDamage();
+
+    /**
+     * Gets the last or current combat duration
+     *
+     * @return the combat duration
+     * @see #isInCombat()
+     */
+    int getCombatDuration();
+
+    /**
+     * Adds a new entry the pool of combat entries,
+     * updating the entity's combat state
+     *
+     * @param combatEntry combat entry
+     */
+    void addCombatEntry(CombatEntry combatEntry);
+
+    /**
+     * Constructs a death message based on the current combat history
+     *
+     * @return a death message
+     */
+    Component getDeathMessage();
+
+    /**
+     * Resets entity's combat state, clearing combat history
+     */
+    void resetCombatState();
+
+}

paper-api/src/main/java/io/papermc/paper/world/damagesource/FallLocationType.java

@@ -0,0 +1,65 @@
+package io.papermc.paper.world.damagesource;
+
+import net.kyori.adventure.translation.Translatable;
+import org.jetbrains.annotations.ApiStatus;
+import org.jspecify.annotations.NullMarked;
+
+/**
+ * Represents a type of location from which the entity fell
+ *
+ * @since 1.21.4
+ */
+@NullMarked
+@ApiStatus.Experimental
+public sealed interface FallLocationType extends Translatable permits FallLocationTypeImpl {
+
+    /**
+     * Gets the fall location id
+     *
+     * @return the fall location id
+     */
+    String id();
+
+    /**
+     * Gets the translation key used for a fall death message
+     * caused by falling from this location
+     *
+     * @return the translation key
+     */
+    @Override
+    String translationKey();
+
+    /**
+     * The entity is not within a special fall location
+     */
+    FallLocationType GENERIC = new FallLocationTypeImpl("generic");
+    /**
+     * The entity is within the ladder
+     */
+    FallLocationType LADDER = new FallLocationTypeImpl("ladder");
+    /**
+     * The entity is in vines
+     */
+    FallLocationType VINES = new FallLocationTypeImpl("vines");
+    /**
+     * The entity is in weeping wines
+     */
+    FallLocationType WEEPING_VINES = new FallLocationTypeImpl("weeping_vines");
+    /**
+     * The entity is in twisting vines
+     */
+    FallLocationType TWISTING_VINES = new FallLocationTypeImpl("twisting_vines");
+    /**
+     * The entity is in scaffolding
+     */
+    FallLocationType SCAFFOLDING = new FallLocationTypeImpl("scaffolding");
+    /**
+     * The entity is within some other climable block
+     */
+    FallLocationType OTHER_CLIMBABLE = new FallLocationTypeImpl("other_climbable");
+    /**
+     * The entity is in water
+     */
+    FallLocationType WATER = new FallLocationTypeImpl("water");
+
+}

paper-api/src/main/java/io/papermc/paper/world/damagesource/FallLocationTypeImpl.java

@@ -0,0 +1,14 @@
+package io.papermc.paper.world.damagesource;
+
+import org.jspecify.annotations.NullMarked;
+
+@NullMarked
+record FallLocationTypeImpl(String id) implements FallLocationType {
+
+    @Override
+    public String translationKey() {
+        // Same as net.minecraft.world.damagesource.FallLocation#languageKey
+        return "death.fell.accident." + this.id;
+    }
+
+}

paper-api/src/main/java/org/bukkit/entity/LivingEntity.java

@@ -4,6 +4,8 @@
 import java.util.List;
 import java.util.Set;
 import java.util.UUID;
+import io.papermc.paper.world.damagesource.CombatTracker;
+import io.papermc.paper.world.damagesource.FallLocationType;
 import org.bukkit.FluidCollisionMode;
 import org.bukkit.Location;
 import org.bukkit.Material;
@@ -21,6 +23,7 @@
 import org.bukkit.scoreboard.Team;
 import org.bukkit.util.RayTraceResult;
 import org.bukkit.util.Vector;
+import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
@@ -1468,4 +1471,22 @@ default void swingHand(@NotNull org.bukkit.inventory.EquipmentSlot hand) {
      */
     boolean canUseEquipmentSlot(org.bukkit.inventory.@NotNull EquipmentSlot slot);
     // Paper end - Expose canUseSlot
+
+    /**
+     * Gets the entity's combat tracker
+     *
+     * @return the entity's combat tracker
+     * @since 1.21.4
+     */
+    @ApiStatus.Experimental
+    @NotNull CombatTracker getCombatTracker();
+
+    /**
+     * Calculates fall location from current entity's location
+     *
+     * @return fall location
+     * @since 1.21.4
+     */
+    @ApiStatus.Experimental
+    @NotNull FallLocationType calculateFallLocationType();
 }