Screen Effects

Overview

Citrine provides client-side screen effects for (usually) impact effects. These include screen flashes and screen shake.

Packages:

• org.carpentry.citrine.api.client.flash
• org.carpentry.citrine.api.client.shake

Screen Flash

The screen flash overlays the player's HUD with either a solid color or a texture, fades according to the passed EasingType.

ScreenFlash

ScreenFlash is a record containing the data for an individual screen flash.

public record ScreenFlash(
    float ticks,
    float startTime,
    Color color,
    Identifier img,
    EasingType type
) {}

Field	Description
ticks	Duration of the flash, in ticks.
startTime	World time at which the flash started.
color	Color used for the overlay.
img	Texture used for the overlay.
type	Easing function controlling the fade.

A flash uses either color or img, depending on the selected method.

ScreenFlashManager

ScreenFlashManager manages screen flashes on the client.

addFlash()

Adds a color or texture-based flash.

ScreenFlashManager.addFlash(
    20,
    Color.WHITE,
    EasingType.QUAD
);

For a texture-based flash:

ScreenFlashManager.addFlash(
    20,
    new Identifier("example", "textures/gui/flash.png"),
    EasingType.QUAD
);

Both methods accept:

Parameter	Description
ticks	Duration of the flash.
color / img	Color or texture to display.
type	Easing function used for the fade.

Other methods

Method	Description
getActiveFlashes()	Returns the list of active flashes.
removeFlash(ScreenFlash)	Removes a specific flash.
clearExpired(float currentTime)	Removes flashes whose duration has elapsed.

Networked Screen Flash

NetworkedScreenFlashManager allows the server to trigger screen flashes for a list of players.

sendFlash()

There are two methods for sending flashes.

Color-based flash:

NetworkedScreenFlashManager.sendFlash(
    player,
    20,
    Color.WHITE,
    EasingType.QUAD
);

Texture-based flash:

NetworkedScreenFlashManager.sendFlash(
    player,
    20,
    new Identifier("example", "textures/gui/flash.png"),
    EasingType.QUAD
);

Both methods accept a ServerPlayerEntity, duration, and easing type, with either a Color or an Identifier.

Multiple players

The manager also supports sending flashes to collections of players:

NetworkedScreenFlashManager.sendFlash(
    world.getPlayers(),
    20,
    Color.RED,
    EasingType.QUAD
);

Players that are not ServerPlayerEntity instances are skipped.

Screen Shake

The screen shake system offsets the player's camera in a random motion to create an impact effect.

Unlike screen flashes, screen shake is represented by individual ScreenShakeInstance objects managed by ScreenShakeManager.

ScreenShakeInstance

Each ScreenShakeInstance represents one active screen shake.

new ScreenShakeInstance(
    EasingType.QUAD,
    5.0f,
    20
);

Parameter	Description
easing	Easing function controlling how the shake loses intensity.
intensity	Initial shake strength.
durationTicks	Duration of the shake in ticks.

The duration cannot be 0 or less.

getStrength(float tickDelta)

Returns the current shake strength.

The strength starts at the configured intensity and decreases to zero according to the passed easing function.

ScreenShakeManager

ScreenShakeManager manages all screen shake instances.

add()

Adds a new shake instance:

ScreenShakeManager.add(
    new ScreenShakeInstance(
        EasingType.QUAD,
        5.0f,
        20
    )
);

getStrength(float tickDelta)

Returns the combined strength of all active shake instances.

The total is capped at MAX_STRENGTH, currently 15.0f, to prevent stacked effects from producing excessive camera movement.

noiseX(float tickDelta) and noiseY(float tickDelta)

Return the horizontal and vertical offset values.

clear()

Removes all active shake instances.

Networked Screen Shake

NetworkedScreenShake provides a server-side method for triggering screen shake on a specific player.

shake()

NetworkedScreenShake.shake(
    player,
    EasingType.QUAD,
    5.0f,
    20
);

Parameter	Description
player	Player receiving the effect.
easing	Easing function controlling the shake's decay.
intensity	Initial shake strength.
ticks	Duration of the shake, in ticks.

Example: Combining Screen Effects

// Server-side
NetworkedScreenFlashManager.sendFlash(
    player,
    10,
    Color.RED,
    EasingType.QUAD
);

NetworkedScreenShake.shake(
    player,
    EasingType.QUAD,
    6.0f,
    15
);