Blog · Release · v3.7.0 · September 26, 2026

Drawing the ocean as water, not as a surface

Spiralyst Lab 3.7.0 is out, and the 3D Flows category has a third member: an ocean wave. It draws the sea as water, not as a surface — every ocean renderer we found draws a surface. This release also makes its pulse rings far bigger without letting them lie, and hands your agent the stage: fullscreen, the controls in or out of the shot, the look saved as a preset.

Open any ocean in a game or a film and you are looking at a surface: a sheet, bent into waves, lit to look like water. It works. It is also a picture of the top of the sea and nothing else. We wanted to draw the water itself — every drop, where it is, where it is going — and it turns out that for one particular wave, mathematics wrote that down more than two hundred years ago.

The one exact wave

Ocean waves obey the same equations as every other fluid, with one cruel extra: the top of the water is free to move, so the shape of the thing you are solving for is part of the answer. A standard coastal-engineering text says it flatly: an analytical solution to the problem is impossible. Every wave theory engineers use is a way of giving something up.

And yet there is one exact answer. In 1802 a Prague engineer named Franz Gerstner wrote down a wave that satisfies the full frictionless equations, free surface and all, with nothing assumed small. He did it by describing not the surface but the water: label every drop by where it rests, and his formula says where that drop is at every moment. Each drop goes round a circle. The circles shrink with depth — half a wavelength down they are a twentieth the size — and the surface they add up to has sharp crests and long, flat troughs. It was forgotten for sixty years and rediscovered three times. More than two centuries on, it is still the textbook exact solution for gravity waves on deep water.

That formula is a formula for a particle. Spiralyst Lab draws particles. So the first scene of the new type is Gerstner's wave, drawn as tens of thousands of drops each riding its own circle, and it is labelled exact in the app because it is.

Set the trail length to the wave's period and every trail becomes one complete orbit.

There is an honest catch, and the app says it out loud. Gerstner's water spins, and a sea raised by wind from calm does not. Real waves are closer to the theory George Stokes built in 1847, in which every drop creeps forward a little each cycle. The two are related in the neatest possible way: to second order, a Stokes wave is a Gerstner wave plus that drift. There is a switch for it. Turn it on and the closed circles open into forward-looping curls.

Swell outruns chop, because it has to

The second scene is an open sea: a long swell, a shorter wind sea and a fine chop, added together. Here the equations insist on something you have seen at every beach without knowing it: a wave's speed depends on its length. A ten-second swell travels at nearly sixteen metres a second; a two-second chop at three. That is why swell arrives before the storm that made it.

It is also what lets music in honestly. The equations fix how each wavelength moves and say nothing about how much of each there is. So the heights are yours and the motion is the water's. Bind the swell's height to the bass and the chop's to the hi-hats, and the bass-driven waves visibly outrun the hat-driven ones. Nothing is animated to make that happen. It is dispersion.

A wind speed control hands the wind sea over to the Pierson–Moskowitz spectrum, the 1964 description of a fully grown sea, and covers it in whitecaps at the fraction Monahan measured for that wind. Add several trains and the scene stops calling itself exact — adding solutions works for linear problems, and this one is not — but it prints the size of the approximation live in the info bar, which we think is better than a bare disclaimer.

The beach

The third scene is the one everybody pictures when they hear the word "wave." The swell comes in over a shelf, the bottom rises, and because the energy it carries has to go somewhere the wave slows and grows. It grows until it reaches a limit — about a seventh of its length in deep water, less as the water shoals — and breaks.

How it breaks is decided by a single number combining the beach's slope and the wave's steepness. Below about a half the wave spills, foam sliding down its face; above about three it surges up the sand without ever quite breaking; in between it plunges, throwing a lip over an air tube. Those thresholds were measured in wave flumes in the 1960s and 70s, and the info bar names the breaker as you move the slope.

When it plunges, the tube has a shape. In 1982 Michael Longuet-Higgins found a curve that satisfies the equations of motion for the underside of an overturning wave — a particular teardrop about 2.76 times as long as it is wide. In 2021 researchers scanned thirty breaking waves on a North Carolina beach with lidar and measured 2.55. That curve is what the drops in this scene ride. Turn the swell a little off the shore and the break runs along the crest: a peeling wave.

Everything up to the break is solved from published equations and measurements. How the water gets from the unbroken wave onto that curve, and everything the foam does afterwards, is a sketch, and it is labelled as one.

Made for music

Every control in the scene is a real quantity, in metres and seconds, and every one of them can be bound to a band of your music. But the honest controls are heights in metres, and a band picker alone does not tell you how far to swing them. So the wave has a 🎵 React to music button: one click binds the scene's best set — which control, which band, and the range the music is allowed to move it through. The heights lead every set. Then press ✨ Auto-Reactivity with the track playing and each of those bands is tuned to the song you are actually playing.

Then there are the controls that exist to be driven:

• Pulse ring — a kick throws a ring wave outward across the sea. It is a real wave: it obeys the dispersion relation, its energy travels outward at the group velocity, so the crests are born at the back of the ring and die at the front. What is yours is the striking — and where: the ring's source can be moved anywhere on the sea, and an optional fade lets rings die away with distance (labelled as the drawing effect it is).
• Crest sharpen, Jitter, Spray kick, Surface shear — a steeper sea, a crackling skin, drops thrown clear of the crests, the surface dragged along by an unseen wind. Each one is labelled for what it is: a drawing effect, not the fluid.
• Reaction smoothing — how quickly the sea follows the music, so a bass line breathes the swell instead of snapping it.

Rings up to twenty metres, still honest

We wanted big rings, so the Pulse ring now reaches twenty metres (the 🎵 sets swing it up to seven metres in the deep-water scene and eight on the open sea). Making the slider bigger was the easy part. The hard part is that a real wave can only be so steep: throw a tall ring at a short period and the water at the source would have to fold over itself.

So the period you set is now a floor. A tall ring is thrown at the shortest period that keeps it from folding — about 4¼ seconds for an 8-metre ring, 5¼ for 12 metres, 6¾ for 20 — which also makes it longer and faster, just as a real ring from a bigger splash would be. And the truth labels say so: a ring thrown at your period and within the limit is marked exact to first order; a stretched ring is marked illustrative; a ring that would still break the limit at the source is marked exaggerated. The live readout shows the period you asked for next to the one being used.

One ring shape for a whole song

When the music drives the rings, the ring's period now comes from the top of the range the music is allowed to reach, so it is set once and holds for the whole song. An earlier build followed the loudest recent hit instead, which quietly re-shaped every ring already in flight whenever the song got louder. It looked jerky, and it was: the pulses changed mid-beat. Drag the slider by hand and the period still follows the height you've set, with a little patience so it doesn't flicker.

Viscosity, four ways

The same release brings a little "viscosity" to all three flow scenes, and each version means something specific:

• Particle inertia (vortex, waterfall, wave) — the drawn drops are heavy. A heavy speck in a fluid lags it, and on a circular orbit traces a smaller circle behind the water's, by the amount Stokes' drag law predicts. The flow is untouched; the tracers alone are slow. Sea turns to syrup; the vortex's spirals smear into ribbons.
• Diffusion (all three) — every drop wanders a little and drifts back, the way dye spreads while it is carried, about a million times faster than real water would allow.
• Wave damping (wave) — real viscous decay. Because it goes as the square of the wavenumber, turn it up and the chop fades within metres while the swell rolls on. At water's real viscosity the effect is invisible, which is why the slider runs on a log scale and tells you when it has left reality.
• Eddy viscosity (waterfall) — how quickly water that has landed forgets the momentum it arrived with. Up for a lazy, well-mixed pool; down for a sharper jump.

Hand your agent the stage

Spiralyst Lab has always been scriptable: every control has a programmatic twin on a local API, so an AI agent, a controller bridge or a plain shell script can drive what you would drive by hand. Earlier versions let an agent build a scene. 3.7.0 lets it run one.

• Presentation mode. Put the art fullscreen and take it back out. Keep the control panel hidden for the room, or pin it on screen while fullscreen for a tutorial that shows the sliders moving with the music. A script can read back which layout is live before it starts recording.
• Save presets. When an agent lands on a look you like, it saves it to your own preset library by name, just as the Save button does, ready for you to load at the gig.
• 3D Flows over the API. Read a flow's live numbers and its truth labels — wave heights, wavelength and speed, where the beach breaks and how, the ring's requested and used period — restart it, and switch the ocean wave's 🎵 React to music set on or off.
• Video export over the API. Record the canvas straight to MP4, MOV or WebM, at the resolution and frame rate the script chooses, with no dialogs. Like every export it is video-only; add your soundtrack afterwards.

It is the same local API as before: it answers on your own Mac and nowhere else, it needs a secret token that changes every launch, and nothing goes to any cloud. Presentation mode, presets and the flow controls work in the trial for the types the trial includes; exports need a licence, like the Export tab.

We used all of this ourselves. How we made our demo videos, and how yours can be made the same way, is its own post: How we made our demo videos.

Fixes you'll notice

• A still preset stays still. Loading a preset with a still camera over a session whose camera was slowly orbiting used to leave the orbit running underneath. An animation switched off in a preset now really stops.
• The "tuning to the music" notice is off the artwork. While Auto-Reactivity tunes your bands it shows a notice; it now sits at the top of the control panel, like the quality notice, instead of over the art your audience is watching. With the panel in its own window, the notice goes with it.
• React to music drives the wave's own controls. The 🎵 set now binds the wave's Jitter rather than a similarly named global effect, and Surface shear is no longer in the open-sea set, where it slid the whole upper sea back and forth. It is still a slider when you want it.

Small things that matter

• Pan. Every 3D scene can now be slid as well as orbited: shift-drag, middle-drag or right-drag, or shift and scroll, plus Pan sliders on the Camera tab. Frame the barrel off-centre and leave it there.
• Particle count sits at the top of the wave's controls, where it belongs.
• Math Mode covers the wave with the live formula tile, the info card and a plain-English guide to all thirty controls, and reads itself aloud in four sections like every other type.

Learning out loud

We checked this scene the way we checked the vortex and the waterfall: against published numbers before writing a line of scene code. The wave math reproduces the worked examples in the US Army Corps of Engineers' Coastal Engineering Manual to under one percent. The number of broken waves the beach puts in its surf zone at once lands where Battjes' 1974 paper says it should, though nothing was fitted to it. And Gerstner's wave was checked numerically to be what the textbooks say it is: exact.

Things we got wrong at the start and fixed: the swash never drained from the beach; the air tube was full of water; a change in swell height travelled across the sea at the group velocity — physically true, and it made the slider look broken (it now moves the whole sea at once by default, and the arriving behaviour is a slider you can turn up when you want to watch a set roll in); and a tall pulse ring was labelled exact while its water folded over at the source. That last one is why big rings now stretch their period and change their label.

How to get it

Already a customer? 3.7.0 is included in your annual licence: download it from the download page and replace your copy.

New here? The Navier–Stokes vortex remains in the free trial; the waterfall and the ocean wave are part of the licence — a year of everything is $24.99.

Get Spiralyst Lab — $24.99/yr ← All posts