Hologram Integration

PhantomDungeons comes with 3 built-in damage indicator styles and exposes a simple registry that lets you drop in your own. Each mob chooses its style through a single YAML key.

Built-in Styles

Style key	Class	Description
modern	ModernDamageHologram	Text-display entity (1.19.4+). Pop-in → hold → shrink + fade. Spawns randomly around entity bounds.
phantom (default)	PhantomHologram	Pooled armor-stand holograms. Smart positional spread per player.
damage	DamageHologram	Legacy physics armor stand. Launches upward with gravity, falls back down.

Configuring a Style in a Mob File

Add the style key inside damage-indicator. The value must match a registered style name (case-insensitive).

any-mob.yml

visual-settings:
  damage-indicator:
    enabled: true
    display: '&c-%damage% &4❤'
    style: "phantom"   # modern | phantom | damage  — or your own registered key

If the key is absent or unrecognised, phantom is used as the safe fallback.

Registering a Custom Style

Implement the DamageIndicatorFactory functional interface from DamageIndicatorRegistry and register it with a unique string key (MUST). Registration is permanent for the lifetime of the servers lifecycle, call it once during your plugin's onEnable().

Step 1 - Implement a factory

The simplest form is a single static method or lambda.

Lambda (simple)

import me.fergs.phantomdungeons.packets.impl.hologram.DamageIndicatorRegistry;

public final class MyPlugin extends JavaPlugin {

    @Override
    public void onEnable() {
        DamageIndicatorRegistry.getInstance().register("my-style", (plugin, player, location, text) -> {
            // Spawn your hologram however you like.
            MyCustomHologram.create(plugin, player, location, text);
        });
    }
}

Method reference

Step 2 - Set the style in the mob file

damage-indicator:
  enabled: true
  display: '&b+%damage% &3★'
  style: "my-style"

That's all, the registry routes every hit on that mob to your factory, and does caching of your class for optimal performance.

Extending the Abstracts

For full control over packet-level animation, extend one of the two abstract bases.

AbstractModernHologram - Text Displays (1.19.4+)

Use this for anything that needs smooth per-tick scale/opacity/scale animation via text-display entities. You must implement three methods.

import me.fergs.phantomdungeons.packets.impl.hologram.AbstractModernHologram;

public final class MyModernHologram extends AbstractModernHologram {

    private static final int DURATION = 30; // ticks

    public MyModernHologram(Plugin plugin, Player viewer, Location location, String text) {
        super(plugin, viewer, location, text);
        // optional stuff: setBackgroundColor(), setShadow(), setSeeThrough(), setScale()
    }

    /** Wire up the BukkitTask. Always call destroy() when onTick() returns false. */
    @Override
    protected void startAnimation() {
        animationTask = Bukkit.getScheduler().runTaskTimerAsynchronously(plugin, () -> {
            if (!onTick()) destroy();
        }, 1L, 1L);
    }

    /**
     * Called every tick. Return true to keep going, false to destroy.
     * Call teleport() after updating posX/posY/posZ to move the entity.
     * Send additional WrapperPlayServerEntityMetadata packets for scale, opacity, etc.
     */
    @Override
    protected boolean onTick() {
        if (!viewer.isOnline() || ticksLived++ >= DURATION) return false;
        posY += 0.04;
        teleport();
        return true;
    }

    @Override
    protected int getMaxTicks() { return DURATION; }

    /** Static factory so it fits DamageIndicatorFactory's signature. */
    public static void create(Plugin plugin, Player player, Location location, String text) {
        new MyModernHologram(plugin, player, location, text).spawn();
    }
}

AbstractLegacyHologram — Armor Stand (all versions)

import me.fergs.phantomdungeons.packets.impl.hologram.AbstractLegacyHologram;

public final class MyLegacyHologram extends AbstractLegacyHologram {

    private static final int DURATION = 25;
    private double velY = 0.25;

    public MyLegacyHologram(Plugin plugin, Player viewer, Location, String text) {
        super(plugin, viewer, location, text);
    }

    @Override
    protected void startAnimation() {
        animationTask = Bukkit.getScheduler().runTaskTimerAsynchronously(plugin, () -> {
            if (!onTick()) destroy();
        }, 1L, 1L);
    }

    @Override
    protected boolean onTick() {
        if (!viewer.isOnline() || ticksLived++ >= DURATION) return false;
        velY -= 0.03;          // gravity
        posY += velY;
        teleport();
        return true;
    }

    @Override
    protected int getMaxTicks() { return DURATION; }

    public static void create(Plugin plugin, Player player, Location location, String text) {
        new MyLegacyHologram(plugin, player, location, text).spawn();
    }
}

Full Example - "Critical Hit" Style

CriticalHologram.java

import com.github.retrooper.packetevents.PacketEvents;
import com.github.retrooper.packetevents.protocol.entity.data.EntityData;
import com.github.retrooper.packetevents.protocol.entity.data.EntityDataTypes;
import com.github.retrooper.packetevents.util.Vector3f;
import com.github.retrooper.packetevents.wrapper.play.server.WrapperPlayServerEntityMetadata;
import me.fergs.phantomdungeons.packets.impl.hologram.AbstractModernHologram;
import org.bukkit.Bukkit;
import org.bukkit.Location;
import org.bukkit.entity.Player;
import org.bukkit.plugin.Plugin;

import java.util.List;
import java.util.concurrent.ThreadLocalRandom;

public final class CriticalHologram extends AbstractModernHologram {

    private static final int   TOTAL = 28;
    private static final float PEAK  = 1.8f;
    private double velY = 0.06;

    private CriticalHologram(Plugin plugin, Player viewer, Location location, String text) {
        super(plugin, viewer, spawnOffset(location), text);
        setBackgroundColor(0x00000000);
        setShadow(true);
    }

    private static Location spawnOffset(Location base) {
        ThreadLocalRandom r = ThreadLocalRandom.current();
        double angle = r.nextDouble(0, Math.PI * 2);
        double radius = r.nextDouble(0.3, 0.7);
        double yOff = r.nextDouble(1.0, 2.2);
        return base.clone().add(Math.cos(angle) * radius, yOff, Math.sin(angle) * radius);
    }

    @Override
    protected void startAnimation() {
        animationTask = Bukkit.getScheduler().runTaskTimerAsynchronously(plugin, () -> {
            if (!onTick()) destroy();
        }, 1L, 1L);
    }

    @Override
    protected boolean onTick() {
        if (!viewer.isOnline() || ticksLived >= TOTAL) return false;
        ticksLived++;

        float t = (float) ticksLived / TOTAL;
        float scale = PEAK * (float) Math.sin(Math.PI * t);
        byte  alpha = (byte) (ticksLived < TOTAL * 0.7 ? -1 : (int) (255 * (1f - t)));

        posY += velY;
        velY *= 0.88;
        teleport();

        var user = PacketEvents.getAPI().getPlayerManager().getUser(viewer);
        if (user == null) return false;
        user.sendPacket(new WrapperPlayServerEntityMetadata(entityId, List.of(
            new EntityData<>(12, EntityDataTypes.VECTOR3F, new Vector3f(scale, scale, scale)),
            new EntityData<>(26, EntityDataTypes.BYTE, alpha)
        )));
        return true;
    }

    @Override
    protected int getMaxTicks() { return TOTAL; }

    public static void create(Plugin plugin, Player player, Location location, String text) {
        new CriticalHologram(plugin, player, location, text).spawn();
    }
}

Register it once:

DamageIndicatorRegistry.getInstance().register("critical", CriticalHologram::create);

Use it in any mob file:

damage-indicator:
  enabled: true
  display: '&6&l%damage%'
  style: "critical"

API Reference

DamageIndicatorRegistry

Method	Description
getInstance()	Returns the singleton registry.
register(String style, DamageIndicatorFactory factory)	Register a new style. Overwrites if the key already exists.
isRegistered(String style)	Check whether a key is currently registered.
get(String style)	Retrieve a factory by key. Returns the modern factory as fallback if unknown.
spawn(String style, Plugin, Player, Location, String text)	Resolve and immediately spawn — convenience wrapper around get().spawn().

DamageIndicatorFactory

@FunctionalInterface
public interface DamageIndicatorFactory {
    void spawn(Plugin plugin, Player player, Location location, String text);
}

All parameters passed to spawn() are guaranteed non-null.

Make sure to depend, before any mob loads

Register your styles inside onEnable(), before PhantomDungeons loads mob configs. If your plugin depends on PhantomDungeons, declare it in plugin.yml:

depend: [PhantomDungeons]

FYI: Your factory receives the already-formatted display string (colours not yet parsed). Call Color.hex(text) inside your hologram constructor or before passing the string to LegacyComponentSerializer if you need colour codes resolved. Or use your own utilities.