// undine docs
Colliders
A collider is an object that interacts with the fluid and affects its motion.
In the simulation pipeline, colliders are part of scene configuration and continue to matter throughout boundary interaction during each simulation step.
Colliders in the pipeline
The user defines colliders during scene configuration, and the solver later accounts for that geometry during boundary interaction.
This makes colliders one of the clearest examples of how Blender scene objects and solver behavior meet.
| Step | Control | Purpose |
|---|---|---|
| Tagging | Tag Collider | Marks the selected Blender object as a collision participant. |
| Validation | Tagged in Scene: Colliders | Confirms the expected collider count before solving. |
| Preparation | Bake colliders (animated) | Builds animated collider data for the configured frame range. |
| Simulation | Collider SDF controls | Tunes how the solver predicts, bands, and resolves boundary contact. |
Why colliders matter
Collision handling is one of the core simulation subsystems listed in the project overview. Keeping this chapter separate makes it easier to document scene interaction without mixing it into unrelated controls.
Collider SDF
The Collider (SDF) section controls how a fluid — viscous or not — responds when it touches an SDF collider. It is the fourth layer of viscosity behavior but applies to any liquid.
SDF settings are especially important for thin contacts, moving objects, and shots where fluid needs to slide, stick, or damp against a boundary. The percentage sliders map onto internal 0..1 strengths (0% → 0.0, 100% → 1.0).
| Control | Property | Default · Range | What it does / when to tune |
|---|---|---|---|
| Predict Band Cells | collider_band_cells | 2 · 0–6 | Width of the predictive SDF band (in cells) used to condition contact. 0 disables it. More cells = earlier/softer contact detection at extra cost. |
| Boundary Band (vox) | boundary_band_voxels | 1.0 · 0–4 | SDF edge smoothing band in voxels. 0 disables smoothing (hard edge). Raise for less stair-stepped contact. |
| Contact Radius Scale | collision_contact_radius_scale | 0.5 · 0–2 | Scales particle radius to a minimum contact offset against the collider in world-grid units. 0 = legacy behavior. Raise to avoid penetration/leaking on thin meshes. |
| Normal Damping | collider_normal_damping_percent | 15% · 0–100% | Damping of the normal component near the collider (per step). 0% = bounce preserved; high = the fluid loses impact velocity against the surface (less splash/bounce). Real property: collider_normal_damping (0..1). |
| Tangent Friction | collider_tangent_friction_percent | 15% · 0–100% | Tangential friction near the collider (per step). 0% = free slide; high = it slows while sliding along the surface. Real property: collider_tangent_friction (0..1). |
| Tangential Capture Speed | collider_stick_threshold | 0.02 · 0–5 | Tangential slip-speed threshold below which no-slip capture is reinforced. Slow material "sticks" to the wall. |
| Tangential No-Slip Strength | collider_stick_strength | 0.6 · ≥0 | Strength of tangential no-slip. Affects slip only; it does NOT increase contact distance or normal separation. Raise so material adheres / does not slide on walls. |
| Slip Capture | collider_slip_capture_enabled | False · bool | Enables impact/settle slip capture: biases the tangential response by approach velocity. Reveals the tuning sub-panel below. |
Slip Capture Tuning
Visible only with Slip Capture enabled. It biases tangential response by contact state, so a material can slide on impact but grip once it settles.
Impact and settled states are classified by the normal approach speed; the tangent and stick scales then shape how much the fluid slips or grips in each state.
Pros and cons of SDF colliders
- Pros: fine physical control of contact (bounce vs friction vs no-slip), and state-based slip capture for materials that slide on the way down but grip once they rest.
- Cons: many interdependent sliders; extreme damping/friction can glue the fluid artificially or kill splash dynamics. No-slip does not solve penetration — that is Contact Radius Scale / Boundary Band.
| Control | Property | Default · Range | What it does |
|---|---|---|---|
| Impact Speed | collider_slip_impact_speed | 0.2 · 0–5 | Normal-speed threshold for classifying a contact as impact. |
| Settled Speed | collider_slip_settled_speed | 0.05 · 0–2 | Normal-speed threshold below which a contact is considered settled. |
| Impact Tangent Scale | collider_slip_impact_tangent_scale | 0.35 · 0–1 | Tangential friction scale while the contact is impact (<1 = more sliding on the hit). |
| Settled Tangent Scale | collider_slip_settled_tangent_scale | 1.1 · 1–2 | Tangential friction scale while the contact is settled (>1 = more grip at rest). |
| Settled Stick Scale | collider_slip_settled_stick_scale | 1.25 · 1–2.5 | Multiplier on the stick strength while the contact is settled. |
Contact enhancement
Contact Enhancement can add particles near collider contact regions to reduce dry gaps and improve refill behavior.
The panel notes that Contact Band Cells must be greater than zero to enable collider-contact refill.
| Control | Purpose | Notes |
|---|---|---|
| Contact Band Cells | Enables and sizes the contact refill band. | Set above zero to enable contact refill. |
| Contact Oversampling | Controls extra sampling in the contact region. | Higher values can improve coverage but increase particle work. |
| Contact Min PPC | Minimum particles per cell near contacts. | Useful when contact zones look under-filled. |
| Contact Mass Bias | Biases mass behavior for contact refill. | Tune carefully to avoid visible density changes. |
| Contact No Reseed Cells | Protects a band from reseeding near contact. | Can reduce unwanted particle churn around colliders. |
Thin sheets and collider-heavy shots
Thin liquid sheets and complex collider interactions are difficult regimes for any solver.
When collider-heavy shots become unstable, first test with shorter frame ranges, higher substep safety, and conservative collider SDF values before increasing mesh quality.