Skip to content

Screen Overlays

Gugas749 edited this page Nov 5, 2026 · 1 revision

Screen overlays

Colored tints or vignettes over the player's screen. There are three ways to trigger one: an effect (shown while the player has it), a damage type (flashes when hit by it), or by hand from server code.

import com.gugas749.abysscore.api.overlay.AbyssOverlaySpec;
import com.gugas749.abysscore.api.overlay.AbyssScreenOverlay;

What it looks like — AbyssOverlaySpec

AbyssOverlaySpec.tint(0xAA0000, 0.25f)         // whole screen, red, 25% opacity
AbyssOverlaySpec.vignette(0x5A0080, 0.6f)      // edges only, purple, 60%
        .fade(10, 20)                          // 10 ticks fade in, 20 ticks fade out
        .scaleWithAmplifier()                  // effect overlays only: I=25%, II=50%, III=75%, IV+=100%
Part Description
tint(rgb, alpha) Style.TINT: fills the whole screen
vignette(rgb, alpha) Style.VIGNETTE: dark gradient on the edges, clear center
rgb 0xRRGGBB. Any alpha byte you pass is dropped.
alpha Max opacity, 0.0–1.0 (clamped)
.fade(inTicks, outTicks) Default is fade(5, 10). 20 ticks = 1 s.
.scaleWithAmplifier() Strength follows the effect level. Only used by bindEffect.

The spec is an immutable record: every method returns a new copy. Its fields are color(), maxAlpha(), style(), fadeInTicks(), fadeOutTicks() and ampScaling().

1. Effect → overlay

Shown for as long as the player has the effect. No packets involved: the client reads its own effects every frame, so this must be called on BOTH sides.

NeoForge 1.21.1: call it in the mod constructor. Vanilla MobEffects.X and your DeferredHolders are already holders.

public MyMod(IEventBus modBus) {
    AbyssScreenOverlay.bindEffect(MyEffects.BLEEDING,      // DeferredHolder<MobEffect, ...>
            AbyssOverlaySpec.vignette(0xAA0000, 0.5f).scaleWithAmplifier());

    AbyssScreenOverlay.bindEffect(MobEffects.POISON,
            AbyssOverlaySpec.tint(0x4E9331, 0.15f));
}

Forge 1.20.1: MobEffects.X and RegistryObject.get() are plain MobEffects, not holders. There are two options:

// a) By id: works anywhere, including the mod constructor (nothing needs to be registered yet)
public MyMod() {
    AbyssScreenOverlay.bindEffect(new ResourceLocation("mymod", "bleeding"),
            AbyssOverlaySpec.vignette(0xAA0000, 0.5f).scaleWithAmplifier());
    AbyssScreenOverlay.bindEffect(new ResourceLocation("minecraft", "poison"),
            AbyssOverlaySpec.tint(0x4E9331, 0.15f));
}

// b) By MobEffect: the effect must already be registered, so use common setup (it runs on both sides)
modBus.addListener((FMLCommonSetupEvent e) -> e.enqueueWork(() ->
        AbyssScreenOverlay.bindEffect(MyEffects.BLEEDING.get(),
                AbyssOverlaySpec.vignette(0xAA0000, 0.5f).scaleWithAmplifier())));
Overload When to use Throws if
bindEffect(Holder<MobEffect>, spec) NeoForge: MobEffects.X, DeferredHolder The holder has no registry key (a direct holder)
bindEffect(ResourceLocation, spec) Both versions, any time Never. A wrong id just never matches.
bindEffect(MobEffect, spec) Forge: RegistryObject.get(), after registration The effect isn't registered yet
unbindEffect(ResourceLocation) Remove a binding (call it on both sides too)

Binding the same effect again replaces its spec. With a fade-out set, the overlay also fades as the effect's last ticks run out (infinite effects don't fade).

2. Damage type → flash

AbyssScreenOverlay.bindDamageType(MyDamageTypes.CURSE,
        AbyssOverlaySpec.tint(0x5A0080, 0.35f).fade(2, 15),
        20);                                                // shown for 20 ticks

This is checked on the server after armor and resistances, and only fires if damage > 0 actually went through. Call it from the mod constructor or common setup.

3. By hand (server)

ResourceLocation FLASH = ResourceLocation.fromNamespaceAndPath("mymod", "flash");  // Forge 1.20.1: new ResourceLocation(...)

AbyssScreenOverlay.show(player, FLASH, AbyssOverlaySpec.tint(0xFFFFFF, 0.8f).fade(0, 8), 10);  // white flash, 10 ticks
AbyssScreenOverlay.clear(player, FLASH);    // fades it out using its fade-out time (not an instant cut)
  • Same id shown again = replaced, and its timer restarts. Different ids stack.
  • Duration is at least 1 tick.
  • Damage-type overlays use the id <namespace>:damage/<path>, so clear(player, thatId) works on them too.
  • Overlays are cleared when the player leaves the server.

Examples:

// Cutscene: fade to black for 3 seconds, then back
AbyssScreenOverlay.show(player, id("cutscene"), AbyssOverlaySpec.tint(0x000000, 1f).fade(20, 20), 60);

// "Low sanity" vignette that stays until cleared (very long duration, cleared by hand)
AbyssScreenOverlay.show(player, id("sanity"), AbyssOverlaySpec.vignette(0x101020, 0.7f).fade(40, 40), 20 * 60 * 60);
// ...later
AbyssScreenOverlay.clear(player, id("sanity"));

// Pulse red for everyone near an explosion
for (ServerPlayer p : level.getEntitiesOfClass(ServerPlayer.class, new AABB(pos).inflate(16))) {
    AbyssScreenOverlay.show(p, id("blast"), AbyssOverlaySpec.vignette(0xFF3000, 0.6f).fade(1, 15), 16);
}

AbyssOverlayRenderer (client) and ScreenOverlayPacket are internal. AbyssCore draws the overlays after the HUD, and you never call them yourself.

Clone this wiki locally