---
name: water-reflection
description: 为 Unity 项目中的 UI Image 或 Sprite 应用水面倒影效果。创建或复用 WaterReflection shader（IndianOcean/WaterReflection），创建材质并应用到目标物体。支持水面线位置、波浪振幅、扰动强度、倒影变暗、淡出长度、水面线亮度等参数配置。当用户提到水面倒影、水面反射、倒影效果、water reflection 时使用。
---

# 水面倒影效果 (Water Reflection)

为 UI Image 或 SpriteRenderer 添加水面倒影效果：原图上半部分保持不变，下半部分显示垂直翻转的扰动倒影，水面分界线带波浪起伏和亮线。

## 资源路径

| 资源 | 路径 |
|------|------|
| Shader | `Assets/Light/shaders/WaterReflection.shader` |
| 材质 | `Assets/Materials/WaterReflection.mat` |
| Shader 名称 | `IndianOcean/WaterReflection` |

## 使用流程

### 1. 确保 Shader 存在

检查 `Assets/Light/shaders/WaterReflection.shader` 是否存在。若不存在，从下方 [Shader 源码](#shader-源码) 创建。

### 2. 创建或复用材质

使用 MCP `assets-material-create` 工具：

```
shaderName: "IndianOcean/WaterReflection"
assetPath: "Assets/Materials/WaterReflection.mat"
```

若材质已存在则跳过。

### 3. 应用到目标物体

通过 MCP `script-execute` 执行以下脚本（替换 `TARGET_NAME` 为目标物体名）：

```csharp
using UnityEngine;
using UnityEditor;
using UnityEngine.UI;

public class Script
{
    public static void Main()
    {
        var target = GameObject.Find("TARGET_NAME");
        var mat = AssetDatabase.LoadAssetAtPath<Material>("Assets/Materials/WaterReflection.mat");

        // UI Image
        var img = target.GetComponent<Image>();
        if (img != null) { img.material = mat; return; }

        // SpriteRenderer
        var sr = target.GetComponent<SpriteRenderer>();
        if (sr != null) { sr.material = mat; return; }

        // Any Renderer
        var r = target.GetComponent<Renderer>();
        if (r != null) { r.material = mat; return; }
    }
}
```

### 4. 刷新资源

调用 MCP `assets-refresh` 确保 Unity 编译 shader。

## 可调参数

| 参数 | 说明 | 默认值 | 范围 |
|------|------|--------|------|
| `_Waterline` | 水面线位置（UV.y） | 0.7 | 0.05 ~ 0.95 |
| `_WaveAmplitude` | 水面线波浪振幅 | 0.012 | 0 ~ 0.05 |
| `_WaveFreq` | 水面线波浪频率 | 4.0 | 1 ~ 15 |
| `_WaveSpeed` | 水面线波浪速度 | 1.0 | 0 ~ 5 |
| `_DistortStrength` | 倒影水平扰动强度 | 0.015 | 0 ~ 0.08 |
| `_DistortSpeed` | 扰动动画速度 | 1.5 | 0 ~ 5 |
| `_DistortFreq` | 扰动波纹频率 | 8.0 | 1 ~ 20 |
| `_ReflDarken` | 倒影变暗系数 | 0.5 | 0 ~ 1 |
| `_ReflFadeLen` | 倒影向下淡出长度 | 0.25 | 0 ~ 0.5 |
| `_LineBrightness` | 水面线亮度 | 1.5 | 0 ~ 3 |
| `_LineThickness` | 水面线粗细 | 0.004 | 0 ~ 0.02 |

通过 MCP `gameobject-component-modify` 或 `object-modify` 修改材质参数。

## Shader 源码

若需重建 shader，完整源码见 [WaterReflection.shader](../../../Assets/Light/shaders/WaterReflection.shader)。

核心原理：
- 以 `_Waterline` 为轴，多层正弦+noise 叠加产生波浪形分界线
- 倒影区 UV 垂直翻转：`reflUV.y = 2 * waterline - uv.y`
- 水平扰动由多层 noise 叠加模拟随机水面波纹
- 倒影从上往下逐渐淡出（alpha 衰减）
- 水面分界线处叠加蓝白色亮线

## 注意事项

- 项目使用 **URP** 渲染管线，shader 已包含 `"RenderPipeline" = "UniversalPipeline"` tag
- UI Image 通过 `Image.material` 设置，不是 `Renderer.material`
- 修改 shader 文件后需调用 `assets-refresh` 触发重新编译
- 波浪效果是动态的（依赖 `_Time.y`），在 Play 模式下最明显