# Tideglass Cove 案例

参考学习来源：Techartist（GitHub：iamtechartist）。

- [原仓库](https://github.com/iamtechartist/tideglass-cove)
- [在线 Demo](https://iamtechartist.github.io/tideglass-cove/)
- [固定版本](https://github.com/iamtechartist/tideglass-cove/tree/17f7d97a8b62d8410e70951d51dae134da3e02a8)
- [MIT 许可证，Copyright (c) 2026 Techartist](https://github.com/iamtechartist/tideglass-cove/blob/17f7d97a8b62d8410e70951d51dae134da3e02a8/LICENSE)

本文件是源码学习后整理的方法，不是作者公开的提示词。该版本使用原生 JS ES Modules、Three.js r185、WebGPURenderer 与 TSL；场景模型、材质细节和环境图均由程序构造。布局有明确参数，不是整座岛随机生成。

## 项目方法与适用场合

| 模块与源码 | 具体做法 | 复用条件 |
| --- | --- | --- |
| 地形 core.js / terrain.js | shore 曲线配合连续陆海高度，矩形营地遮罩与椭圆盆地；径向网格封闭侧壁和底面 | 固定轮廓的小型景观；复杂凹边界需换三角化 |
| 岩石 terrain.js / sculpt.js | 碎石用四层九边形截面；石拱用平滑并集、挖空、断裂与层理，再 Marching Tetrahedra | 石块与连通洞穴选择不同表示方式 |
| 植物 plants.js | 中心线树干、叶轴两侧小叶；windAnchor 与 windWeight 保存锚点和三级运动 | 相连部位必须共享整体位移 |
| 营地 camper.js | 带孔 Shape 挤出车壳，共有曲线边界生成车顶，门组原点放在铰链 | 窗洞与开门需进入几何和变换设计 |
| 水体 water.js / core.js | 垂向正弦波、镜像反射、颜色与深度折射、指数吸收、Fresnel、泡沫 | 平缓小水域；不等同于 FFT 海洋或真实流体 |
| 湿沙 core.js | 112×112 历史纹理，约 0.1 秒更新，接触覆盖衰减值 | 浪退后需要保留湿润状态 |
| 岩脚 terrain.js | 160×128 当前潮位截面距离图；潮位变化到阈值才重算 | 固定障碍物，避免逐片元遍历岩石 |
| 焦散 core.js | 太阳方向投影、Perlin 噪声窄带与亮斑，深度和遮蔽控制亮度 | 风格化提示；不求真实折射聚焦 |
| 鱼群 life.js / collision.js | 预测分离、转向限速、重复投影修正，椭球和胶囊避障 | 少量动物；大群体需空间索引 |
| 海豚 dolphins.js | 单调 Hermite 截面建模；七阶段动作；端点速度连接；前端入水二分 | 有准备、飞行、接触、恢复的事件动作 |
| 水花 splash.js | 480 水滴实例池、4 水膜槽位，线性阻力解析弹道 | 短暂可重叠特效，无需液体模拟 |
| 风格 main.js / core.js | 受控布局与色板，程序环境图和 PMREM，昼夜联动 | 先保持画面整体，再补细节 |
| 镜头 main.js | 33° 透视全景与两个近景，窄屏换机位，插值机位和目标 | 场景展示需兼顾剖面与纵向屏幕 |
| 性能 optimize.js / main.js | 按材质和角色合批，keepLocal 保留洞内遮罩，反射降尺寸和刷新频率 | 光学与小部件都增加绘制成本 |

## 共享函数的最小约定

```text
坐标：y 向上，地表在 x/z 平面采样。
shore(x) = -0.55 + 0.062x² + 0.17sin(0.85x) + 0.06sin(2.2x)
d = z-shore(x)      // 是沿 z 的偏移，不是精确最短距离
height(x,z)         // 干沙与海底共用，营地和盆地在此修改
wave(x,z,time)      // CPU 接触使用
waveNode(position)  // GPU 位移使用，共享波参数与时间
```

原项目的三组主波 `(kx,kz,omega,A)` 为 `(0.24,1.65,1.02,0.041)`、`(-0.46,3.05,1.37,0.020)`、`(7.1,5.3,-2.25,0.0048)`。加上潮位、遮蔽、拱下局部波和八槽涟漪，形成最终波高。移植时保持 CPU/GPU 所有项一致，不要仅复制三组正弦。

原项目的法线省略了遮蔽函数及部分局部波的空间导数；若改成更陡地形或更强浪，优先检查法线是否仍适用。

## 可直接改写的公式

```text
平滑遮罩：t=clamp((x-a)/(b-a),0,1)，s=t²(3-2t)
平滑并集：h=clamp(0.5+0.5*(B-A)/k,0,1)
          smin(A,B,k)=mix(B,A,h)-k*h*(1-h)
等值面边交点：t=f(A)/(f(A)-f(B))，P=A+t*(B-A)
湿度记忆：wet=max(contact,wetOld*exp(-dt/11))
水色透射：T=exp(-sigma*L)，sigma=(0.78,0.13,0.079)
路径控制点：B0=P0，B1=P0+V0*T/3，B2=P1-V1*T/3，B3=P1
参数过渡：value+=(target-value)*(1-exp(-k*dt))
```

这些常数按原场景选择。换尺寸后重新调波长、吸收距离、粒子速度和遮罩宽度；`11` 是湿度衰减时间常数。路径式中的 T 表示阶段时长，水色式中的 T 表示透射率。

## 复现顺序

1. 固定镜头和占位体，确认剖面与主体位置。
2. 建立连续地形、边界和共享水面采样。
3. 逐类生成石块、植物、房车，先检查连接与轮廓。
4. 用统一色板完成基础材质和环境，再分层添加水体光学。
5. 让动物避障和入水统一采样已有空间函数，再接水花事件。
6. 对照日间、黄昏、高低潮、镜头和窄屏，测量额外渲染成本。

在原 Demo 中可用 `layer=reflection/refraction/foam/sun` 分别观察水材质分量，`renderer=webgl` 强制 WebGL 2。它们是调试入口；运行后仍要确认场景完成加载再采集截图。