竹知了 3D 仿真 RiChenyv/bamboo-cicada-3d

竹知了 · 3D 仿真 🎋

把中国传统玩具「竹知了」（竹蝉）搬进浏览器的 3D 仿真网页游戏：一根竹签串着薄竹片，搓动竹签让竹片高速旋转切割空气，发出像夏天蝉鸣一样「哇呜——哇呜——」的声音。
转得越快，声音越响、音调越高；慢下来声音变闷、变低，直到自然消失。

全部资源本地化（无 CDN、无外部音频文件），打开即玩。

快速开始

node server.mjs # 默认端口 8333
node server.mjs 8080 # 自定义端口

浏览器打开 。同一 WiFi 下手机可直接访问终端打印的 LAN 地址。

需要现代浏览器（Chrome / Edge / Safari，支持 WebGL 与 ES Modules）。
零 npm 依赖：three.js 与 MediaPipe Hands 已 vendor 到 vendor/。

玩法

| 模式 | 规则 |
| 自由 | 随便搓，看转速、听声音 |
| 持久鸣叫 | 转速 ≥ 12 转/秒算「鸣叫」，连续鸣叫越久分越高；挑战 10 / 20 / 30 / 45 秒徽章 |
| 极速冲刺 | 20 秒内冲到最高转速，≥70 转/秒（4200 RPM）评 S 级 |

最好成绩保存在 localStorage，刷新不丢。

操作方式（多端）

- 🖱 鼠标：按住竹签/竹片快速来回拖动 = 搓动；按住空白处拖动 = 旋转视角；滚轮缩放
- 📱 触摸：同鼠标，单指拖动搓动 / 双指缩放旋转
- 📳 摇一摇：手机快速摇动给转子加冲击（iOS 首次需点「📳 摇一摇」授权）
- 📷 摄像头手势（MediaPipe Hands，本地模型）：双手反向移动 = 真实滚搓；单手快速来回划 = 划搓
- ⌨ 键盘：空格 持续滚搓 · R 停转重置 · M 静音
- ⚡ 「一键助转」按钮适合快速体验

仿真还原点

构造：竹签 + 薄竹片（中心孔、细长叶形、带螺旋桨扭角）+ 中心轴帽 + 叶尖红点，竹片与竹签固定成一体转子，与真实竹知了一致。

发声原理：竹片每转一圈两次「过风」，声音基频 = 2 × 转速。
Web Audio 实时合成（无任何录音）：双失谐锯齿波（丰富谐波）+ 随转速扫频的低通 + 每转一次的幅度调制（「哇呜」颤音）+ 叶片切风噪声 + 掌心搓动摩擦噪声，转速下降时音调与响度连续衰减至静音。参数平滑采用指数趋近，无爆音。

物理：搓动给转子角速度（棘轮打滑模型——反向搓动只传递部分力矩，来回搓也能提速，与真实玩法中「回程放松/单向轴承」一致）；松手后受空气阻力（高速主导，二次项）与轴承摩擦（低速主导，线性项）衰减，低速静摩擦停转，滑行曲线与真实玩具手感接近。

转速可视化：12 层残影实例（加法混合）+ 高速模糊光斑，转速一眼可辨。

运行与验证

npm test # Node 单元测试：物理衰减/棘轮/搓动识别/音频参数映射（16 项）
npm run verify # 真实浏览器 E2E：音频随转速变化、物理、交互、玩法、存档、残影、移动端布局（19 项）

test/verify.mjs 基于零依赖 CDP 客户端（test/cdp.mjs，Node ≥ 20 原生 WebSocket）驱动本机 Edge/Chrome headless。受限环境无法直接拉起浏览器时，可先手动启动：

msedge --headless=new --remote-debugging-port=9223 --user-data-dir= about:blank
CDP_CONNECT_ONLY=1 npm run verify

验证截图输出到 shots/（desk_idle / desk_mid / desk_fast / mobile）。

目录结构

index.html 页面骨架（importmap + HUD） css/style.css 响应式样式（桌面侧栏 / 移动端底部面板，深色竹林风） js/config.js 全局常数 + 转速→音频参数纯函数 js/physics.js 转子物理（搓动棘轮 + 空气/轴承阻力衰减） js/audio.js Web Audio 实时合成引擎 js/rub-detect.js 手势搓动识别（纯逻辑，可单测） js/rub.js 输入中枢（指针/键盘/摇一摇/手势桥接） js/gesture.js MediaPipe Hands 摄像头手势 js/game.js 挑战玩法 + 最好成绩（localStorage） js/toy.js 3D 场景（竹签/竹片/残影/光斑/灯光） js/textures.js 程序化竹材质（Canvas 生成） js/main.js 装配与主循环（含 window.__zzl 调试接口） vendor/three/ three.module.js + three.core.js + OrbitControls vendor/mp/ MediaPipe Hands（模型与 wasm） server.mjs 零依赖静态服务器 test/ 单元测试 + E2E 验证 + CDP 客户端