World Effects¶
Glowing shapes drawn in the world: particles that swell and fade, beams, flashes, trails and shapes of your own, rifts that tear open in the air, and blocks shown as ghosts. Package: net.ixdarklord.coolcatcanvas.api.client.vfx (client) and api.vfx (server).
Since
CoolCatLib 26.1.2-5 (Canvas 26.1.2-6 before the merge), on Minecraft 26.1 โ 26.1.2, and in 26.2 and 26.3; 2100.4.0.0 (1.21.1) and 2001.4.0.0 (1.20.1). On 1.20.1, shader materials use GLSL 150.
World effects are drawn after the whole level and before the player's hand, lit by nothing. They hide behind solid things and fade softly where they meet them, so a glow never ends in a hard line at a wall or the ground. Everything drawn with the same material in a frame goes out in one draw call.
| You want | Use |
|---|---|
| Sparks, embers, smoke that live on their own | Effect particles: a ParticleSpec, spawned with WorldParticles. |
| A beam or a flash, once | One-liners: WorldVfx.beam, flash, groundFlash. |
| Shapes that follow something every frame | A renderer: WorldVfx.register with a VfxRenderer. |
| An effect the server starts | Named effects: VfxEffects.register, then VfxControl.play. |
| A tear in the air | Rifts: WorldRifts, or RiftControl from the server. |
| Blocks shown as see-through ghosts | Ghost blocks: GhostBlocks.draw, or drawEffect with a shader. |
Materials¶
A VfxMaterial is what a shape is drawn with: a texture, a blend, and a softness.
VfxMaterial glow = VfxMaterial.additive(VfxMaterial.GLOW); // light: adds to the scene
VfxMaterial smoke = VfxMaterial.alpha(VfxMaterial.SMOKE); // painted over, can darken
VfxMaterial mine = VfxMaterial.luminous(MyMod.id("textures/vfx/flare.png")).withSoftness(0.3F);
| Blend | For |
|---|---|
VfxBlend.ADDITIVE |
Light, fire, magic. Overlaps brighten each other and black adds nothing. Washes out against a bright sky. |
VfxBlend.ALPHA |
Smoke and dust: painted over by alpha, so it can darken as well as lighten. |
VfxBlend.LUMINOUS |
Glow textures drawn on black with no alpha channel: painted over, with the alpha taken from each texel's brightness. |
softness is over how many blocks an effect fades out as it nears whatever is behind it (VfxMaterial.DEFAULT_SOFTNESS is 0.6; 0 is a hard edge).
Built-in textures, white with their brightness in alpha so they take any color and work with either blend: GLOW, SPARKLE, STAR, RING, SMOKE and STREAK.
Effect particles¶
A ParticleSpec describes a kind of particle once; WorldParticles spawns it as often as you like. Size, opacity and spin follow a Curve over each particle's life, so particles swell and fade instead of popping in and out.
static final ParticleSpec EMBER = ParticleSpec.builder(VfxMaterial.additive(VfxMaterial.GLOW))
.lifetime(20, 35) // each lives a random 20 to 35 ticks
.size(Curve.of(0.12F, 0.2F, 0.0F).easing(Easing.EXPO_OUT, Easing.SINE_IN))
.opacity(Curve.FADE) // quickly in, slowly out
.color(0xFFD27A, 0xFF4A1C) // shifts around the color wheel
.gravity(-0.004F) // negative: drifts up
.drag(0.94F)
.build();
WorldParticles.spawn(EMBER, x, y, z, 0.0, 0.05, 0.0);
WorldParticles.burst(EMBER, pos, 24, 0.2, 0.12); // 24 of them, flying apart
WorldParticles.line(EMBER, from, to, 30, 0.01); // strung along a line
| Builder call | What it sets |
|---|---|
shape(Shape.SPARK) |
A streak along the motion, longer the faster it moves (stretch(ticks) sets how many ticks of motion it covers). The default is BILLBOARD, always facing the camera. |
lifetime(ticks), lifetime(min, max) |
How long it lives. A range keeps a burst from vanishing all at once. |
size(Curve), opacity(Curve) |
Half its width in blocks, and its opacity, over its life. |
color(rgb), color(start, end), colorEasing |
Its color, or a shift that stays vivid instead of passing through grey. |
spin(Curve), randomRoll() |
Turning in radians a tick (either way, at random), and a random starting angle. |
gravity(f), drag(f) |
Blocks a tick it speeds up downwards, and what its speed is multiplied by each tick (0 to 1). |
A Curve has three points: it eases from start to middle over the first half of the life, and from middle to end over the second.
Curve.constant(0.25F) // always 0.25
Curve.of(0.0F, 1.0F) // grows, linearly
Curve.of(0.0F, 1.0F, 0.0F) // in, then out again
Curve.of(0.2F, 0.6F, 0.0F).easing(Easing.EXPO_OUT, Easing.SINE_IN) // bursts open, then drifts shut
Not vanilla particles
Effect particles aren't registered, don't exist on the server and ignore the Particles video setting. They are drawn after the whole world, so glows show through water and clouds. At most WorldParticles.MAX (16384) live at once, and they are dropped when the player leaves the world. Spawn them on the client thread.
One-liners¶
Shapes that appear, draw themselves and fade, with nothing to keep track of:
VfxMaterial glow = VfxMaterial.additive(VfxMaterial.GLOW);
WorldVfx.beam(VfxMaterial.additive(VfxMaterial.STREAK), from, to, 0.4F, 0xFF9AD8FF, 10); // narrows as it fades
WorldVfx.flash(glow, pos, Curve.of(0.2F, 1.5F), 0xFFFFC870, 8); // swells and fades
WorldVfx.groundFlash(VfxMaterial.additive(VfxMaterial.RING), pos, Curve.of(0.5F, 4.0F), 0xFF7AD8FF, 12); // a shockwave on the ground
Colors here are 0xAARRGGBB; sizes are half widths in blocks.
Draw every frame¶
For shapes that follow something (a tether between two entities, a glowing sword, a rune under a player), register a VfxRenderer. It's called every frame a world is drawn, until you unregister it; registering an id again replaces it.
WorldVfx.register(MyMod.id("tether"), frame -> {
Vec3 a = first.getPosition(frame.partialTick());
Vec3 b = second.getPosition(frame.partialTick());
frame.draw(VfxMaterial.additive(VfxMaterial.STREAK)).beam(a, b, 0.25F, 0xFFB070FF, 0xFF70D0FF);
});
WorldVfx.unregister(MyMod.id("tether"));
VfxFrame gives the level(), partialTick(), time() (seconds, stopped while the game is paused), cameraPosition(), and draw(material) (or draw(material, layer), see draw order), which returns a VfxDraw:
VfxDraw method |
Draws |
|---|---|
billboard(position, halfSize, argb) (or with x, y, z and a roll) |
A square facing the camera. |
beam(from, to, width, argb), beam(from, to, width, fromArgb, toArgb) |
A ribbon between two points, turned to the camera. |
flat(x, y, z, halfSize, yaw, argb) |
A square lying flat, facing up. |
quad(a, b, c, d, argb) |
A flat quad through four corners, seen from both sides. |
quad(a, b, c, d, u0, v0, u1, v1, argb) |
The same with UVs of your choosing, for shader materials. |
trail(trail, width, headArgb, tailArgb) |
The ribbon a Trail leaves. |
Nothing drawn lasts: draw again every frame.
Trails¶
A Trail remembers where something was over its last few ticks. Feed it a position every client tick and draw it every frame:
Trail trail = new Trail(12); // twelve ticks of movement
// every client tick
trail.add(bolt.position()); // or trail.shrink() once it stops, to let the tail catch up
// every frame, in a VfxRenderer
frame.draw(VfxMaterial.additive(VfxMaterial.STREAK)).trail(trail, Curve.of(0.3F, 0.0F), 0xFFFFE9A0, 0x00FF7A2A);
The width curve runs from the newest point to the oldest.
Draw order and layers¶
World effects write no depth of their own: wherever two overlap, the one drawn later covers the other, whichever is nearer. That's no trouble for additive effects, which look the same in any order, but painted-over ones (ALPHA, LUMINOUS) of different textures can cover each other the wrong way round: a far hand drawn over a near arm. Layers set the order:
VfxLayer CREATURE = VfxLayer.sorted(10); // its parts reach in front of each other
frame.draw(HAND, CREATURE).quad(...);
frame.draw(ARM, CREATURE).quad(...);
frame.draw(GLOW, VfxLayer.of(20)).billboard(...); // always over the creature
- Layers are drawn from the lowest
orderto the highest, so a higher layer always covers a lower one.draw(material)and every particle and one-liner useVfxLayer.DEFAULT, layer 0. - In each layer, painted-over shapes are drawn first and additive ones last.
- In a plain layer (
VfxLayer.of(n)), each material is drawn where it was first used in the frame, its shapes in the order you drew them. It's the cheapest, and right when one material never needs to cover another. - In a sorted layer (
VfxLayer.sorted(n)), the painted-over shapes of every material are drawn from the farthest from the camera to the nearest, each judged by its middle. It costs a sort of that layer's shapes each frame and a draw call wherever the texture changes along the way, so keep sorted layers to what needs them.
Since
Coming in 8.0.0, on every version. Before it, materials were drawn in no set order.
From the server¶
The server can't draw, but it can ask clients to play an effect they know by name. Register effects on the client, from a ClientModConstructor:
VfxEffects.register(MyMod.id("impact"), (level, params) -> {
WorldParticles.burst(EMBER, params.position(), Math.round(20 * params.scale()), 0.1, 0.15);
WorldVfx.flash(VfxMaterial.additive(VfxMaterial.GLOW), params.position(), Curve.of(0.2F, 1.2F), 0xFF000000 | params.color(), 6);
});
Then play them from the server:
VfxControl.play(level, MyMod.id("impact"), VfxParams.at(hit, 0xFF7A2A)); // everyone within 64 blocks
VfxControl.play(level, MyMod.id("bolt"), VfxParams.between(from, to, 0x9AD8FF), 128); // a range of your own
VfxControl.play(player, MyMod.id("impact"), VfxParams.at(hit).withScale(2.0F)); // one player
VfxParams carries a position, a target (where a beam ends, or a direction), a color (0xRRGGBB) and a scale; what they mean is up to the effect. One call is one small packet to each player in range, in place of the dozens a burst of vanilla particles takes. Clients without the effect ignore it, and players who can't receive it (no CoolCatLib, fake players) are skipped. VfxEffects.play(id, params) plays one on the local client alone.
Rifts¶
A rift is a tear in the air, drawn by a built-in shader and run through three acts: it opens (a flash, a jagged slit that widens, its opening sound, a shake of the camera nearby), stays open (its edge crawls, motes are drawn into it, its ambient sound loops) and closes (it narrows to a line and snaps shut with a last flash and its closing sound). It always turns to face whoever looks at it.
Rift rift = WorldRifts.open(RiftSpec.DEFAULT, pos); // stays until closed
rift.close();
WorldRifts.open(RiftSpec.DEFAULT, pos, 100); // closes by itself after five seconds open
A RiftSpec sets how it looks and sounds:
RiftSpec ember = RiftSpec.builder()
.size(3, 5) // width and height, in blocks
.color(0xFF7030) // edge and glow; the inside is a dark shade of it
.timing(30, 12) // ticks to open, ticks to close
.sounds(MySounds.TEAR, MySounds.HUM, MySounds.SNAP) // open, ambient (looped), close; any may be null
.particles(EMBER, 2.0F) // motes drawn in while open, per tick
.shake(1.5F) // camera shake nearby, in degrees
.build();
RiftSpec.DEFAULT is a violet rift two blocks wide and four tall with vanilla's portal sounds. Rift reports its phase() (OPENING, OPEN, CLOSING, GONE) and openness(partialTick); remove() drops it with no closing act, and WorldRifts.clear() drops them all.
From the server, open a rift the clients registered by name:
// client, in a ClientModConstructor
WorldRifts.register(MyMod.id("ember_rift"), ember);
// server
UUID id = RiftControl.open(level, MyMod.id("ember_rift"), pos); // stays...
RiftControl.close(level, id); // ...until closed
RiftControl.open(level, RiftControl.DEFAULT, pos, 100); // the default rift, closing by itself
Rifts aren't saved
A rift is not an entity: players who come into range (96 blocks) or log in after it opened don't see it. For one that must last, open it again for them, or attach it to something that already syncs.
Shader materials¶
VfxMaterial.withShader(id) draws a material with a fragment shader of your own instead of the textured one, for what a texture can't do: portals, heat haze, anything procedural. The id mymod:vfx/portal reads assets/mymod/shaders/vfx/portal.fsh.
#version 330
#moj_import <coolcatcanvas:vfx.glsl> // VfxTime.x (seconds), vfx_depth_fade(...)
uniform sampler2D Sampler0; // the material's texture
uniform sampler2D DepthSampler; // the scene's depth
in vec2 texCoord; // the quad's UVs, as given to VfxDraw
in vec4 vertexColor; // the color given to VfxDraw
out vec4 fragColor;
void main() {
float swirl = 0.5 + 0.5 * sin(length(texCoord - 0.5) * 30.0 - VfxTime.x * 4.0);
fragColor = vec4(vertexColor.rgb * swirl, vertexColor.a);
// Hide behind solid things, fading softly where they meet.
fragColor.a *= vfx_depth_fade(texelFetch(DepthSampler, ivec2(gl_FragCoord.xy), 0).r, gl_FragCoord.z);
}
A shader has no uniforms of its own: what changes from one shape to the next travels in the color and the UVs, which is why VfxDraw.quad takes any UV range. VfxMaterial.RIFT_SHADER is the shader rifts are drawn with.
Ghost blocks¶
GhostBlocks draws blocks as ghosts: their real models (block entities too, a chest as a chest), tinted and faded by one color. A group of ghosts is drawn as one picture, so only its outside shows, as the real blocks would, never the faces behind.
List<GhostBlocks.Placed> blocks = List.of(new GhostBlocks.Placed(pos, Blocks.CHEST.defaultBlockState()));
WorldVfx.register(MyMod.id("ghosts"), frame ->
GhostBlocks.draw(blocks, 0x80FFFFFF, GhostBlocks.Show.THROUGH_WALLS, GhostBlocks.Light.BRIGHT));
Call it from a renderer, or anywhere else right after the level is drawn, while its depth is still there. The color's alpha is the ghosts' opacity. Each call draws one group in one color.
Show |
Where the ghost shows |
|---|---|
THROUGH_WALLS |
Only where something is in front of it: seen through walls, not over the real block in plain sight. To find something. |
IN_WORLD |
Only where nothing is in front of it, as a real block would be. A ghost of what is to be built. |
ALWAYS |
Everywhere, over whatever is in front of it. |
OVER_BLOCK |
Over the real block where it stands, hidden only by what is in front of it. It covers exactly the block's faces, to fade one block into another. |
Light |
How it's lit |
|---|---|
BRIGHT |
Every face full bright, so it stands out. |
SHADED |
Each face shaded by its side, as an item is, at full brightness. |
WORLD |
As the world lights a real block there: each face shaded by its side, smooth lighting, and the block and sky light where it stands (dark in a cave, dimmer at dusk). A ghost over a real block matches its shading exactly. |
On 26.2, 26.3, 1.21.1 and 1.20.1, which don't have Light yet, pass true (shaded) or false (full bright) in its place.
World-lit ghosts keep their lighting from frame to frame, and build it again only when their block changes, or twice a second for changes in the light. Plants drawn off the middle of their block (flowers, grass) sit where the real ones are.
Several groups¶
draw(groups, argbs, show, light) draws several groups at once, each in its own color and opacity: a reveal fading in, wave by wave. It's the same as a draw for each group, but world-lit groups of solid blocks go over the world in one pass instead of one pass a group. A group with no opacity is skipped.
List<List<GhostBlocks.Placed>> waves = List.of(firstRing, secondRing, thirdRing);
int[] colors = new int[waves.size()]; // reuse it from frame to frame
// every frame, in a VfxRenderer
for (int i = 0; i < colors.length; i++) colors[i] = (int) (opacity(i) * 255) << 24 | 0xFFFFFF;
GhostBlocks.draw(waves, colors, GhostBlocks.Show.IN_WORLD, GhostBlocks.Light.WORLD);
With a shader¶
drawEffect(blocks, show, light, shader, texture, params) draws the ghosts' models and lays a fragment shader of your own over the world where they show, in place of a flat color: a force field running over the blocks, a scan, frost creeping across them. It works per pixel, so it follows the blocks' true shapes (a flower's petals, grass's blades) with no seams between them.
static final float[] PARAMS = new float[4]; // reuse it from frame to frame
WorldVfx.register(MyMod.id("shield"), frame -> {
PARAMS[0] = frame.time(); // seconds, for the shader to move by
GhostBlocks.drawEffect(blocks, GhostBlocks.Show.ALWAYS, GhostBlocks.Light.BRIGHT,
MyMod.id("core/force_field"), MyMod.id("textures/effect/hex.png"), PARAMS);
});
The id mymod:core/force_field reads assets/mymod/shaders/core/force_field.fsh. It imports coolcatcanvas:ghost_effect.glsl:
#version 330
#moj_import <coolcatcanvas:ghost_effect.glsl>
out vec4 fragColor;
void main() {
ivec2 pixel = ivec2(gl_FragCoord.xy);
float depth = ghost_depth(pixel); // -1 where no ghost shows
if (depth < 0.0) discard;
vec3 world = ghost_world_position(gl_FragCoord.xy, depth);
float wave = 0.5 + 0.5 * sin(world.y * 4.0 - GhostParams0.x * 3.0);
vec4 hex = texture(EffectSampler, world.xz + world.y);
fragColor = vec4(vec3(0.4, 0.8, 1.0) * hex.rgb, hex.a * wave * 0.7);
}
From ghost_effect.glsl |
What it gives |
|---|---|
ghost_depth(pixel) |
Where a ghost shows at a pixel, as show says, or -1. |
ghost_world_position(fragCoord, depth) |
That pixel's place in the world. |
ghost_color(pixel) |
The ghost's own color there. |
EffectSampler |
The texture you passed, repeating, with nearest-pixel filtering. |
GhostParams0 to GhostParams3 |
Your params, up to sixteen numbers, in order. |
The shader's output is blended over the world by its alpha.
After the game's models are reloaded, GhostBlocks.clearModels() forgets the block models made so far, so new ones are drawn.
Since
GhostBlocks: since 26.1.2-6 (and 26.2, 26.3), 2100.4.0.0 (1.21.1) and 2001.4.0.0 (1.20.1), with draw(blocks, argb, show, shaded), where shaded is SHADED and false is BRIGHT. Show.OVER_BLOCK: since 8.0.0 on 26.1.2, 26.2 and 26.3.
Light, draw(blocks, argb, show, light), draw(groups, argbs, show, light) and drawEffect: since 8.2.0, on every version (Show.OVER_BLOCK too, on 1.21.1 and 1.20.1). The include was coolcatlib:ghost_effect.glsl before 9.0.0; on 1.21.1 and 1.20.1 the shader is GLSL 150.