Hytale Player Death Event

Hytale Player Death Event

Use this skill when reacting to player (or entity) death in a Hytale plugin. Death detection uses the ECS RefChangeSystem pattern — specifically DeathSystems.OnDeathSystem — which fires when a DeathComponent is added to an entity.

Source: https://hytalemodding.dev/en/docs/guides/plugin/player-death-event

Related skills: hytale-events (general event system), hytale-ecs (ECS fundamentals), hytale-entity-effects (effects/damage pipeline).

Quick Reference

How It Works

1. When an entity's health reaches zero, the damage pipeline attaches a DeathComponent to the entity.
2. Any system extending DeathSystems.OnDeathSystem whose getQuery() matches the entity is notified via onComponentAdded.
3. The DeathComponent carries a Damage object with information about the killing blow (amount, source, etc.).

This is a RefChangeSystem — it reacts to component lifecycle changes, not tick-based updates.

Required Imports

import com.hypixel.hytale.component.CommandBuffer;
import com.hypixel.hytale.component.Ref;
import com.hypixel.hytale.component.Store;
import com.hypixel.hytale.component.query.Query;
import com.hypixel.hytale.server.core.Message;
import com.hypixel.hytale.server.core.entity.entities.Player;
import com.hypixel.hytale.server.core.modules.entity.damage.Damage;
import com.hypixel.hytale.server.core.modules.entity.damage.DeathComponent;
import com.hypixel.hytale.server.core.modules.entity.damage.DeathSystems;
import com.hypixel.hytale.server.core.universe.Universe;
import com.hypixel.hytale.server.core.universe.world.storage.EntityStore;
import javax.annotation.Nonnull;

Step-by-Step

1. Create a class extending DeathSystems.OnDeathSystem

public class PlayerDeathHandler extends DeathSystems.OnDeathSystem {

OnDeathSystem is a specialised RefChangeSystem that listens for DeathComponent additions.

2. Define which entities to watch with getQuery()

@Nonnull
@Override
public Query<EntityStore> getQuery() {
    return Query.and(Player.getComponentType());
}

Query.and(Player.getComponentType()) ensures only entities that have a Player component trigger this system. You can combine multiple component types to narrow the filter further.

3. Override onComponentAdded to handle the death

@Override
public void onComponentAdded(
        @Nonnull Ref ref,
        @Nonnull DeathComponent component,
        @Nonnull Store store,
        @Nonnull CommandBuffer commandBuffer) {

    Player playerComponent = (Player) store.getComponent(ref, Player.getComponentType());
    assert playerComponent != null;

    // React to the death
    Universe.get().sendMessage(
        Message.raw("Player died: " + playerComponent.getDisplayName()));

    // Access death damage info
    Damage deathInfo = component.getDeathInfo();
    if (deathInfo != null) {
        Universe.get().sendMessage(
            Message.raw("Damage amount: " + deathInfo.getAmount()));
    }
}

Parameters:

4. Register the system in your plugin's start() method

@Override
protected void start() {
    this.getEntityStoreRegistry().registerSystem(new PlayerDeathHandler());
}

Death systems are registered the same way as any other ECS system — via getEntityStoreRegistry().registerSystem() in the plugin's start() lifecycle method.

Complete Example

package com.example.plugin.systems;

import com.hypixel.hytale.component.CommandBuffer;
import com.hypixel.hytale.component.Ref;
import com.hypixel.hytale.component.Store;
import com.hypixel.hytale.component.query.Query;
import com.hypixel.hytale.server.core.Message;
import com.hypixel.hytale.server.core.entity.entities.Player;
import com.hypixel.hytale.server.core.modules.entity.damage.Damage;
import com.hypixel.hytale.server.core.modules.entity.damage.DeathComponent;
import com.hypixel.hytale.server.core.modules.entity.damage.DeathSystems;
import com.hypixel.hytale.server.core.universe.Universe;
import com.hypixel.hytale.server.core.universe.world.storage.EntityStore;
import javax.annotation.Nonnull;

public class PlayerDeathHandler extends DeathSystems.OnDeathSystem {

    @Nonnull
    @Override
    public Query<EntityStore> getQuery() {
        return Query.and(Player.getComponentType());
    }

    @Override
    public void onComponentAdded(
            @Nonnull Ref ref,
            @Nonnull DeathComponent component,
            @Nonnull Store store,
            @Nonnull CommandBuffer commandBuffer) {

        Player playerComponent = (Player) store.getComponent(ref, Player.getComponentType());
        assert playerComponent != null;

        Universe.get().sendMessage(
            Message.raw("Player died: " + playerComponent.getDisplayName()));

        Damage deathInfo = component.getDeathInfo();
        if (deathInfo != null) {
            Universe.get().sendMessage(
                Message.raw("Damage amount: " + deathInfo.getAmount()));
        }
    }
}

Tips

• Null-check getDeathInfo() — it can be null if the entity was removed without going through the damage pipeline (e.g., /kill or direct removal).
• Use Query.and(...) with multiple component types to restrict death handling to specific entity subsets (e.g., players with a certain custom component).
• Exclude dead entities from other systems by adding Query.not(DeathComponent.getComponentType()) to their queries so they stop processing dead entities immediately.
• Use CommandBuffer (not direct store mutation) if you need to add/remove components in response to a death — this ensures thread safety and proper ordering.
• Localize death messages using Message.translation(...) instead of Message.raw(...) for user-facing text.

Key Classes