04｜灯光与阴影

/**
 * 辅助环境光：单独使用灯光时，确保场景不会全黑
 */
const helperAmbientLight = new THREE.AmbientLight(0xffffff, 0.1)

/**
 * 1a. AmbientLight — 环境光
 *
 * 最简单的灯光：全局均匀照亮所有物体，没有方向、没有阴影。
 * 常用于填充暗部，避免完全黑暗的区域。
 *
 * AmbientLight(color, intensity)
 *   color     — 灯光颜色，默认 0xffffff（白色）
 *   intensity — 灯光强度，默认 1
 */
const ambientLight = new THREE.AmbientLight(0xffffff, 0.3)

/**
 * 1b. HemisphereLight — 半球光
 *
 * 模拟自然环境光：天空颜色 + 地面颜色，从上下两个方向照射。
 * 比 AmbientLight 更有层次感，适合户外场景。
 *
 * HemisphereLight(skyColor, groundColor, intensity)
 *   skyColor    — 天空方向的颜色（上方）
 *   groundColor — 地面方向的颜色（下方）
 *   intensity   — 灯光强度
 */
const hemisphereLight = new THREE.HemisphereLight(0x87ceeb, 0x362907, 0.4)

/**
 * 1c. DirectionalLight — 方向光（平行光）
 *
 * 模拟太阳光：所有光线平行，从一个方向照射整个场景。
 * 可以投射阴影，阴影是正交投影（没有近大远小）。
 *
 * 注意：position 决定光照方向（从 position 指向 target，默认原点）
 * 但距离不影响光照强度（与 PointLight 不同）
 */
const directionalLight = new THREE.DirectionalLight(0xffffff, 1.0)
directionalLight.position.set(-5, 8, 5)

/**
 * 1d. PointLight — 点光源
 *
 * 从一个点向四面八方发光，像灯泡、蜡烛。
 * 距离越远越暗（遵循平方反比定律），可以投射阴影。
 *
 * PointLight(color, intensity, distance, decay)
 *   distance — 灯光最远照射距离（0 = 无限远）
 *   decay    — 衰减方式（2 = 真实物理衰减）
 */
const pointLight = new THREE.PointLight(0xff922b, 2, 15)
pointLight.position.set(3, 4, 2)

/**
 * 1e. SpotLight — 聚光灯
 *
 * 从一个点向一个方向发光，像手电筒、舞台灯。
 * 可以投射阴影，有锥形范围。
 *
 * SpotLight(color, intensity, distance, angle, penumbra, decay)
 *   angle    — 光锥角度（弧度），默认 Math.PI/3（60°）
 *   penumbra — 边缘柔和度（0~1），0 = 硬边，1 = 完全柔和
 */
const spotLight = new THREE.SpotLight(0xffff00, 20, 0, Math.PI / 6)
spotLight.position.set(0, 8, 0)

/**
 * 开启阴影需要三步：
 * 1. renderer.shadowMap.enabled = true — 渲染器开启阴影
 * 2. light.castShadow = true — 灯光投射阴影
 * 3. mesh.castShadow = true — 物体投射阴影
 * 4. mesh.receiveShadow = true — 物体接收阴影
 *
 * 灯光.castShadow — 灯光"有没有能力"投射阴影
 * 物体.castShadow — 这个物体"会不会"挡住光产生阴影
 * 地面.receiveShadow — 这个物体"能不能"显示别人投来的阴影
 */

// 渲染器：开启阴影
renderer.shadowMap.enabled = true

/**
 * shadowMap.type — 阴影贴图类型
 *
 * BasicShadowMap    — 最快，质量最差（硬边锯齿）
 * PCFShadowMap      — 中等质量，软边但可能有锯齿
 * PCFSoftShadowMap  — 高质量，柔和软边（推荐）
 * VSMShadowMap      — 另一种柔和阴影，但有局限性
 */
renderer.shadowMap.type = THREE.PCFSoftShadowMap

// 光源：设置 castShadow = true
directionalLight.castShadow = true

// 投射物：设置 castShadow = true
mesh.castShadow = true

// 接收面：设置 receiveShadow = true
ground.receiveShadow = true

directionalLight.shadow.mapSize.width = 1024
directionalLight.shadow.mapSize.height = 1024

/**
 * shadow.camera — 阴影的正交相机（定义阴影可见范围）
 *   near/far   — 阴影的最近/最远距离
 *   left/right/top/bottom — 阴影的上下左右边界
 *
 * ⚠️ 重要：物体超出这个范围就不会有阴影！
 */
directionalLight.shadow.camera.near = 0.5
directionalLight.shadow.camera.far = 50
directionalLight.shadow.camera.left = -10
directionalLight.shadow.camera.right = 10
directionalLight.shadow.camera.top = 10
directionalLight.shadow.camera.bottom = -10

/**
 * DirectionalLightHelper — 方向光辅助可视化
 * 显示方向光的位置和照射方向（用线段和矩形表示）
 * DirectionalLightHelper(light, size) — size: 辅助线的长度，默认 1
 */
const directionalHelper = new THREE.DirectionalLightHelper(directionalLight, 1)
scene.add(directionalHelper)

/**
 * SpotLightHelper — 聚光灯辅助可视化
 * 显示聚光灯的锥形范围和照射方向
 */
const spotHelper = new THREE.SpotLightHelper(spotLight)
scene.add(spotHelper)

/**
 * PointLightHelper — 点光源辅助可视化
 * 显示点光源的位置和照射范围（用球体表示）
 * PointLightHelper(light, sphereSize) — sphereSize: 辅助球体的半径，默认 1
 */
const pointHelper = new THREE.PointLightHelper(pointLight, 0.5)
scene.add(pointHelper)