StylizedWater2插件帮助文档精读

请尊重原作者的工作，转载时请务必注明转载自：www.xionggf.com

插件官方文档地址

---

Stylized Water 2 入门指南

1. 准备工作

• 确保项目无控制台错误：未解决的代码错误会导致资源代码无法编译，材质可能显示为粉色。
• 项目设置：
  • 使用 Universal Render Pipeline (URP)：在 Edit -> Project Settings -> Graphics 中检查是否已分配 URP 资源。
  • 如果没有正确设置 URP，材质将显示为粉色。请参考 Unity 的 URP 文档进行设置。
  • 注意：建议在项目早期决定使用 URP，因为在生产过程中切换到 URP 可能导致其他自定义着色器失效。
  • 颜色空间：推荐使用 Linear 颜色空间（新项目默认使用 Gamma 空间），详细信息请参考 Unity 文档。

2. URP 设置

• 启用必要选项：
  • Depth Texture：用于多种效果（如深度和交互动画）。如果禁用，这些效果将失效，且在 Android 上构建时水可能会不可见。
  • Opaque Texture：用于折射效果，启用折射时需要。
  • 如果这些选项未启用，但着色器使用了相关功能，材质 UI 中会显示警告并提供快速修复按钮。
• 相机设置：每个相机可以覆盖这些设置。如果某些效果在特定场景或相机中不可见，请检查这些选项是否被设置为“Off”。
• 质量级别设置：如果使用了不同质量级别的管道设置，请确保这些选项也已启用，否则在较低质量级别下运行时，水效果可能失效。

3. 向场景中添加水

• 建议：创建或复制材质（而不是直接使用包中的材质），以避免更新资源时设置被意外覆盖。
• 方法：
  • 方法 1：将 Assets/StylizedWater2/Prefabs 中的预制件拖入场景，并调整材质属性。
  • 方法 2：通过 GameObject -> 3D Object -> Water -> Object 菜单选项创建新的 Mesh Renderer。
  • 方法 3：
    1. 在场景中创建一个平面网格。
    2. 创建新材质并分配 StylizedWater2/Default 着色器。
    3. 通过 Add Component -> Stylized Water 2 -> Water Object 添加 Water Object 组件（仅在需要使用平面反射时必要，但无负面影响）。
• 材质参数：每个参数都有工具提示，鼠标悬停可查看描述。

---

Stylized Water 2 着色器使用指南

1. 基本设置

• 着色器与材质：着色器分配给材质，材质应用于网格。由于水的透明特性，着色器始终以 Forward 渲染 方式渲染。
• 材质参数工具提示：大多数参数都有工具提示，鼠标悬停可查看描述。也可通过“Toggle tooltips”按钮展开所有提示。

2. 着色模式

• 高级着色模式（Advanced Shading Mode）：
  • 专注于高端渲染，适合需要高质量水效果的项目。
  • 特点：
    • 色散折射（chromatic refractions）：颜色通道分离一个像素。
    • 焦散/太阳反射遮罩(caustics/sun)：即使水不接收阴影，也会读取阴影贴图以避免这些效果出现在阴影中。
    • 透射颜色(translucency color)与光源颜色(light color)更精确地混合。
    • 双采样折射(double-sampling of refraction)：使颜色梯度也呈现折射效果。
    • 第二法线贴图采样(double-sampling of refraction)：用于远距离法线。
  • 适用场景：如果水在游戏中仅为背景或俯视角查看，高级模式可能无明显优势。
• 简单着色模式（Simple Shading Mode）：
  • 适合移动设备硬件，性能更优。

3. 构建时切换功能

• 关键词（Keywords）：
  • 着色器使用关键词来控制特定代码的执行或跳过，类似于 C# 中的定义符号。
  • 关键词状态保存在材质中。
  • 多编译关键词（Multi-compile Keywords）：
    • Unity 在构建项目时会编译多个着色器变体，以实现实时质量/性能调整。
    • 例如，点光源/聚光灯的启用或禁用。
  • 着色器功能（Shader Features）：
    • 对于法线贴图、泡沫和波浪等功能，如果未在材质中启用，构建时不会创建禁用该功能的着色器变体。
    • 原因：多编译关键词会指数级增加着色器变体数量，可能导致多达 200 万种变体，显著增加构建时间（数小时）。
• 修改关键词：
  • 如果需要允许功能切换，可以修改着色器文件（StylizedWater2.shader），将 #pragma shader_feature_local _WAVES 替换为 #pragma multi_compile_local _ _WAVES。
  • 之后可通过 material.SetKeyword("_WAVES", true/false); 切换关键词状态。
• 替代方案：
  • 创建两个材质：一个启用功能，另一个禁用功能。只要两个材质都包含在构建中，Unity 会编译两种变体，允许在运行时切换。

总结

• 着色模式选择：根据项目需求和目标平台选择“简单”或“高级”着色模式。
• 功能切换：通过关键词控制着色器功能，但需注意多编译关键词可能显著增加构建时间。
• 优化建议：修改着色器文件或创建多个材质以实现功能切换，同时平衡性能与灵活性。

---

Stylized Water 2 顶点颜色功能

1. 顶点颜色概述

• 定义：顶点颜色是网格顶点属性（Vector4），类似于位置、法线和 UV。
• 用途：可用于驱动着色器的某些行为。
• 编辑方式：
  • 在主流 3D 工具（如 Maya、Blender、3DS Max）中绘制。
  • 在 Unity 编辑器中使用 PolyBrush 绘制。
  • 通过 C# 脚本程序化生成（示例脚本：链接）。脚本通过射线检测测量顶点到地形的距离，并将归一化距离存储在顶点颜色通道中。

2. 顶点颜色的应用

• 最佳实践：使用为环境定制的自定义网格，以获得最佳效果。
• 注意事项：
  • 在 Unity 编辑器中绘制顶点颜色后，网格会变为唯一实例并保存到场景文件中，无法再与预制件一起使用。
  • 可使用 FBX Exporter 包将网格导出为新文件。

3. 顶点颜色通道的具体功能

• 红色通道（Red Channel）：

  • 功能：控制 交互动画泡沫(intersection foam)。

  • 设置：在“Intersection”选项卡中，将“Gradient source”设置为“Vertex color”或“Both”。

  • 建议：避免绘制 100% 红色，需要线性渐变以获得最佳效果。

    

• 绿色通道（Green Channel）：

  • 功能：控制 深度颜色渐变。

  • 设置：在“Color”选项卡中启用“Vertex color opacity”复选框。

  • 特殊说明：

    • 如果浅水颜色的 Alpha 通道为 0，顶点颜色会使水透明。
    • 启用 River Mode 时，此通道完全控制透明度（法线贴图、折射和光反射也会淡出）。

    

• 蓝色通道（Blue Channel）：

  • 功能：控制 波浪平坦化（wave flattening）。
  • 设置：在“Waves”选项卡中启用“Vertex color flattening”复选框。
  • 用途：允许在环境的一部分区域保持高波浪，而在海岸线处保持平静水面。
  • 注意：不影响浮力（浮力仍读取原始波浪高度）。

  

• Alpha 通道（Alpha Channel）：

  • 功能：控制 表面泡沫。
  • 设置：在“Surface Foam”选项卡中启用“Vertex color painting”复选框。
  • 绘制方式：
    • 在 PolyBrush 中，需将颜色掩码设置为仅应用于“A”（Alpha）通道。
    • Alpha 值决定绘制的泡沫强度。
  • 注意：顶点颜色会添加泡沫，但材质颜色 Alpha 通道仍控制“基础”泡沫不透明度。

总结

• 顶点颜色是控制水效果的重要工具，可通过多种方式编辑和应用。
• 各通道功能：
  • 红色：交互动画泡沫。
  • 绿色：深度颜色渐变和透明度。
  • 蓝色：波浪平坦化。
  • Alpha：表面泡沫。
• 优化建议：使用自定义网格和适当工具（如 PolyBrush）以获得最佳效果。

---

Stylized Water 2 平面反射功能

1. 概述

• 默认反射：水默认反射天空盒和反射探针（Reflection Probes），适合表现水的曲率（受波浪法线和法线贴图影响）。
• 平面反射（Planar Reflections）：
  • 通过从镜像视角渲染场景，实现类似镜子的反射效果。
  • 反射会与反射探针混合，结合两者的优点。
  • 波浪和法线会扭曲反射，创造逼真的水面反射效果。
  • 限制：仅适用于平坦水面（单一高度）。

2. 设置

• 启用平面反射：

  • 方法 1：通过 Window -> Stylized Water 2 -> Set up planar reflections 启用。
  • 方法 2：创建空 GameObject，添加 Stylized Water 2 -> Planar Reflection Renderer 组件。

• 分配水对象：

  • 手动分配需要应用反射的水对象，或点击“Auto-find”按钮自动分配场景中所有水对象。
  • 如果场景中只有一个水对象，它会自动分配。

• 水对象要求：

  • 水网格必须附加 Water Object 组件。
  • 水对象应始终位于“Water”层，否则水本身会被渲染到反射中，导致“无限镜”效果。

• 边界框：

  • 组件选中时，会显示一个白色矩形框，表示渲染的边界。
  • 如果水对象移动，边界框会过时，导致反射停止渲染。此时会显示错误和快速修复按钮。

  enter description here

3. 故障排除

• 反射不可见：
  • 检查材质参数“Curvature Mask”（Reflections 选项卡），它基于视角影响反射可见度。
  • 将该值调低可增加反射可见度（0 时水几乎成为镜子）。
• Game 视图中反射异常：
  • 禁用第三方渲染功能，检查是否有影响。
  • 如果需要，可为平面反射设置单独的渲染器（参见性能指南部分）。
• 反射中出现黑点或黑色区域：
  • 问题已在版本 1.1.5 中修复。
  • 如果反射中大部分为黑色，可能是场景未设置反射探针。
    • 解决方法：在 Window -> Rendering -> Lighting Settings 中禁用“Baked Global Illumination”，勾选“Auto generate”，等待烘焙完成后再禁用。
    • 或手动创建反射探针（GameObject -> Light -> Reflection Probe），确保探针框至少接触水面。

enter description here

4. 多实例支持（v1.1.0+）

• 多个反射渲染器：
  • 可以为不同水对象创建多个 Planar Reflection Renderer 组件。
  • 例如，一个渲染器用于海洋（仅反射船只），另一个用于内陆池塘（仅渲染短距离）。
  • 特别适用于水对象不在同一高度的情况。

5. 限制

• 水对象移动：如果水对象移动，需调用 RecalculateBounds() 函数更新边界框。
• VR 不兼容：平面反射不支持 VR。
• Overlay 相机：通过 Overlay 相机渲染的水不会显示平面反射（作为优化手段）。
• 加载/流式系统：通过加载/流式系统加载的水对象无法使用平面反射。

6. 未来改进

• 组 ID 功能：计划为 Water Object 组件添加“Group ID”下拉菜单，以便自动分配到具有相同 ID 的 Planar Reflection Renderer 组件。

7. 性能

• 详细信息请参阅 性能指南 部分。

总结

• 平面反射为水提供了逼真的镜像反射效果，但仅适用于平坦水面。
• 设置简单：通过菜单或组件启用，分配水对象即可。
• 故障排除：注意 Curvature Mask 参数、反射探针设置和第三方渲染功能的影响。
• 多实例支持：可为不同水对象创建多个反射渲染器。
• 限制：不支持 VR、Overlay 相机和流式加载的水对象。

---

Stylized Water 2 组件与工具

1. Water Object 组件

• 功能：
  • 用于标识场景中代表水的对象。
  • 被 Planar Reflection Renderer、Underwater Rendering 扩展和 Buoyancy API 使用。
  • 缓存网格和材质，以便快速检索。
  • 提供对 MaterialPropertyBlock 的访问。
  • 可通过 Transform 获取水位高度。
• 位置：所有预制件上都附有此组件。

2. Water Mesh 工具

• 功能：
  • 生成平面或圆形网格，用于水着色器。
  • 方便在 Unity 内为网格添加细分，无需使用外部工具。
  • 使用波浪时，网格需要足够的顶点密度。
• 创建方法：
  • 在项目窗口中右键单击，选择 Create -> Water -> Mesh，生成 .watermesh 资产。
  • 生成的网格可分配给任何 Mesh Filter 组件。
• 注意事项：
  • 避免添加过多细分（超过 65k 顶点），否则会导致网格混乱。
• API：
  • 使用 StylizedWater2.WaterMesh 类通过脚本创建网格。
  • 修改公共属性后调用 Rebuild() 函数生成网格。
  • 或直接调用 StylizedWater2.WaterMesh.Create 函数。

3. Water Grid 组件

• 功能：
  • 在其位置周围创建水网格的网格。
• 创建方法：
  • 通过 Add Component -> Stylized Water 2 -> Water Grid 添加。
  • 或通过 GameObject -> 3D Object -> Water -> Grid 创建。
  • 或通过 Window -> Stylized Water 2 -> Create water grid 创建。
• 跟随目标：
  • 设置“Follow target”变换字段，使网格在 XZ 轴上跟随目标。
  • 位置会捕捉到最近的顶点，避免移动时波浪抖动。
• 材质设置：
  • 材质 UI 中的“General”选项卡下，将“UV Source”设置为“World XZ Projected”（默认设置），以确保水面一致性。
• 用途：
  • 用于创建流式系统的水块，或模拟无限海洋。
• 限制：
  • 不支持动态顶点细分（如 CDLOD 系统），这超出了资源范围。
  • 由于网格是程序化生成，在预制件中使用时会重新生成，但速度较快。

4. Align Transform To Waves 组件

• 功能：
  • 使 Transform 及其子对象贴合水面。
  • 通过重新计算材质的波浪模式，在代码中镜像波浪动画。
• 注意事项：
  • 脚本会修改 Transform 的旋转和 Y 位置，因此无法手动旋转或通过其他脚本修改。
  • 可通过直接修改子对象的旋转来实现额外旋转。
  • 不与 RigidBody 兼容：重力会试图拉下物体，导致物理和 Transform 域之间的冲突，表现为极端抖动。
• 示例：
  • “WavesExample”场景展示了此组件的实际效果。

总结

• Water Object：标识水对象，支持反射、水下渲染和浮力功能。
• Water Mesh：生成平面或圆形网格，支持脚本创建和修改。
• Water Grid：创建水网格，支持跟随目标和流式系统。
• Align Transform To Waves：使对象贴合水面，但不支持 RigidBody。

---

Stylized Water 2 脚本功能

1. 概述

• 主要功能：虽然这是一个着色器资源，但浮力（Buoyancy）相关的功能需要脚本支持，因此提供了一些 C# 函数辅助开发。
• 前提：假设用户熟悉 C# 和面向对象编程（OOP）。官方不提供基础编码帮助。
• 注意事项：
  • 如果使用程序集定义（Assembly Definition），需添加对 sc.stylizedwater2.runtime 程序集的引用，否则无法访问 StylizedWater2 命名空间和类。
  • 所有函数均支持 IntelliSense 摘要，可在 IDE 中查看参数描述和重载变体。

2. 关键函数

• StylizedWater2.WaterObject.Find：

  • 功能：在给定位置下方或上方查找 Water Object 组件。
  • 用途：采样波浪高度/法线时，需要引用 Water Object 组件以访问水位高度（Y 位置）和材质（波浪设置）。
  • 性能：效率随场景中 Water Object 数量增加而降低，不建议每帧调用。

• StylizedWater2.Buoyancy.FindWaterLevelIntersection：

  • 功能：模拟假射线检测，计算从某点沿特定方向与水位（世界空间高度）的交点。
  • 用途：作为快速粗略检查，适用于不需要波浪精度的情况。

• StylizedWater2.Buoyancy.Raycast：

  • 功能：模拟物理风格的射线检测，内部使用 FindWaterLevelIntersection 和 Buoyancy.SampleWaves 函数。
  • 用途：可用于定位子弹击中水面等效果。
  • 注意：与射线检测不同，无法返回是否命中 Water Object，但可检查返回点是否低于水位。

• StylizedWater2.Buoyancy.CanTouchWater：

  • 功能：检查位置是否介于 Water Object 的 Y 位置和最大波浪高度之间。
  • 用途：作为快速粗略检查，在调用更耗资源的 Buoyancy.SampleWaves 之前使用。

3. 高级功能

• 浮动原点系统（Floating Origins）：

  • 功能：通过 StylizedWater2.WaterObject.PositionOffset = <Vector3> 设置着色器中的世界位置偏移值。
  • 用途：用于处理大型场景中的坐标偏移问题。

• 网络同步波浪：

  • 问题：着色器效果（包括波浪）使用 Unity 的全局 _TimeParameters 值（即 UnityEngine.Time.time）作为时间索引。
  • 解决方案：通过网络应用确保所有玩家的波浪一致，可通过脚本每帧传递自定义时间值：StylizedWater2.WaterObject.CustomTime = <float>。
  • 禁用：传递小于 0 的值即可禁用此行为。

总结

• 核心功能：提供了一系列 C# 函数，支持浮力计算、波浪采样和水位检测。
• 性能优化：通过快速粗略检查（如 CanTouchWater 和 FindWaterLevelIntersection）减少资源消耗。
• 高级应用：支持浮动原点系统和网络同步波浪，适用于大型场景和多人游戏。

---

Stylized Water 2 河流模式

1. 概述

• 默认行为：水效果沿“General”选项卡中配置的方向流动，部分效果（如法线和泡沫）有反向流动的次级层。
• 河流模式（River Mode）：为河流/溪流设计，水始终沿单一方向流动。

2. 材质设置

• 启用河流模式：
  • 在材质选项中启用“River mode”。
  • 功能变化：
    • 强制使用网格的 UV 通道，使水沿网格曲率流动。
    • 基于配置的角度和衰减计算坡度因子。
    • 在斜坡上绘制表面泡沫，并随水面平坦逐渐消失（新增“Slope Foam”参数）。
    • 可使用单独的法线贴图纹理，仅在斜坡上可见。
    • “Vertex color depth”选项控制透明度（而非水深）。
  • 注意：
    • 启用河流模式后，波浪功能自动禁用。
    • 浮力功能仅适用于平坦水面，不适用于河流。
• 法线贴图和泡沫：
  • 确保为“Slope”槽位分配法线贴图。
  • 表面泡沫功能启用后，可指定斜坡上的泡沫量。
  • 确保法线和泡沫的“Speed”值不为负（与湖泊材质不同）。

3. 创建河流几何体

• 工具：
  • River Modeler：与 Stylized Water 3 完美集成的专用河流工具。
  • 其他工具：如 River Auto Material 或 EasyRoads3D，支持生成样条网格。
• 网格要求：
  • UV 壳垂直布局，无重叠（确保无缝纹理平铺）。
  • 预计算顶点法线（用于识别陡峭表面）。
  • 使用法线贴图时，需计算切线（如 Mesh.RecalculateTangents）。
  • 理想情况下，无或黑色顶点颜色（避免干扰顶点颜色控制的着色功能）。
• UV 设置：
  • 确保 UV 平铺为整数值（如 1、2、3），避免纹理不连续。
  • 如果水流方向相反，可调整材质的 Y 方向，或垂直翻转 UV 贴图。

4. 河流与湖泊的混合

• 实现方法：
  • 修改河流材质的渲染队列为 3001（透明队列 + 1），确保其绘制在其他水体材质之上。
  • 在接收水体材质上启用 ZWrite。
  • 在河流材质上启用顶点颜色控制透明度。
• 顶点颜色：
  • 使用绿色顶点颜色通道使网格部分完全透明。
  • 在河流网格末端（接触湖泊的部分）绘制绿色顶点颜色，使其逐渐融入湖泊。

总结

• 河流模式为河流/溪流提供了单一方向的流动效果，支持坡度泡沫和单独的法线贴图。
• 网格要求：确保 UV 布局正确，预计算法线和切线。
• 混合河流与湖泊：通过顶点颜色控制透明度，实现平滑过渡。

---

Stylized Water 2 第三方集成

1. 概述

• 自动检测：导入水着色器时，会自动检测项目中兼容的雾效资产，并编译集成代码。
• 重新编译：如果在导入水着色器后安装雾效资产，需选择 StylizedWater2_Standard 着色器文件并点击“Recompile”按钮。
• 集成状态：可通过 Window → Stylized Water 2 → Hub 菜单查看第三方资产的集成状态。

2. 雾效资产

• 深度雾效限制：深度雾效无法对透明材质（如水）进行着色，因此需在着色器中直接应用相同的雾效着色。
• 兼容性：
  • 大多数雾效资产提供通用着色器函数，水着色器可将其集成以实现一致的雾效。
  • 如果雾效渲染器被禁用，水着色器仍会基于最后传递的设置应用雾效。
• 全局控制：从版本 1.1.2 开始，可通过脚本全局切换水着色器的雾效。例如，禁用特定相机的雾效：

  _WaterFogDisabled = 1; // 1 为禁用，0 为启用
  

3. 具体资产集成

• SC Post Effects：
  • 在 Fog 渲染功能中，必须勾选“Skip Transparents”复选框。
• COZY Weather：
  • COZY 使用透明材质渲染天空盒和雾效，因此水材质的渲染队列值会自动设置为 3002（默认为 3000），以确保水始终渲染在天空和云层之前，但在雾效球体之后。
  • 水下渲染扩展：
    • 版本 1 & 2：不兼容，需要着色器代码修改。
    • 版本 3+：自动集成。
    • 限制：
      • 不支持“Stylized”雾效风格，会导致不必要的裁剪。
      • COZY 不会在天空穹顶后渲染实际天空盒，从水下向上看时，折射环境会显示为黑色。
• Enviro：
  • 注意：如果 Enviro 的雾效渲染功能未启用，水会变为白色，因为没有雾效设置传递给着色器。
  • 平面反射：不会反射 Enviro 的雾效，这是设计缺陷，需在 Enviro 的渲染代码中修正。
• Azure Sky：
  • 大气高度雾效：需要版本 3.2.0 或更高。
  • 水下渲染扩展：不兼容，需要着色器代码修改。
• Buto 2021 | 2022 体积雾和光照：
  • 支持集成，需确保正确配置。

4. 其他资产

• Curved World 2020：
  • 需通过 Curved World 窗口的“Activator”选项卡激活，指向 Assets\Stylized Water 2\Shaders 文件夹后点击“Activate”按钮。
  • 注意：水下渲染扩展与此资产不兼容。
• Dynamic Water Physics 2 (DWP2)：
  • 如果项目中存在 DWP2，会提供 Stylized Water Data Provider 组件，允许 DWP2 使用浮力 API 读取水位高度和法线，用于物理计算。
  • 设置：通过 Help→Stylized Water 2→Hub Window 快速设置此组件。
  • 要求：至少需要版本 2.5.6。
  • 限制：浮力仅适用于平坦水体（如湖泊和海洋），不支持弯曲网格（如河流或星球）。

总结

• 雾效集成：水着色器支持与多种雾效资产集成，确保一致的视觉效果。
• 第三方资产：支持 COZY Weather、Enviro、Azure Sky、Buto 等资产的集成，但需注意兼容性和限制。
• 物理集成：支持与 Dynamic Water Physics 2 的浮力 API 集成，但仅适用于平坦水体。

---

Stylized Water 2 透明度遮罩

1. 功能概述

• 用途：通过在网格前隐藏水，创建水中的可见孔洞，常用于隐藏船体内部的水。
• 原理：使用特定的透明度遮罩材质（WaterTransparencyMask）来遮挡水材质。

2. 设置步骤

1. 创建网格：
   • 创建一个平面（Plane）网格对象。
2. 应用遮罩材质：
   • 在 StylizedWater2/Materials 文件夹中找到 WaterTransparencyMask 材质。
   • 将该材质应用于平面网格对象。
3. 效果：
   • 水材质会在该网格后变为不可见。

3. 注意事项

• 网格设计：
  • 简单的平面/四边形网格可能有效，但建议根据实际需求建模，以准确表示水的切割阈值。
  • 例如，船体内部的网格应精确匹配船体形状。
• 渲染队列：
  • 该遮罩会隐藏所有具有相同或更高渲染队列的透明材质，而不仅仅是水材质。

4. 示例

• 应用场景：
  • 在船体内部使用透明度遮罩，确保船内无水显示。
  • 创建复杂的水面效果，如瀑布或河流中的空洞。

总结

• 透明度遮罩是隐藏特定区域水材质的有效工具，适用于船体内部或其他需要切割水面的场景。
• 设置简单：只需创建网格并应用 WaterTransparencyMask 材质。
• 注意限制：遮罩会影响所有具有相同或更高渲染队列的透明材质。

---

Stylized Water 2 浮力功能

1. 概述

• 功能：通过 C# 脚本读取水面高度和法线数据，用于浮力计算。
• 前提：需要熟悉脚本编程，了解浮力系统的复杂性。
• 适用范围：主要提供第三方或自定义浮力系统所需的功能，不包含船控制器或基于物理的浮力系统。

2. 读取波浪数据

• 函数：

  StylizedWater2.Buoyancy.SampleWaves(Vector3 position, Material waterMat, float waterLevel, float rollStrength, bool dynamicMaterial, out Vector3 normal);
  

  • 功能：在任意世界位置读取波浪高度和法线。
  • 参数：
    • position：世界坐标位置。
    • waterMat：水材质。
    • waterLevel：水位高度。
    • rollStrength：滚动强度。
    • dynamicMaterial：是否使用动态材质。
    • normal：输出法线向量。
  • IDE 支持：函数和参数描述可通过 IDE 查看。
• 材质设置：
  • 在材质的“General”选项卡中，确保“UV Source”设置为“World XZ projected”（默认设置）。
• 返回值：
  • 返回的数据比水网格的视觉表示更精确。
  • 不返回网格三角形的高度/法线，而是基于着色器计算的结果。
• 程序集引用：
  • 如果使用程序集定义，需添加对 sc.stylizedwater2.runtime 程序集的引用，否则无法访问 StylizedWater2.Buoyancy 类。

3. 动态水物理 2（DWP2）集成

• 功能：
  • DWP2 是一款高级浮力/流体动力学系统，包含船控制器。
  • 提供与 Stylized Water 2 的集成，允许读取水位高度和法线数据。
• 安装：
  • 通过 Help->Stylized Water 2->Hub Window 快速设置 Stylized Water Data Provider 组件。
  • 具体步骤请参考“第三方集成”部分。

4. 限制

• 适用水体：仅适用于平坦水体（如湖泊和海洋）。
• 河流或球形水体：不支持，需要复杂的脚本或自定义物理系统。

总结

• 浮力功能：通过 SampleWaves 函数读取波浪数据，支持自定义浮力系统。
• DWP2 集成：与 Dynamic Water Physics 2 无缝集成，提供高级浮力和流体动力学支持。
• 限制：仅适用于平坦水体，不适用于河流或球形水体。

---

Stylized Water 2 故障排除与常见问题解答

1. 通用建议

• 确保项目无控制台错误：未解决的代码错误会导致资源代码无法编译和执行，着色器可能显示为粉色或功能缺失。

2. 渲染问题

• 透明材质（+精灵和粒子效果）总是出现在水的前面或后面：
  • 检查渲染队列设置，确保透明材质的渲染顺序正确。
• 焦散效果随相机移动而扭曲：
  • 确保 Depth Texture 已启用，并检查材质设置。
• 水显示为黑色反射：
  • 检查反射探针设置，确保场景中有有效的反射探针。
• 水不透明且呈灰色：
  • 确保材质透明度设置正确，并检查渲染队列。
• 应用河流材质后水消失：
  • 确保河流材质的设置正确，特别是 UV 和顶点颜色。
• （Unity 6+）使用波浪时，水整体上下移动：
  • 检查波浪设置，确保材质和网格配置正确。
• 水下的透明材质未折射：
  • 确保折射功能已启用，并检查材质设置。
• 折射在几何体周围显示红/蓝伪影：
  • 检查 Opaque Texture 设置，确保正确启用。
• 构建后水深和交互动画效果不可见：
  • 确保 Depth Texture 和 Opaque Texture 在构建设置中启用。
• 某些对象上未显示水深和交互动画效果：
  • 检查对象的材质和渲染设置，确保兼容。
• 使用 Forward+ 渲染时，光源在一定距离后不再影响水：
  • 检查光源范围和渲染管线设置。

3. 错误

• 着色器错误：OUTPUT_SH4: 宏调用参数不足：
  • 检查着色器代码，确保宏调用参数正确。
• 着色器错误：未声明的标识符 ‘_FOVEATED_RENDERING_NON_UNIFORM_RASTER’：
  • 确保项目配置正确，特别是与渲染管线相关的设置。
• 着色器错误：无法包含源文件 Underwater/UnderwaterFog.hlsl：
  • 确保文件路径正确，文件存在且未被损坏。
• 着色器错误：无法包含源文件 Libraries/hlsl：
  • 检查文件路径和命名，确保正确。
• 着色器错误：无法打开包含文件 ‘Packages/com.unity.render-pipelines.universal/ShaderLibrary/DOTS.hlsl’：
  • 确保 URP 包已正确安装并配置。

4. 编辑器问题

• 场景视图中水透明，但游戏视图中不透明：
  • 检查渲染设置和材质配置，确保一致。
• 正交相机下场景视图中水不可见：
  • 检查相机设置和材质渲染队列。
• 场景视图中水动画不流畅或不起作用：
  • 确保场景视图的渲染设置与游戏视图一致。

5. 移动设备问题

• 水在设备上显示与编辑器（PC/主机）不同：
  • 检查移动设备的渲染精度设置，确保兼容。
• 在设备上运行时，交互动画泡沫闪烁：
  • 优化移动设备的深度纹理设置，减少精度问题。
• 纹理在长时间运行后出现像素化：
  • 检查纹理分辨率和内存管理，确保优化。
• 正交相机下，水出现在其他对象/地形下方，且交互动画不可见：
  • 检查相机设置和材质渲染队列。

6. 伪影问题

• 光反射显示噪点伪影：
  • 检查反射设置和材质参数，确保优化。
• 折射也扭曲水面上方的对象：
  • 检查折射设置和材质参数，确保正确。
• 从远处看水显示噪点伪影：
  • 优化渲染设置和材质参数，减少伪影。

总结

• 渲染问题：常见问题包括透明材质顺序、反射、折射和动画效果，需检查材质和渲染设置。
• 错误处理：着色器错误通常与文件路径、宏调用和渲染管线配置有关，需仔细检查。
• 移动设备优化：由于硬件限制，需特别注意深度纹理和渲染精度。
• 伪影修复：通过优化反射、折射和材质参数，减少噪点和扭曲。

---

Stylized Water 2 性能优化指南

1. 通用建议

• 使用性能分析工具：推荐使用 Profiler 和 Frame Debugger 工具，深入了解项目的渲染性能，准确判断优化需求。
• 性能指标：帧率（FPS）不是可靠的性能指标，需结合其他工具进行分析。

2. 着色器性能

• 核心优化：着色器通过高效利用资源进行了优化，通常优于使用 Shader Graph 创建的类似效果。
• 性能影响因素：
  • 启用的功能(render features)。
  • 着色器处理的顶点数量。
  • 水着色器渲染的屏幕像素数量。
• 水效果复杂性：水是复杂的现象，需要多层元素实现逼真效果，因此性能影响不可避免。

3. 优化建议

• 减少屏幕空间：如果水占据的屏幕空间较小，渲染速度会更快。
• 禁用动态光照：如果场景不使用动态光照（如昼夜系统），可在材质中禁用光照以节省性能（位于“Lighting”选项卡）。
• 深度纹理：在 URP 中渲染深度纹理会显著增加绘制调用次数。如果项目未优化绘制调用，建议在 URP 资产和水材质中禁用深度纹理，改用顶点颜色绘制效果。
• 波浪功能：启用波浪时，尽量将“Count”参数值保持在最低。

4. 高开销功能

• 法线贴图：每个像素的矩阵变换 + 更多数据通过着色器阶段。
• 波浪：算法对每个顶点和屏幕上的水像素运行。
• 折射：采样全屏纹理 + 重新采样深度以过滤水面上方的对象。

5. 移动设备优化

• 目标设备：现代设备可以流畅运行所有功能，但针对老旧设备时，需禁用不影响美术方向的功能。
• 着色模式：始终使用“Simple”着色模式（位于材质 UI 的“Rendering”选项卡）。
• UV 坐标：将“UV Coordinates”（General 选项卡）设置为“Mesh UV”，并通过 UV 管理水面平铺，避免高数值 UV 坐标引入浮点舍入误差。

6. 平面反射优化

• 性能影响：平面反射涉及从镜像视角重新渲染场景几何体，可能使渲染成本翻倍。
• 剔除掩码：使用 Culling Mask 字段，仅反射对视觉效果重要的图层。
• 渲染器：
  • 创建单独的“空”渲染器，专门用于平面反射。
  • 在 Planar Reflection Renderer 组件中配置使用此渲染器，避免不必要的渲染。

7. 脚本优化

• 全局控制：通过 StylizedWater2.PlanarReflectionRenderer.SetQuality 函数全局切换平面反射设置，适用于不同质量等级的项目。

  StylizedWater2.PlanarReflectionRenderer.SetQuality(
          bool allowReflections, float renderScale = -1f, float renderRange = -1f, int maxLodLevel = -1);
  

• 性能保护：反射不会为隐藏或覆盖相机渲染，确保隐藏/离屏相机使用 HideFlags。

总结

• 核心优化：通过减少屏幕空间、禁用动态光照和优化深度纹理，提升性能。
• 高开销功能：法线贴图、波浪和折射是性能消耗较大的功能，需谨慎启用。
• 移动设备：使用“Simple”着色模式，优化 UV 坐标设置。
• 平面反射：通过剔除掩码和单独渲染器，减少渲染成本。
• 脚本控制：支持全局切换平面反射设置，适应不同质量需求。