// undine docs
Fluid
Undine aims to reproduce liquid motion that feels physically plausible rather than relying solely on artistic approximations.
The Sim Params tab exposes both artist-facing presets and technical controls for material response, particle distribution, and density behavior.
Material presets
The top of the Sim Params tab exposes quick material families such as Water, Oil, Honey, Chocolate, and Slime.
These presets are starting points. They set groups of simulation values at once so the user can begin from a coherent material behavior instead of tuning every control manually.
| Preset family | Typical intent | Tuning direction |
|---|---|---|
| Water | Low-viscosity, responsive liquid behavior. | Use as the default baseline for most clean fluid tests. |
| Oil | Heavier and smoother motion than water. | Increase damping or viscosity-related controls if motion should feel thicker. |
| Honey | Slow, cohesive, high-viscosity behavior. | Expect to trade speed for stability and use more conservative time stepping. |
| Chocolate | Dense viscous material with a heavier visual feel. | Tune surface, viscosity, density response, and surfacing for the shot scale; do not assume viscoelastic memory unless an advanced branch is enabled. |
| Slime | Highly cohesive or stylized material behavior. | Use restraint with surface and vorticity settings to avoid over-energized motion. |
| THICK_EXACT | Opt-in numerical foundation for dense materials. | Enables the exact strain-rate viscosity route; it is not material memory or a complete chocolate/frosting model by itself. |
| Chocolate Memory (Experimental) | Hold-shape chocolate with viscoelastic memory. | Turns on memory + Herschel-Bulkley + yield (350 Pa, 0.35 s, polymer ratio 0.50). CPU-only reference; reversible. See the Viscosity chapter. |
| Toothpaste Memory (Experimental) | Crest-holding paste with viscoelastic memory. | Turns on memory + Herschel-Bulkley + yield (900 Pa, 0.55 s, polymer ratio 0.65). CPU-only reference; reversible. See the Viscosity chapter. |
Preset library and custom presets
The Preset Library section applies built-in or custom presets to the current scene.
Built-in presets are locked, so they act as stable reference points. Custom presets can be saved, updated, or deleted depending on the selected preset state.
| Control | Purpose | Notes |
|---|---|---|
| Presets | Chooses a preset from the library. | The screenshots show Water selected. |
| Apply Selected | Applies the selected preset to the visible Sim Params values. | Use this after choosing a preset from the dropdown. |
| Name | Names a custom preset. | Use a clear shot or material name. |
| Save New | Creates a new custom preset from current values. | Useful after tuning a reusable material. |
| Update Selected | Writes current values back into the selected custom preset. | Disabled for locked built-in presets. |
| Delete Selected | Removes the selected custom preset. | Disabled for locked built-in presets. |
Forces
Forces shape the global motion of the liquid before more specialized material effects are considered.
| Control | Purpose | Practical effect |
|---|---|---|
| Gravity Z | Controls vertical gravitational acceleration. | The visible default is 9.81, matching a common real-world gravity scale. |
| Drag | Adds global velocity damping. | Raise when the entire simulation should lose energy faster. |
| Weight Scale | Scales how strongly weight-like effects influence the liquid. | Useful for art direction when the scene scale or visual weight needs adjustment. |
Physically coherent liquid behavior
Parameters such as viscosity, surface tension, and pressure response are implemented with physically motivated models whenever possible.
The goal is not only visual appeal, but liquid motion that remains believable across a range of use cases.
Viscosity and rheology
The visible Numerics panel includes viscosity controls, a Rheology section, and an opt-in Viscoelastic Memory panel. Disabled viscosity, rheology, or memory settings are preserved but bypassed, so a material setup can stay ready without paying for those effects until enabled.
Viscosity is organized as four cooperating layers — solver quality, rheology model, viscoelastic memory, and collider contact. The table below is the quick map; the Viscosity chapter is the full reference.
| Control | Purpose | Notes |
|---|---|---|
| Viscosity | Controls internal resistance to flow. | Higher values make the fluid move more slowly and resist deformation. |
| Friction | Adds resistance related to contact or material motion. | Useful for thicker fluids or contact-heavy shots. |
| Quality preset (Simple) | Picks the speed/quality bias: Fast, Balanced, PRO Lite, or Thick Exact. | Balanced is the default. PRO Lite is a weighted approximation; Thick Exact selects the exact strain-rate route for final bakes — it is numerical, not memory. |
| Viscosity Mode (Advanced) | Chooses the backend directly. | Off / Legacy / Implicit / PRO Lite Weighted (variational) / PRO Exact Host (pro_strain_rate). PRO Exact is CPU/host only. |
| Rheology model | Newtonian, Bingham, or Herschel-Bulkley material response. | Adds yield-stress (hold-shape) and shear-thinning/thickening. Disabled rheology is preserved but bypassed. |
| Viscoelastic Memory (Experimental) | Opt-in Maxwell/Oldroyd-B memory with yield↔elastic hold-shape. | OFF by default and CPU-only. With memory off, the job is byte-identical to the classic path. |
Advanced viscosity and dense materials
Undine includes an advanced path for materials that do not behave like water: thick honey, chocolate, toothpaste, frosting, creams, and paste-like masses that tend to retain ridges, ribbons, strands, and folds longer than a simple liquid.
Two layers sit on top of the solver here: a rheology model (Newtonian / Bingham / Herschel-Bulkley) for yield-stress and shear-thinning, and an opt-in viscoelastic memory (VISC-PRO) for real hold-shape. The path is designed with numerical safety above visual aggression. New routes are opt-in, disableable, diagnosable, and should not alter old scenes when the advanced material branch is off.
Exact viscous foundation
pro_strain_rate is the advanced exact-viscosity backend exported as numerics.viscosity_mode = "pro_strain_rate" when that route is selected.
THICK_EXACT configures this robust viscous foundation for dense materials. It is a numerical preset, not a memory model by itself.
Minimal viscoelastic memory
Material memory is implemented as a CPU-first branch with its own constitutive state. The extra tensor is stored as a six-component SoA side state in ViscoelasticState instead of invading Core, Grid, or Field.
The initial model is a regularized Maxwell/Oldroyd-B style route with tensor transport, CPU strain-rate evaluation, stress divergence, explicit coupling, and rollback if non-finite values or validation failures appear.
Paste forces and solid contact
PasteForcesStage can add opt-in cohesion, adhesion to solid SDFs, and simplified wetting/contact-angle behavior in controlled free-surface or wall bands.
These forces are clamped by delta-v per substep and monitored with specific metrics. They help continuity near ribbons, extrusions, nozzles, walls, and ridges; they do not invent detail that particles or SDF surfacing have already erased.
CPU/GPU routing
The advanced dense-material route starts as CPU/host reference. If a GPU-resident run has no equivalent kernel for an enabled advanced force, the route must block or degrade before pressure rather than applying the force late.
GPU support for ProStrainRate, paste forces, or viscoelastic memory is treated as unsupported or experimental until parity and stability tests pass. It is not enabled by default.
Supported behavior range
Undine is intended to simulate a wide range of liquid behavior, from low-viscosity fluids such as water to highly viscous materials like syrup, oil, chocolate, slime, toothpaste, frosting, and dense cream. Advanced dense-material behavior should be read as CPU-first and opt-in unless the current build explicitly reports a validated GPU route.
Why this matters
A broad behavior range makes the fluid chapter a bridge between artistic direction and solver design.
Particle distribution and reseeding
Particle Distribution controls how Undine maintains particle coverage. The Conservative distribution mode is designed to preserve mass-aware behavior while reducing visual gaps and clustering.
In the visible panel this section can be disabled, but its settings still document how reseeding will behave when enabled.
| Control group | Visible controls | Purpose |
|---|---|---|
| General | Mode, Particles Per Cell | Sets the target distribution strategy and baseline particle density. |
| Reseeding | Reseed Strength, Birth Threshold, Death Threshold | Controls how aggressively particles are added or removed to maintain coverage. |
| Particle count limits | Min PPC, Max PPC | Bounds the number of particles per cell. |
| Separation override | PR Override: Iters, Radius, Rate | Overrides separation behavior for particle redistribution when needed. |
| Contact Enhancement | Contact Band Cells, Contact Oversampling, Contact Min PPC, Contact Mass Bias, Contact No Reseed Cells | Adds refill behavior near colliders when contact bands are enabled. |
Adaptive PPV and advanced particle controls
Adaptive PPV adjusts particle-per-voxel behavior over time. It is useful when particle density needs to react gradually instead of jumping between states.
The advanced particle controls are best treated as stability and diagnostics tools rather than primary art-direction sliders.
| Control | Purpose | Guidance |
|---|---|---|
| Enable Adaptive PPV | Turns adaptive particle-per-voxel behavior on or off. | Leave enabled when density changes should be smoothed over time. |
| Tau Frames | Controls the response time in frames. | Higher values react more slowly and smoothly. |
| Rate Up | Limits how quickly particle density can increase. | Raise carefully to avoid sudden particle growth. |
| Rate Down | Limits how quickly particle density can decrease. | Raise carefully to avoid visible thinning. |
| Deadband | Ignores small density changes. | Useful for avoiding constant small corrections. |
| Rest Density | Reference density for the solver. | The visible value uses a water-like 1000 baseline. |
| Mass Epsilon | Small mass threshold for numerical safety. | Keep near default unless diagnosing mass-related artifacts. |
| Narrow Band / Age-Weighted Kills / TDW Birth Interpolation | Advanced particle lifecycle controls. | Use for specific density or reseeding artifacts after simpler controls are exhausted. |
Balancing Physical Accuracy and Artistic Control
Fluid simulation tools must balance two sometimes conflicting goals: physical realism and artistic controllability.
Undine aims to provide a solver that behaves in a physically coherent manner while still allowing artists to guide the behavior of the simulation through intuitive parameters.
Practical presentation of physical concepts
Many solver parameters correspond to real physical concepts such as viscosity, surface tension, or boundary friction.
Those concepts are presented in a way that allows artists to shape the simulation without requiring deep knowledge of fluid dynamics.