chaseleantj/desktop-habitats
# Desktop Habitats 学习卡
一、一句话定位
一个用 Three.js/WebGL2 渲染的本地桌面水族馆，在 macOS 上实现交互式动态壁纸，鱼会响应光标、抢食，植物随水流摆动。
二、核心技术/架构亮点
1. 实时渲染：Three.js + WebGL2，自定义 GLSL 着色器、阴影和深度效果；一个统一水模型同时驱动植物、粒子、鱼群和光照。
2. 功耗自适应：根据桌面可见度、电源状态动态降帧（60/30/20fps），被完全遮挡、锁屏或低电量模式时彻底停止渲染。
3. macOS 壁纸集成：通过 install.sh 构建应用、安装登录项，并设置静态底图配合透明动画层；无需 Node 即可运行。
4. 纯本地/隐私友好：代码、纹理和库全部打包，无联网、无遥测、不监听键盘；仅读取光标和窗口位置估算可见度。
5. 可扩展场景结构：场景按 `scenes/riverscape/` 独立组织，含测试，未来可并列添加新环境。
三、适用场景与目标用户
- 想在 Mac 桌面养鱼、喜欢动态壁纸的趣味用户。
- 对 WebGL 实时渲染、功耗优化、macOS 壁纸应用实现感兴趣的开发者。
- 需要本地运行、注重隐私、不愿注册账号的个人工具爱好者。
四、可动手动作
- 试用：macOS 13+，装 Xcode 命令行工具后运行 `sh wallpaper/install.sh`；卸载用 `sh wallpaper/uninstall.sh`。
- 浏览器体验：Node 20+ 执行 `npm start`，访问 http://127.0.0.1:8080；点击水面喂食、Space 暂停、F 全屏。
- 开发调试：`npm run check` 和 `npm test` 跑语法/模拟/渲染预算测试；`diagnostics=1` 开启本地 benchmark。
- 借鉴思路：学习其"按可见度自动降帧/停渲染"的功耗控制策略；场景目录划分与无依赖静态服务器设计可复用。
五、学习优先级
- P0（本周动手）：跑通 `npm start` 浏览器版，读 `scenes/riverscape/src/` 中鱼群避让与竞食逻辑 —— 直接可玩且代码量适中，能快速领悟实时交互架构。
- P1（排期）：分析功耗自适应降帧实现，参考到自己的渲染项目——这是本项目的独特工程亮点。
- P2（观念了解）：macOS 壁纸应用打包/安装脚本原理——若不做原生开发，了解即可。
- P3（略读）：具体 GLSL 水草着色器数学——需要时再深入。⌂