DamageOverlay

A lightweight, client-side damage popup overlay for NeoForge. It renders floating damage numbers in the world at the position you specify, complete with a configurable rise trajectory, fade-out animation, and a small API that other mods can call.

Features

• Floating damage text anchored to any world position
• Smooth rise + fade-out animation
• Random horizontal spread and slope per popup, so multiple hits on one target don't stack on top of each other
• Fully configurable via the in-game config screen
• Tiny public API (DamageApi) for other mods to trigger popups

API Reference

Add DamageOverlay as an optional dependency, then call the API. It is safe to guard with ModList.get().isLoaded("damageoverlay") if you want a hard fallback.

Entry point

DamageApi api = DamageApi.get();

Spawning a popup

All overloads delegate to the single abstract method:

void popup(double damageAmount, double x, double y, double z, PopupOptions options);

Convenience overloads:

Example:

DamageApi.get().popup(12.5, entity.getX(), entity.getY() + 1.0, entity.getZ());

Calls are thread-safe: they are marshalled onto the client thread internally.

PopupOptions

An immutable record with builder-style copies:

record PopupOptions(int color, float scale, float endScaleFactor, long lifetimeMs, float riseSpeed, boolean appendExclamationMark)

• color — 0xRRGGBB; the alpha channel is ignored (opacity is driven by the fade-out).
• scale — text scale multiplier at spawn (default 1.0).
• endScaleFactor — multiplier applied to scale at the end of the lifetime, interpolated linearly from 1.0 as the popup ages. 1.0 keeps the size constant, 0.5 shrinks the text to half its spawn size, 0.0 shrinks it away. Clamped to at least 0.
• lifetimeMs — total time on screen including the fade, clamped to at least 1.
• riseSpeed — GUI pixels per second of vertical travel.
• appendExclamationMark — when true, a ! is appended to the formatted damage value.

Factory and helpers:

PopupOptions.defaults()          // reads the current config values
.withColor(int color)
.withScale(float scale)
.withEndScaleFactor(float endScaleFactor)
.withLifetime(long lifetimeMs)
.withRiseSpeed(float riseSpeed)
.withAppendExclamationMark(boolean appendExclamationMark)

Example:

DamageApi.get().popup(42.0, x, y, z,
    PopupOptions.defaults()
        .withColor(0xFFAA00)
        .withScale(1.5F)
        .withLifetime(1000L)
        .withAppendExclamationMark(true));

Configuration

The default riseSpeed is derived from RisePixels and Lifetime:

riseSpeed = RisePixels * 1000 / Lifetime   // px per second

How it works

Each popup stores its world position, a random slope k in [MinSlope, MaxSlope], and a spawn timestamp. Every frame the renderer:

1. Projects the world position through the level camera's model-view and projection matrices.
2. Computes age = (now - createdAt) / lifetimeMs.
3. Moves the text along a straight trajectory where horizontal travel = vertical travel / k — so small slopes drift sideways while large slopes rise almost vertically.
4. Fades the alpha from 255 to 0 over the lifetime.
5. Scales the text from scale down (or up) to scale * endScaleFactor over the lifetime.
6. Skips anything that lands outside the GUI bounds.

Popups are added and expired on the client thread, so the list is only ever mutated where it's safe to do so.