Description

Want to see who contributed to a player's death? This mod is for you.

It tracks all entities that attacked a player during a fight and displays their names on the death screen and in the kill feed. The mod also includes an API that allows other mods to access this data. For example, PvP mods can award XP to players when they kill another player.

Kill Assists has two main configuration modes: Last Hit and Top Damage.

Last Hit: The kill is awarded to the last player who hit the victim.

Top Damage: The kill is awarded to the player who dealt the most damage, preventing kill stealing.

The mod (and its API!) can also provide damage percentages, allowing you to see how much damage each participant dealt. Mod developers can use this data, for example, to award XP proportionally to the damage dealt.

Includes complete integration documentation for mod developers!

Compatible with Hydowned Revival!

User and API documentation for mod owners

KillAssists — Documentation

Part 1: Configuration

Everything you need to configure the mod as a server owner. No code required.

Config file

On first launch, a config file is created at mods/KillAssists/config.json (relative to the server working directory). Edit it and restart the server, or use the in-game command to change settings live.

{
  "_comment_assistWindowMs": "Time window in milliseconds. Any damage dealt within this window before death counts as an assist. Range: 1000-120000",
  "assistWindowMs": 10000,

  "_comment_maxAssistsDisplayed": "Maximum number of assist names shown in the kill feed and death screen. Range: 1-10",
  "maxAssistsDisplayed": 3,

  "_comment_trackMobDamage": "If true, mob/NPC damage is tracked as assists. If false, only player damage counts.",
  "trackMobDamage": true,

  "_comment_killAttribution": "Who gets credited as the killer in the API (data sent to other mods). 'last_hit' = entity that dealt the killing blow. 'top_damage' = entity that dealt the most total damage. Does NOT affect what is displayed in-game.",
  "killAttribution": "last_hit",

  "_comment_displayMode": "Who is shown as the killer in the kill feed and death screen. 'last_hit' = last hit dealer. 'top_damage' = top damage dealer (marked with %). Independent from killAttribution.",
  "displayMode": "last_hit",

  "_comment_showPercentages": "If true, damage percentages are shown next to each name in the kill feed and death screen. Example: 'PlayerA (62%) [+PlayerB (25%), Mob (13%)]'. Works with both displayMode values.",
  "showPercentages": false
}

Settings explained

assistWindowMs

Time window in milliseconds. When a player dies, the mod looks back this far to find all entities that dealt damage. Default: 10000 (10 seconds). Range: 1000–120000.

maxAssistsDisplayed

Maximum number of assist names shown in the kill feed and death screen. If there are more, the rest are shown as +N. Default: 3. Range: 1–10.

trackMobDamage

If true, damage from mobs and NPCs counts as assists. If false, only player damage is tracked. Default: true.

killAttribution

Who is considered the "killer" in the API (the KillEvent sent to other mods like PvP stats trackers). Does not change what players see in-game.

displayMode

Who is shown as the killer in-game (kill feed pastille and death screen). Independent from killAttribution.

You can mix and match — for example, killAttribution: "top_damage" (API credits top damage) + displayMode: "last_hit" (players see the classic last-hit display).

showPercentages

If true, damage percentages are displayed next to each name in the kill feed and death screen.

In-game command

/killassists [setting] [value]

No arguments: shows current config. All changes are saved to the config file immediately.

Part 2: API for mod developers

Everything you need to hook into KillAssists from another mod.

Dependency

Add KillAssists as a dependency in your manifest.json:

{
  "dependencies": ["KillAssists"]
}

Public classes are in the com.killassists.api package.

Listening to kills

Every player death fires a KillEvent, with or without assists. The event always includes damage percentages for every entity involved, regardless of configuration. Register a listener in your plugin's setup():

import com.killassists.api.KillAssistsAPI;
import com.killassists.api.KillEvent;

@Override
public void setup() {
    KillAssistsAPI.addKillListener(event -> {
        String victim = event.getVictimName();       // "Steve"
        UUID victimUuid = event.getVictimUuid();

        String killer = event.getKillerName();       // "Alex"
        float killerPct = event.getKillerDamagePercent(); // e.g. 35.0
        String mode = event.getAttributionMode();    // "last_hit" or "top_damage"

        for (KillEvent.AssistEntry assist : event.getAssists()) {
            assist.getDisplayName();     // "Skeleton Fighter", "PlayerX"
            assist.getTotalDamage();     // raw damage dealt
            assist.getDamagePercent();   // percentage of total damage (e.g. 45.2)
            assist.isPlayer();           // true if player
            assist.getPlayerUuid();      // player UUID (null if mob)
        }
    });
}

To remove a listener:

KillAssistsAPI.removeKillListener(myListener);

KillEvent

Received on every player death. All lists are immutable.

AssistEntry

Each entity (player or mob) that dealt damage within the time window, excluding the killer.

Kill attribution in the API

The killAttribution config setting controls who is labeled as "killer" vs. "assister" in the KillEvent. The displayMode and showPercentages settings have no effect on the API — they only change the in-game display.

// Example: PlayerA did 90% damage, PlayerB got the last hit
// killAttribution = last_hit:   killer = PlayerB (10%), assists = [PlayerA (90%)]
// killAttribution = top_damage: killer = PlayerA (90%), assists = [PlayerB (10%)]

In all modes, the KillEvent always includes full damage percentages for every entity.

Reading / modifying config at runtime

Allows another mod to adjust KillAssists settings programmatically. All changes are saved to mods/KillAssists/config.json immediately and persist across restarts.

// Read
long window = KillAssistsAPI.getAssistWindowMs();             // default: 10000
int maxDisplay = KillAssistsAPI.getMaxAssistsDisplayed();     // default: 3
boolean trackMobs = KillAssistsAPI.isTrackMobDamage();        // default: true
String attribution = KillAssistsAPI.getKillAttribution();     // default: "last_hit"
boolean isTopAttr = KillAssistsAPI.isTopDamageAttribution();  // default: false
String display = KillAssistsAPI.getDisplayMode();             // default: "last_hit"
boolean isTopDisp = KillAssistsAPI.isTopDamageDisplay();      // default: false
boolean showPct = KillAssistsAPI.isShowPercentages();         // default: false

// Modify
KillAssistsAPI.setAssistWindowMs(15000);             // 15 seconds
KillAssistsAPI.setMaxAssistsDisplayed(5);            // max 5 assists displayed
KillAssistsAPI.setTrackMobDamage(false);             // ignore mob damage
KillAssistsAPI.setKillAttribution("top_damage");     // API: top damage = killer
KillAssistsAPI.setDisplayMode("top_damage");         // UI: top damage = killer
KillAssistsAPI.setShowPercentages(true);             // UI: show damage %

Full example: PvP stats mod

public class PvPStatsPlugin extends JavaPlugin {

    public PvPStatsPlugin(JavaPluginInit init) { super(init); }

    @Override
    public void setup() {
        KillAssistsAPI.addKillListener(event -> {
            if (!event.isKillerPlayer()) return;

            UUID killerUuid = event.getKillerUuid();
            UUID victimUuid = event.getVictimUuid();

            // Record kill with damage share
            addKill(killerUuid, event.getKillerDamagePercent());
            addDeath(victimUuid);

            // Record all player assists with their damage contribution
            for (KillEvent.AssistEntry assist : event.getAssists()) {
                if (assist.isPlayer()) {
                    addAssist(assist.getPlayerUuid(),
                              assist.getTotalDamage(),
                              assist.getDamagePercent());
                }
            }
        });
    }
}

Notes

• The event is fired server-side within the ECS system, during death processing.
• Listeners are thread-safe (CopyOnWriteArrayList).
• Exceptions in a listener are silently swallowed to avoid breaking other listeners or the game.
• The assist list in KillEvent contains all assisters (not limited by maxAssistsDisplayed — that limit only applies to in-game display).
• Damage percentages are always computed and included in the KillEvent, regardless of killAttribution, displayMode, or showPercentages settings.
• killAttribution and displayMode are independent: you can have the API credit top damage while the UI shows last hit, or vice versa.