Troubleshooting and FAQ

Symptom	Check
Water is pink or a material is missing	Resolve shader/import errors, verify the render-pipeline setup, and confirm the package’s shader/material/resource assets are present.
Water is hidden behind scenery	Check the surface and underwater Sorting Layers, their Order in Layer values, the camera position, and the layer masks used by reflections and scene captures.
A 2.5D surface looks flat, cropped, or incorrectly projected	Confirm that the scene camera uses Perspective projection; use 2D Water or Fake Perspective 2D Water with an orthographic camera. Then check camera angle, near/far clipping, water Depth (Z), and the back-edge offsets.
Underwater color or distortion repeats, ghosts, or becomes unstable	In the active 2D Renderer Data, set Foremost Sorting Layer to the last captured layer before Underwater. Never include the Underwater layer in the Camera Sorting Layer Texture that its own shader samples.
Objects sort incorrectly against a 2.5D surface	The surface uses both Sorting Layers and ZWrite depth testing. Check the object’s Z position relative to the surface before changing its sorting order, and keep ZWrite enabled on the supplied surface shader.
An imported sample scene renders incorrectly	Reopen Tools → DiffusionWorks → Ultimate Water System 2D → Set Up Current Demo Scene and apply the demo setup. The samples depend on their temporary Sorting Layers and Camera Sorting Layer Texture boundary.
Sensor stays dry	Enable Interactions, enabled water/trigger/collider components, actual water bounds, exclusion areas, and assigned sample points. Confirm automatic updates or a manual Refresh() call.
Sensor finds water but the head is not submerged	HasWater is not a head-underwater test. Inspect State, the head sample point, and IsFullySubmerged.
No entry event when starting underwater	Entry is filtered for surface entry. Use current readings or StateChanged for initial submerged behavior.
Splash/wake missing on a moving object	Affect Layers, collision setup, Rigidbody2D or MotionTracker2D, minimum movement speed, spawn rate, and visual/deformation switches.
Splash looks too large but the ring is correct	Change the splash blob controls or per-object blob override rather than ring amplitude.
Current is visible but objects do not move	Current lines are visual. Check target mode, marker, layer/tag filters, body state, and whether a custom controller applies sampled current.
Player is pushed twice	Check automatic current application plus controller force application, and multiple water-movement methods in one update.
Character will not swim after adding the helper	WaterCharacter2D calculates and returns a velocity; it does not move the character. Your controller must use that result in its normal movement and collision step.
Buoyant object sinks or jitters	Detection first, then lift versus mass/gravity, damping, float-point coverage, constraints, and competing movement scripts.
Floating decoration clips through waves	Surface offset/clearance, follow-surface option, peak sampling, and sorting.
Reflection misses an object	Both GameObject-layer and sorting-layer masks; marker settings; capture visibility, distance, and camera filters.
Reflection seems delayed	Update Every N Frames and capture distance/visibility restrictions.
Exclusion does not look or behave correctly	Zone owner, shape, sorting, automatic refresh, and whether the sample is actually inside it.
Random ripples do not animate in edit mode	Spawning runs during Play mode.
Simple Water does not provide buoyancy	It is a visual shape renderer; use the main interactive water workflow.

Can I use my own controller? Yes. Start with WaterSensor2D and read the water state and forces you need. WaterCharacter2D is an optional helper and a source-code reference for building your own water movement.

Can two water bodies look different? Yes. Use separate settings/presets and the per-body material-instancing option.

Are floating props physics objects? The Floating Props and Floating Debris modules are decorative. Use Buoyancy 2D for physics objects and Floating Platform 2D for the platform behavior described above.

Do I need to add the internal water components myself? Create water through the provided menu and use its unified Inspector. Only add the relevant object-level utilities to characters, props, or platforms.