Repository navigation
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;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().
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).
AbyssScreenOverlay.bindDamageType(MyDamageTypes.CURSE,
AbyssOverlaySpec.tint(0x5A0080, 0.35f).fade(2, 15),
20); // shown for 20 ticksThis 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.
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>, soclear(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.
- Setup: depending on AbyssCore
- Sides, threads and lifecycle: read this first
- Permissions
- Networking
- Synced player data
- Corruption
- Damage
- Continuous effects
- Screen overlays
- Commands
- GUI toolkit
- GeckoLib
- Outside the API package: vanish and config queries
- Complete example: a mana mod
- Limitations, troubleshooting and changelog
- Quick reference