name: water-crystal-skill-vfx description: Build the effects of a water and crystal skill as one visual language in Three.js. Water that reads as clear water, never a teal fill or a textured ball. A ray-marched water orb whose surface swells, rings and deforms in place: it refracts the frame behind it with an inverted horizon, has a silver rim and sharp highlights, and shows a faint caustic web on its far wall. Streams wound up from tide pools as uneven beaded ropes with silver edges, drips and shed drops. A lash that unspools from the orb, whips and pours into a pool under a torn, lopsided splash crown of aerated white water with spikes breaking into drops. Analytic ripple rings and rain on the pools. Crystals traced against their own half-space planes (Snell, Fresnel, total internal reflection, exit dispersion, Beer–Lambert, fracture discs, a white-hot root glow and a resonance band that climbs the stone), growing out of the water in a draining veil, then shattering into Voronoi shards that fall, tumble and rest with real contact on a heightfield. Caustics on the pool floor, and a moonlit tidal rock flat: rock banks traced from target images onto a world grid, flat mirror pools, a moon-glitter column of micro-facet glints, and a moon disc with maria. Use for water or ice-crystal skills, water orbs or bubbles, water whips, jets or tentacles, splash impacts, tide pools, rain, crystal growth or eruption, crystal resonance, shattering glass or quartz, caustics, wet-stone night scenes, moon reflections on water, "water and crystal", "hydro", "clear water VFX", "crystal shatter" or "skill effects only". Includes a reusable module and a five-beat demo on a scanned CC0 low-tide floor with failure-mode switches.

Water and Crystal Skill VFX

Use this for the effect half of a water skill: what gathers above the hand, what it throws, what grows where it lands and what breaks. Reach for a sibling instead in these cases:

• Lightning, an energy orb, black afterimage smoke and air bursts: lightning-energy-skill-vfx. This skill reuses its clock, composite, impact frames and flash limiter.
• Fire, smoke, embers and heat haze: fire-smoke-skill-vfx.
• Readable, budgeted gameplay effects in general (telegraphs, status, cleanup rules): create-game-vfx. Its readability rules still apply here.
• Scoring a skill out of 10, or polishing the caster's body and timing: game-dev-combat-skill-polish.

Source: a brief for elemental skill pages built to the Black Lightning demo's bar, with the notes the user gave on that demo ("not as in-your-face", "more fine lines", "smooth transitions", "a more realistic floor", "no sliding textures", "more detail in the frames"). There is no character: water gathers over an implied open palm. After its self-critique rounds and a review round, the page went through three rounds of a dream loop against GPT Image edits of its own frames (see references/scorecard.md).

Verified stack: Three.js r170, WebGL2, GLSL ShaderMaterials, HalfFloat render targets, a 96³ baked noise texture, and a hand-written bloom, glint and composite chain. No post-processing library. The demo's floor is Poly Haven's Low Tide Rocks by Dimitrios Savva (CC0). Its 1k colour, normal and ARM maps are in demo/assets/ground/, re-encoded at quality 85 and embedded by demo/build.mjs as data URIs, so the page opens from disk.

The mechanism

Water is what it bends and what it mirrors; crystal is light caught between planes.

• Clear water has no colour of its own. Every water surface (orb, streams, splash) refracts a copy of the frame drawn behind it, reflects the night and the lights with Fresnel, and is tinted only by its path length (Beer–Lambert). Its look comes from silver rims, a dark edge on the unlit side and sharp highlights of small bright sources, which are never scaled down by the 2% reflectance.
• Surfaces evolve in place. The orb is a sphere-traced field: its free-drop oscillation modes ride on springs, capillary rings run over it, and a warp field drifts through its noise. Nothing turns rigidly or scrolls (the Sliding texture switch shows that failure). Streams carry ripples that move with the flow.
• Crystals are their own planes. Each crystal is a convex hull clipped from half-spaces. The fragment shader traces the ray inside against those same planes in closed form, so back facets, total internal reflection and edges show inside the stone (the Painted glass switch shows a tinted body with only a reflection).
• The ground is a place, not a texture. A heightfield of wet rock banks stands out of one flat water plane at y = 0. Where the rock is below the plane, it is the pool floor seen through water. A half-resolution mirror pass (an oblique-clipped reflected camera) puts the rock, the orb, the streams, the crystals and the drops into the pools, and the moon arrives as a glitter column of micro-facet glints. The same terrain runs on the CPU, so shards and drops land on the surface that is drawn.
• One clock and one composite, as in lightning-energy-skill-vfx: holds freeze every layer at once, refraction-only pressure fronts write into one half-resolution distortion buffer, and the impact frame draws after tone mapping. Here the vignette sits before the tone curve, so highlights still clip.

Reuse the working effect

Copy assets/tide-crystal.mjs. You pass in your own THREE, and the module does not import a second copy. The demo runs this same module, inlined by demo/build.mjs because a page opened from disk cannot import modules.

import { createTideCrystal, ENV_GLSL, LIGHTS_GLSL, RIPPLE_GLSL, CAUSTIC_GLSL, TNOISE_GLSL, NOISE_GLSL, L_MIRROR } from './tide-crystal.mjs';

const fx = createTideCrystal(THREE, { renderer, scene, camera, seed: 23, moonDir });   // bakes the 96³ noise texture
fx.setSize(width * dpr, height * dpr, dpr);       // drawing-buffer pixels, again on resize
fx.warmup();                                      // compile every effect before the first cast
fx.options.shake = 0.6; fx.options.fisheye = 0.65;   // felt, not thrown at the viewer
fx.groundAt = (x, z) => myTerrainHeight(x, z);    // shards and drops land on your ground (default: y = 0)

// The orb: grow it, ring it when water joins it, kick its drop modes.
const orb = fx.createOrb({ radius: 0.02 });
orb.position.copy(overThePalm); orb.radius = 0.25; orb.glow = 1;
orb.ring(dirOnTheSphere, 0.05, 2.4, 0.2);         // a capillary ring from where a stream arrives
orb.kick(1, 0.03);                                // excite one oscillation mode

// A stream: rebuild its centreline every frame (points + radius per point); the module tubes it.
const stream = fx.createTube({ maxPoints: 64, radial: 14, flow: 3.2, foam: 1.1, glow: 0.7 });
stream.points = arcPoints; stream.radii = arcRadii; stream.visible = true;

// Crystals rise out of the pool floor, glow, crack and shatter.
const C = fx.createCrystal({ base, axis, length: 0.9, radius: 0.1, seed: 7, pieces: 7, groundY: floorY });
C.visible = true; C.grow = 0.6; C.glow = 0.4; C.band = 0.5;   // set every frame from your beat
fx.shatter(C, { center: clusterCentre, strength: 1.2, up: 1.2 });

// Your ground and pools: add NOISE_GLSL, TNOISE_GLSL, ENV_GLSL, LIGHTS_GLSL and RIPPLE_GLSL (and
// CAUSTIC_GLSL for the pool floor), spread fx.envUniforms, fx.lightUniforms, fx.groundUniforms and
// fx.mirrorUniforms into their uniforms. Use ripples(p) + rainRipples(p) for the water's slope,
// sample tMirror through uMirrorMat for the reflection, skyBase/skyClouds for the sky in it, and
// energySplit(...) for the effect's light. Put a copy of your ground on layer L_MIRROR so it reflects.

function frame(realDt) {
  const dt = fx.update(realDt);                   // sim seconds: 0 during a hold, scaled by ramps
  // drive the orb, streams and crystals with dt, then:
  fx.render();                                    // mirror, world, frame copies, solids, water, drops, haze, bloom, composite
}

// A splash:
fx.crown(splashPoint, { radius: 0.16, height: 0.3, life: 0.8 });
fx.spray(splashPoint, { count: 160, dir: UP, spread: 0.9, speed: [1.2, 3.6], size: [0.002, 0.0065], life: [1, 2] });
fx.ripple(splashPoint, { slope: 0.42, speed: 0.55, wavelength: 0.06, decay: 0.75, width: 0.05, life: 3.6 });
fx.addFoam(splashPoint, 0.7, 3.2);
fx.impact({ hold: 0.05, frame: 'none', shake: 0.007, at: splashPoint });

Other calls:

• fx.createOrb({ radius }) returns an orb you change every frame: position, radius, glow, visible, settle (0–1: calmer, more damped), neck { dir, len, r } (a capsule smooth-unioned onto the orb where a stream leaves it), ring(dir, amp, speed, width), kick(mode, v) and currentRadius.
• fx.createTube({ maxPoints, radial, flow, foam, glow }) returns a tube: points (Vector3s), radii, fades, along0 (where the ripples sit on the water, so they ride with it), visible, flow, opacity, glow and wobble.
• fx.createCrystal({ base, axis, length, radius, seed, tint, pieces, spin, groundY }) returns a crystal: visible, grow (0–1, rising out of the floor), glow, band (the resonance band's height, −1 for none), veil and veilT (the water film and its draining line), crack (0–1, fractures climbing from the root), frost and shattered. Its shards come pre-cut (C.pieces).
• fx.shatter(C, { center, strength, up }) hands the crystal to its shards (rigid bodies with contact).
• fx.crown(pos, { radius, height, life, droplets }), fx.drop(pos, vel, { life, size, drag, gravity, ripple, kind }) and fx.spray(pos, { count, dir, spread, speed, size, life, ripple, up }).
• fx.ripple(pos, { slope, speed, wavelength, decay, width, life, delay, small }) (slots 0–11 are for hero rings; small: true uses 12–23, so drops never steal a splash's ring), fx.groundUniforms.uRain.value (0–1).
• fx.caus[i] (x, z, radius, gain) and fx.causCol[i] (r, g, b, dispersion) for six caustic spots, fx.addFrost(pos, radius, { grow, life }), fx.addFoam(pos, radius, life), fx.wet[i].
• fx.setLight(slot, pos, energy, color) (held, eased), fx.flashLight(slot, pos, energy, decay, color) (decays), fx.front(center, normal, { radius, thick, life, amp, delay }) (refraction only).
• fx.vortexField { on, center, swirl, pull, lift, radius } winds drops of kind: 1 round a centre and swallows them.
• fx.impact({ hold, frame: 'center' | 'full' | 'none', flash, shake, shakeMode, fisheye, at }), fx.ramp(scale, seconds), fx.repeat(ticks, fn), fx.stats(), fx.dropList() (the live drops, for debugging), fx.debug (noMirror, noGrab2, noRip, noCaus).
• fx.options: water ('living' | 'sliding'), crystal ('traced' | 'flat'), flashes ('full' | 'safe'), shake, fisheye. fx.grabTwice = true takes a second frame copy after the crystals when water overlaps them on screen.
• Layers: 0 the world, 1 distortion, 2 seen in the mirror (L_MIRROR), 3 refracting solids, 4 water bodies, 5 drops.

The layers, with the numbers that shipped

| layer | numbers | | --- | --- | | Orb | A back-faced icosphere bound (1.18 radii, 1.42 + the neck's length with a neck) around a sphere-traced field: radius 1 + three P2 modes and a P3 mode on springs (ω 7.2 / 8.1 / 6.6 / 11.3 rad/s, damping 0.16 + 0.25 × settle), a warped noise drifting through at (0.11, −0.07, 0.05)/s with amplitude 4.2% (halved as it settles), a fine octave at 0.5% (surface tension keeps the outline smooth), and up to 4 capillary rings as a derivative of a Gaussian over the arc (amp e^(−1.6t), width × (1 + 0.8t)). Capillary detail at 13.3/radius lives only in the normal (0.045). 26 sphere-trace steps on the coarse field plus 2 refinements on the full one; analytic coverage at the silhouette from the ray's closest approach. Refraction IOR 1.333 through the real