English | 简体中文
纯前端 WebGL 水族箱 · boids 鱼群 + 实时水面涟漪
注：在线演示会直接加载默认鱼缸场景，支持鼠标点击/拖动水面触发涟漪。
涟漪鱼缸 是一个在浏览器里实时运行的 3D 水族箱，无需安装，打开网页就能玩。
整缸鱼用 boids 群体行为自主游动，会聚集、转向、互相避让；鱼游近水面或你点击、拖动水面，都会荡开真实传播的水波；珊瑚则在页面打开时从无到有、慢慢生长成形。所有效果都在 WebGL 里逐帧实时计算，构成一个会自我运转的小世界，而不是一段预录动画。
| 模块 | 功能描述 |
|---|---|
| 观赏鱼 | 金鱼使用 boids 行为自主游动，默认 3 条、最多 5 条，支持数量、速度和行为参数调节 |
| 水面 | 高度场水面模拟，鱼靠近水线、鼠标点击和鼠标拖动都可以触发涟漪 |
| 珊瑚 | 页面打开或刷新时从 0 个、0 尺寸逐步生长到默认状态，营造生命感 |
| 控制面板 | 右侧可折叠菜单，提供鱼群、水面、珊瑚、光照和显示效果等中文参数 |
| 多语言 | 可视化界面和 README 支持中文/英文切换 |
| 部署 | TypeScript 构建后的静态前端项目，可部署到 GitHub Pages |
这是一个 Vite + TypeScript + Three.js ESM 项目，不依赖后端服务。开发环境由 Vite 提供模块服务，生产构建会把脚本、样式和 GLB 资源统一输出到 dist/，可直接部署到 GitHub Pages。
项目当前有两个页面入口：
- 实际鱼缸应用：
/index.html，加载dist/src/main.js和dist/src/styles.css，包含真实 Three.js 场景与交互。 - UI 设计原型：
/designs/fish-education-aquarium/index.html，是独立的静态原型，不会驱动真实鱼缸场景。
提示：由于使用了原生 ES Module，浏览器在
file://协议下会拦截模块加载，因此需要通过本地 HTTP 服务器打开，不能直接双击index.html。
git clone https://github.com/SeanWong17/RippleAquarium.git
cd RippleAquariumnpm install
npm run build开发时使用 Vite 热更新，不需要手动复制 dist/。生产预览使用 npm run build 后的 npm run preview。
建议使用本地静态服务器运行：
npm run dev然后打开：
http://127.0.0.1:5213/index.html
构建并预览生产版本：
npm run build
npm run preview预览地址为 http://127.0.0.1:5213/index.html。请务必在 RippleAquarium 项目根目录 执行命令；页面更新后若仍看到旧内容，可使用带查询参数的地址强制刷新缓存，例如：
http://127.0.0.1:5213/index.html?ui-refresh=20260904
模拟逻辑（boids 转向、避障射线、空间网格）带有单元测试，使用 Node 内置 test runner：
npm test浏览器验收：
npm run test:e2e| 操作 | 效果 |
|---|---|
| 鼠标点击水面 | 产生一次涟漪 |
| 鼠标按住并拖动水面 | 沿拖动路径产生连续涟漪 |
| 右侧按钮 | 隐藏或显示参数面板 |
| 左上角语言按钮 | 在中文和英文界面之间切换 |
| 左上角 GitHub 图标 | 跳转到项目仓库 |
| 空格键 | 在外部环绕相机和鱼视角相机之间切换 |
1 / 2 |
显示或隐藏界面面板 |
| 模块 | 实现要点 |
|---|---|
| 渲染 | Three.js + WebGL，使用实例化渲染绘制主鱼群 |
| 鱼群行为 | 金鱼执行 boids 对齐、聚集、分离、避障和边界回避 |
| 性能 | 使用均匀空间网格做邻居查询，将鱼群行为从 O(n²) 降到近 O(n)，热路径复用对象避免每帧分配 |
| 鱼体运动 | 基于速度方向和姿态变化驱动金鱼朝向，并通过 Shader 驱动尾部摆动 |
| 水面涟漪 | 使用水面网格高度场传播波动，支持鼠标与鱼体触发 |
| 珊瑚生长 | 初始化阶段按统一成长进度驱动每个珊瑚从小到大生长 |
| 依赖 | Three.js 运行时与 addons 本地化到 vendor/；TypeScript 与类型声明作为开发依赖安装 |
| 国际化 | 轻量级前端 i18n 字典，界面文案可在中英文之间切换 |
RippleAquarium/
├── assets/ # README 演示动图
├── vendor/three/ # Node 单元测试使用的 Three.js 兼容资源
├── src/
│ ├── fish/ # 鱼模型加载、姿态、变形、实例化渲染与空间网格
│ ├── coral/ # 珊瑚模型资源
│ ├── fish-school-simulation.ts
│ ├── water-surface.ts
│ ├── coral-reef.ts
│ ├── clownfish-school.ts
│ ├── i18n.ts
│ └── main.ts
├── scripts/ # 旧资源复制脚本（迁移兼容）
├── test/ # 单元测试与 Playwright 浏览器验收
├── dist/ # Vite 构建产物（本地生成，不提交）
├── index.html
├── package.json
├── tsconfig.json
├── README.md
├── README.en.md
└── LICENSE
本项目是在以下开源/公开项目和模型资源基础上整合、改造和再设计得到的：
| 项目 | 借鉴内容 |
|---|---|
| vibe-motion/threejs-boids | 当前项目的鱼群行为基础，提供沙丁鱼式 boids 运动、Three.js 场景和实例化鱼群渲染的起点 |
| aisparkedu/ripple | 参考水面涟漪交互思路，并改造成当前鱼缸中的鼠标/鱼体触发水波效果 |
| Jaydeep-P/aquarium | 参考水族箱题材资源，借鉴珊瑚、小丑鱼和锦鲤等视觉元素方向；当前项目中珊瑚和小丑鱼模型资源来自该项目 |
| Bfbbr-SpongeBob Pineapple House | 鱼缸底部菠萝屋装饰模型，作者 SMF Features Developed From Cheryl Hill，Sketchfab 标注为 CC Attribution |
| NASB2 - SpongeBob and Patrick | 鱼缸底部角色装饰模型，作者 SMF Features Developed From Cheryl Hill，Sketchfab 标注为 CC Attribution |
如果你继续分发或部署本项目，请保留这些来源说明，并检查上游项目的许可证要求。
欢迎提交 Issue 或 Pull Request。
- Issues: Bug 反馈与功能建议
- Pull Requests: 提交改进
本项目使用 GNU Affero General Public License v3.0。
Made with ❤️ by seanwong17