教程编写与发布指南
目录和命名
课程正文放在 doc/shader-tutorial/，文件名为 01-hello-shader.md 这类“课次 + 主题”的 kebab-case。每课练习放在 exercises/01-hello-shader/，每题再建一个语义明确的独立目录，例如 01-red-triangle/。每题至少包含 index.html、main.js、shader.vert、shader.frag、README.md；无需某阶段的 Shader 时，可在 README 说明原因并省略该文件。
练习页面从 exercises/ 运行 http-server -p 1000 后，应能通过相对路径直接访问。标准深度的页面使用 ../../style.css、../../runtime.js、../../vendor/three.module.min.js，返回目录使用 ../../index.html。不要使用以 /doc/... 开头的绝对网站路径，也不要依赖网络 CDN。
exercises/_starter/00-runtime-check/ 是不计入题数的可运行样例。复制它到新练习目录后，替换标题、任务、Shader 与控件。templates/ 中的占位符文件是编写蓝本，不作为课程练习发布。
每课正文的解释顺序
- 问题与可见结果：说明日常开发场景、希望看到的画面，以及本课需要哪些前置知识。
- 图形学原理：写明坐标空间、向量或公式、适用范围，并把公式对应到画面变化。
- 数据经过的环节：JavaScript/Three.js → uniform 或 attribute → 顶点 Shader → varying 插值 → 片元 Shader → 屏幕。未使用的环节明确说明。
- 可运行最小示例：标出关键参数为何这样选，参数增减后会发生什么。
- 常规实践与取舍：说明何时用内建材质、ShaderMaterial、CPU 计算或后处理；兼顾资源所有权、精度、性能与设备限制。
- 故障与验证：列出一两个高频错误，给出可复现症状和排查顺序。
- 练习导航：按 ⭐ 到 ⭐⭐⭐⭐ 排列，链接已存在的练习目录。
综合实战可以减少概念性解释，但仍需列出输入、输出、运行方式与验收条件。
每题的三层任务
| 层级 | 内容 | 验收要求 |
|---|---|---|
| 基础 | 照着源码临摹并修改一个参数 | 有明确可见结果 |
| 改造 | 更换参数、场景或组合方式 | 说明预期与实际差异 |
| 创造 | 给出目标，让学习者自行实现 | 能用画面和数值判断完成 |
难度标记使用：⭐ 照着做、⭐⭐ 小改动、⭐⭐⭐ 综合应用、⭐⭐⭐⭐ 挑战。每道题的验收条件必须可观察或可测量；“效果更好”“帧率提升”“不同设备完全一致”不能脱离测试条件单独作为标准。踩坑题应同时给出稳定的修复路径。
Three.js 与 GLSL 约定
本仓库使用 Three.js 0.185.1。课程默认在现代浏览器的 WebGL2 路径运行；ShaderMaterial 可演示 GLSL ES 1.00 风格写法，但这不代表当前渲染器提供 WebGL1 后备。第 12 课涉及真正的 WebGL1 验证时，应提供独立测试入口并注明所用 API 与浏览器环境。
纹理颜色、线性光照与最终 sRGB 输出必须明确区分。ShaderMaterial 示例若直接输出颜色，应检查 Three.js 的 tone mapping 与 colorspace 处理。避免非法数学输入；展示故障时用可控开关，并在说明中标出其行为不可依赖。动画使用秒为单位的 dt，长期运行的时间精度问题另行说明。
runtime.js 只管理画布、相机、尺寸、渲染循环和仍挂在独立场景中的常见资源。练习自己的数学计算保留在 main.js 或 Shader 文件内。外部监听器、从场景提前移除的资源、共享缓存和 render target 应由练习显式清理。引入第三方模型、纹理或算法时记录来源和许可证。
发布前检查
- 从
exercises/执行http-server -p 1000，确认目录和新题都能打开。 - 检查控制台的 JavaScript 错误、Shader 编译日志、资源 404，以及桌面和窄屏的尺寸变化。
- 操作每个滑块、按钮、鼠标或触摸交互；核对 README 的预期画面与实际一致。
- 验证窗口缩放、动画暂停与页面离开时的资源释放。
- 性能题固定设备、画布尺寸、像素比、场景和预热时间后记录结果；draw call 不当作 GPU 时间。
- 在仓库根目录运行
yarn build，并检查git diff --check。