three-base 2.0.134 → 2.0.137

package/FPScontrol.d.ts

@@ -17,6 +17,7 @@ export default class FPScontrol extends EventDispatcher {
     inertia: boolean;
     scene: Scene;
     dev: boolean;
+    devCameraOffset: Vector3;
     thirdPerson: boolean;
     thirdPersonDistance: number;
     thirdPersonHeight: number;
@@ -24,18 +25,24 @@ export default class FPScontrol extends EventDispatcher {
     private _thirdPersonAngleX;
     private _prevThirdPerson;
     COLLIDE_VOLUME: number;
+    private readonly VERTICAL_RANGE;
     private readonly PUSH_DISTANCE;
     private readonly MAX_ITERATIONS;
+    private _tempQuat;
     private _raycaster;
     private _tempVec;
     private _tempVec2;
     private _tempVec3;
     private _tempVec4;
-    private readonly HORIZONTAL_RAY_DIRECTIONS;
-    private readonly VERTICAL_DOWN;
-    private readonly VERTICAL_UP;
+    private readonly _localRayOrigins;
+    private readonly _localRayDirs;
+    private _worldRayOrigins;
+    private _worldRayDirs;
     private _colliders;
+    private _collidersDirty;
+    private _colliderSceneVersion;
     private _getColliders;
+    markCollidersDirty(): void;
     playerCollider: Capsule;
     clock: Clock;
     prePlayerVelocity: Vector3;

package/FPScontrol.js

@@ -4,7 +4,7 @@
  * @Last Modified by: xiaosihan
  * @Last Modified time: 2024-11-07 21:57:39
  */
-import { BufferGeometry, Clock, EventDispatcher, Float32BufferAttribute, Group, Line, LineBasicMaterial, Mesh, InstancedMesh, Raycaster, Vector3, } from "three";
+import { BufferGeometry, Clock, EventDispatcher, Euler, Float32BufferAttribute, Group, Line, LineBasicMaterial, Mesh, InstancedMesh, Quaternion, Raycaster, Vector3, } from "three";
 import { Capsule } from "three/examples/jsm/math/Capsule";
 import { clamp, degToRad } from "three/src/math/MathUtils";
 import { acceleratedRaycast, computeBoundsTree } from "three-mesh-bvh";
@@ -34,7 +34,7 @@ export default class FPScontrol extends EventDispatcher {
     // 是否启用
     enable = false;
     GRAVITY = 30; // 重力
-    STEPS_PER_FRAME = 5; // 每帧碰撞计算的次数
+    STEPS_PER_FRAME = 2; // 每帧碰撞计算的次数
     speed = 1; // 速度
     camera;
     // 移动时是否保持惯性 由外部来配置
@@ -44,6 +44,8 @@ export default class FPScontrol extends EventDispatcher {
     // ========== dev / 第三人称 ==========
     // 开发模式：打开后显示射线可视化
     dev = false;
+    // 调试模式相机偏移（本地坐标系，Y=上，Z=后）
+    devCameraOffset = new Vector3(0, 2.5, 12.5);
     // 第三人称模式
     thirdPerson = false;
     // 第三人称参数：相机与第一人称位置的距离和高度偏移
@@ -55,12 +57,21 @@ export default class FPScontrol extends EventDispatcher {
     // 模式切换检测
     _prevThirdPerson = false;
     // ========== 射线碰撞检测 ==========
-    // 碰撞体积（胶囊体半径）
+    // 碰撞体积（对应 xsh-react-three 的 collideVolume，默认 3，此处缩放为 0.5）
+    // 用于水平射线的起点偏移和 far 值
     COLLIDE_VOLUME = 0.5;
-    // 推离步长（每次迭代推离的距离）
+    // 垂直碰撞范围 = 从 playerCollider.end（眼睛）到脚底的距离
+    // = capsule length + radius = (1.0 - 0.35) + 0.35 = 1.0
+    // 对应 xsh-react-three 中 collideVolume（=3）= 控制器到地面的距离
+    // xsh 中 far = collideVolume, 响应 = collideVolume - distance
+    // 此处 far = VERTICAL_RANGE, 响应 = VERTICAL_RANGE - distance
+    VERTICAL_RANGE = 1.0;
+    // 推离步长（每次迭代推离的距离，与 xsh-react-three 一致：0.03）
     PUSH_DISTANCE = 0.03;
-    // 最大迭代次数
+    // 最大迭代次数（与 xsh-react-three 一致：100）
     MAX_ITERATIONS = 100;
+    // 临时四元数（复用避免 GC）
+    _tempQuat = new Quaternion();
     // 射线检测器
     _raycaster = new Raycaster();
     // 临时向量（复用避免 GC）
@@ -68,20 +79,50 @@ export default class FPScontrol extends EventDispatcher {
     _tempVec2 = new Vector3();
     _tempVec3 = new Vector3();
     _tempVec4 = new Vector3();
-    // 水平射线方向（4 个 45° 斜向）
-    HORIZONTAL_RAY_DIRECTIONS = [
-        new Vector3(-1, 0, -1).normalize(), // 右→前
-        new Vector3(1, 0, -1).normalize(), // 左→前
-        new Vector3(1, 0, 1).normalize(), // 左→后
-        new Vector3(-1, 0, 1).normalize(), // 右→后
+    // ========== 射线定义（完全参考 xsh-react-three FPSControls.tsx 的 render 方法）==========
+    // 射线定义在局部空间，通过 Group3D(rotation={x: -euler.x}) 补偿 pitch
+    // 即射线只跟随 yaw 旋转，不跟随 pitch 俯仰
+    //
+    // xsh-react-three 原始布局（collideVolume=cv）：
+    //   rightToForwardRay: position={x:cv, y:0, z:0},  direction={x:-cv, y:0, z:-cv}
+    //   leftToForwardRay:  position={x:-cv, y:0, z:0}, direction={x:cv, y:0, z:-cv}
+    //   leftToBackRay:     position={x:-cv, y:0, z:0}, direction={x:cv, y:0, z:cv}
+    //   rightToBackRay:    position={x:cv, y:0, z:0},  direction={x:-cv, y:0, z:cv}
+    //   upTodwomRay:       position={x:0, y:0, z:0},   direction={y:-cv}
+    //   dwomToUpRay:       position={x:0, y:0, z:0},   direction={y:cv}
+    //
+    // 局部空间射线起点（索引 0-5）
+    _localRayOrigins = [
+        new Vector3(0, 0, 0), // 0: upTodwomRay（下射线）
+        new Vector3(0, 0, 0), // 1: dwomToUpRay（上射线）
+        new Vector3(1, 0, 0), // 2: rightToForwardRay 起点（右侧）
+        new Vector3(-1, 0, 0), // 3: leftToForwardRay 起点（左侧）
+        new Vector3(-1, 0, 0), // 4: leftToBackRay 起点（左侧）
+        new Vector3(1, 0, 0), // 5: rightToBackRay 起点（右侧）
     ];
-    // 垂直射线方向
-    VERTICAL_DOWN = new Vector3(0, -1, 0); // 上→下
-    VERTICAL_UP = new Vector3(0, 1, 0); // 下→上
+    // 局部空间射线方向（对应 direction prop，归一化前为 {x:±cv, y:0, z:±cv}）
+    // 归一化后与 xsh 的 clampLength(0,1) 效果一致
+    _localRayDirs = [
+        new Vector3(0, -1, 0), // 0: 下射线方向
+        new Vector3(0, 1, 0), // 1: 上射线方向
+        new Vector3(-1, 0, -1).normalize(), // 2: rightToForward → 指向 -X -Z（左前方）
+        new Vector3(1, 0, -1).normalize(), // 3: leftToForward → 指向 +X -Z（右前方）
+        new Vector3(1, 0, 1).normalize(), // 4: leftToBack → 指向 +X +Z（右后方）
+        new Vector3(-1, 0, 1).normalize(), // 5: rightToBack → 指向 -X +Z（左后方）
+    ];
+    // 世界空间射线起点（复用避免 GC）
+    _worldRayOrigins = [0, 1, 2, 3, 4, 5].map(() => new Vector3());
+    // 世界空间射线方向（复用避免 GC）
+    _worldRayDirs = [0, 1, 2, 3, 4, 5].map(() => new Vector3());
     // userData.fpsCollision === true 的碰撞体列表
     _colliders = [];
-    // 收集 fpsCollision 物体 + 首次构建 BVH（参照 ThreeMouse dispatchEvent）
+    // 缓存标记：场景变化时才重建碰撞体列表
+    _collidersDirty = true;
+    _colliderSceneVersion = 0;
+    // 收集 fpsCollision 物体 + 首次构建 BVH
     _getColliders() {
+        if (!this._collidersDirty)
+            return;
         this._colliders.length = 0;
         this.scene.traverseVisible((obj) => {
             if (obj.isMesh && obj.userData?.fpsCollision) {
@@ -92,6 +133,11 @@ export default class FPScontrol extends EventDispatcher {
                 this._colliders.push(obj);
             }
         });
+        this._collidersDirty = false;
+    }
+    // 标记碰撞体列表需要重建（外部在添加/删除碰撞体时调用）
+    markCollidersDirty() {
+        this._collidersDirty = true;
     }
     // 玩家胶囊碰撞体
     playerCollider = new Capsule(new Vector3(0, 0.35, 0), new Vector3(0, 1, 0), 0.35);
@@ -294,143 +340,209 @@ export default class FPScontrol extends EventDispatcher {
                     this.thirdPersonDistance;
             this.camera.lookAt(this.playerCollider.end);
         }
+        // dev 调试模式：在相机本地坐标系叠加偏移（向后上方）
+        if (this.dev && !this.thirdPerson) {
+            const offset = this.devCameraOffset.clone().applyQuaternion(this.camera.quaternion);
+            this.camera.position.add(offset);
+        }
         this.camera.rotation.x = clamp(this.camera.rotation.x, degToRad(-89), degToRad(89));
     };
-    // 碰撞检测：6 射线迭代推离（水平 4 + 垂直 2）
+    // 碰撞检测（完全参考 xsh-react-three FPSControls.tsx 的 computerPosition 方法）
+    //
+    // 射线布局对比（xsh-react-three 的 Raycaster 组件 → 本地实现）：
+    //   xsh: position prop → _localRayOrigins × collideVolume
+    //   xsh: direction prop → _localRayDirs（归一化后 = clampLength(0,1)）
+    //   xsh: raycaster.far = getDirection().length() → horizontalFar / verticalFar
+    //   xsh: Group3D rotation={x:-euler.x} → yawQuat（pitch 补偿）
+    //   xsh: getIntersetResult(positionIncremental) → worldPos = playerCollider.end + positionIncremental
+    //
+    // 6条射线完整数据（cv = collideVolume, vr = VERTICAL_RANGE）：
+    //   0 upTodwomRay:    origin=(0,0,0)×cv+worldPos, dir=(0,-1,0)×yaw, far=vr, 响应=vr-distance
+    //   1 dwomToUpRay:    origin=(0,0,0)×cv+worldPos, dir=(0,1,0)×yaw,  far=vr, 响应=faceNormal×0.01
+    //   2 rightToForward: origin=(cv,0,0)×yaw+worldPos, dir=(-1,0,-1).norm×yaw, far=cv√2
+    //   3 leftToForward:  origin=(-cv,0,0)×yaw+worldPos, dir=(1,0,-1).norm×yaw,  far=cv√2
+    //   4 leftToBack:     origin=(-cv,0,0)×yaw+worldPos, dir=(1,0,1).norm×yaw,   far=cv√2
+    //   5 rightToBack:    origin=(cv,0,0)×yaw+worldPos, dir=(-1,0,1).norm×yaw,   far=cv√2
     playerCollisions() {
         this.playerOnFloor = false;
-        // 收集 fpsCollision 物体
         this._getColliders();
-        // 累积位移增量（用于迭代推离）
         const positionIncremental = this._tempVec4.set(0, 0, 0);
-        // dev 模式：记录射线数据
-        const devRayData = this.dev ? [] : null;
-        let iterationCount = 0;
-        let hasCollision = true;
-        // ========== 迭代推离 ==========
-        while (hasCollision && iterationCount < this.MAX_ITERATIONS) {
-            hasCollision = false;
-            iterationCount++;
-            // 最后 2 次迭代记录调试数据
-            const recordDebug = this.dev && iterationCount >= this.MAX_ITERATIONS - 2;
-            // 获取胶囊体中心的世界位置
-            const centerPos = this._tempVec3
-                .addVectors(this.playerCollider.start, this.playerCollider.end)
-                .multiplyScalar(0.5);
-            // ========== 水平射线（4 根 45°）==========
-            for (let ri = 0; ri < this.HORIZONTAL_RAY_DIRECTIONS.length; ri++) {
-                const rayDir = this.HORIZONTAL_RAY_DIRECTIONS[ri];
-                // 起点：胶囊体中心向射线方向偏移 COLLIDE_VOLUME
-                const rayOrigin = this._tempVec2
-                    .copy(centerPos)
-                    .addScaledVector(rayDir, -this.COLLIDE_VOLUME);
-                this._raycaster.set(rayOrigin, rayDir.clone());
-                this._raycaster.far = this.COLLIDE_VOLUME * 2;
-                const hits = this._raycaster.intersectObjects(this._colliders, false);
-                if (recordDebug) {
-                    // 记录调试射线数据
-                    const farPoint = new Vector3().copy(rayOrigin).addScaledVector(rayDir, this.COLLIDE_VOLUME * 2);
-                    const hasHit = hits.length > 0 && hits[0].distance < this.COLLIDE_VOLUME * 2;
-                    devRayData.push({
-                        origin: rayOrigin.clone(),
-                        farPoint: hasHit ? hits[0].point.clone() : farPoint,
+        const collideVolume = this.COLLIDE_VOLUME;
+        const verticalRange = this.VERTICAL_RANGE;
+        let i = 0;
+        let goOnComputer = true;
+        // 调试数据：按射线索引存储（0=下, 1=上, 2-5=水平），只在第一次迭代记录
+        const devRayData = this.dev ? new Array(6).fill(null) : null;
+        let debugRecorded = !this.dev;
+        while (goOnComputer && i < 100) {
+            goOnComputer = false;
+            i++;
+            // 与 xsh: object3d.getWorldPosition() + positionIncremental 对应
+            const worldPos = this._tempVec3
+                .copy(this.playerCollider.end)
+                .add(positionIncremental);
+            // 与 xsh: Group3D rotation={x:-euler.x} 补偿 pitch → 只跟随 yaw
+            const yawQuat = this._tempQuat.setFromEuler(new Euler(0, this.camera.rotation.y, 0, "YXZ"));
+            // 将局部射线原点和方向转换为世界空间
+            for (let ri = 0; ri < 6; ri++) {
+                this._worldRayOrigins[ri]
+                    .copy(this._localRayOrigins[ri])
+                    .multiplyScalar(collideVolume)
+                    .applyQuaternion(yawQuat)
+                    .add(worldPos);
+                this._worldRayDirs[ri]
+                    .copy(this._localRayDirs[ri])
+                    .applyQuaternion(yawQuat)
+                    .normalize();
+            }
+            // far 值
+            const horizontalFar = collideVolume * Math.SQRT2;
+            const downFar = verticalRange;
+            const upFar = verticalRange;
+            // ========== 4 条水平射线（索引 2-5）==========
+            for (const ri of [2, 3, 4, 5]) {
+                this._raycaster.set(this._worldRayOrigins[ri], this._worldRayDirs[ri]);
+                this._raycaster.far = horizontalFar;
+                const intersets = this._raycaster.intersectObjects(this._colliders, false);
+                // 调试：第一次迭代记录射线数据
+                if (!debugRecorded) {
+                    const hasHit = intersets.length > 0;
+                    let closestDist = Infinity;
+                    let intersetPoint = null;
+                    if (hasHit) {
+                        for (const int of intersets) {
+                            const d = int.point.distanceTo(worldPos);
+                            if (d < closestDist) {
+                                closestDist = d;
+                                intersetPoint = int.point;
+                            }
+                        }
+                    }
+                    devRayData[ri] = {
+                        origin: this._worldRayOrigins[ri].clone(),
+                        farPoint: hasHit
+                            ? intersetPoint.clone()
+                            : this._worldRayOrigins[ri].clone().addScaledVector(this._worldRayDirs[ri], horizontalFar),
                         hit: hasHit,
-                    });
+                    };
                 }
-                if (hits.length > 0) {
-                    const hit = hits[0];
-                    // 推离向量：交点 → 当前位置，长度 PUSH_DISTANCE
-                    const pushVector = this._tempVec
-                        .copy(centerPos)
-                        .sub(hit.point)
-                        .setLength(this.PUSH_DISTANCE);
-                    // 累加推离量到位移增量
-                    positionIncremental.add(pushVector);
-                    // 继续循环，因为推离后可能还会碰撞
-                    hasCollision = true;
+                if (intersets.length > 0) {
+                    let interset = intersets[0];
+                    if (intersets.length > 1) {
+                        for (let j = 1; j < intersets.length; j++) {
+                            if (intersets[j].point.distanceTo(worldPos) < interset.point.distanceTo(worldPos)) {
+                                interset = intersets[j];
+                            }
+                        }
+                    }
+                    // 与 xsh: object3d.getWorldPosition().sub(interset.point).setLength(0.03) 一致
+                    this._tempVec
+                        .copy(worldPos)
+                        .sub(interset.point)
+                        .setLength(0.03);
+                    positionIncremental.add(this._tempVec);
+                    goOnComputer = true;
                 }
             }
-            // 重置 far（垂直射线各自设 far）
-            this._raycaster.far = Infinity;
-            // 垂直射线
-            // 向下 → 地面检测
-            const downRayOrigin = centerPos.clone();
-            this._raycaster.set(downRayOrigin, this.VERTICAL_DOWN.clone());
-            this._raycaster.far = this.COLLIDE_VOLUME + 0.5; // 适当延长检测距离
-            const downHits = this._raycaster.intersectObjects(this._colliders, false);
-            if (downHits.length > 0) {
-                const hit = downHits[0];
-                // 脚下 COLLIDE_VOLUME 内 = 站在地面
-                if (hit.distance < this.COLLIDE_VOLUME + 0.1) {
-                    this.playerOnFloor = true;
-                    // 如果正在下落，归零垂直速度
-                    if (this.playerVelocity.y < 0) {
-                        this.playerVelocity.y = 0;
-                    }
-                    // 上移站位
-                    const adjustY = this.COLLIDE_VOLUME + 0.1 - hit.distance;
-                    if (adjustY > 0) {
-                        positionIncremental.y += adjustY;
+            // ========== 向下射线（索引 0 = upTodwomRay）==========
+            this._raycaster.set(this._worldRayOrigins[0], this._worldRayDirs[0]);
+            this._raycaster.far = downFar;
+            let downIntersets = this._raycaster.intersectObjects(this._colliders, false);
+            // 调试：记录向下射线
+            if (!debugRecorded) {
+                const hasHit = downIntersets.length > 0;
+                let intersetPoint = null;
+                if (hasHit) {
+                    let closestDist = Infinity;
+                    for (const int of downIntersets) {
+                        const d = int.point.distanceTo(worldPos);
+                        if (d < closestDist) {
+                            closestDist = d;
+                            intersetPoint = int.point;
+                        }
                     }
                 }
-                else if (hit.distance < this.COLLIDE_VOLUME + 0.3) {
-                    // 接近地面缓冲
-                    this.playerOnFloor = true;
-                    if (this.playerVelocity.y < 0) {
-                        this.playerVelocity.y = 0;
+                devRayData[0] = {
+                    origin: this._worldRayOrigins[0].clone(),
+                    farPoint: hasHit
+                        ? intersetPoint.clone()
+                        : this._worldRayOrigins[0].clone().addScaledVector(this._worldRayDirs[0], downFar),
+                    hit: hasHit,
+                };
+            }
+            if (downIntersets.length > 0) {
+                let interset = downIntersets[0];
+                if (downIntersets.length > 1) {
+                    for (let j = 1; j < downIntersets.length; j++) {
+                        if (downIntersets[j].point.distanceTo(worldPos) < interset.point.distanceTo(worldPos)) {
+                            interset = downIntersets[j];
+                        }
                     }
                 }
-                hasCollision = true;
-            }
-            if (recordDebug) {
-                // 向下射线调试数据
-                const downFar = new Vector3().copy(downRayOrigin).addScaledVector(this.VERTICAL_DOWN, this.COLLIDE_VOLUME + 0.5);
-                const downHit = downHits.length > 0;
-                devRayData.push({
-                    origin: downRayOrigin.clone(),
-                    farPoint: downHit ? downHits[0].point.clone() : downFar,
-                    hit: downHit,
-                });
+                this.playerVelocity.y = 0;
+                positionIncremental.y += verticalRange - interset.distance;
+                this.playerOnFloor = true;
+                goOnComputer = true;
             }
-            // 向上 → 头顶碰撞
-            const upRayOrigin = centerPos.clone();
-            this._raycaster.set(upRayOrigin, this.VERTICAL_UP.clone());
-            this._raycaster.far = this.COLLIDE_VOLUME + 0.2;
-            const upHits = this._raycaster.intersectObjects(this._colliders, false);
-            if (upHits.length > 0) {
-                const hit = upHits[0];
-                // 头顶碰撞：归零向上速度 + 下移
-                if (hit.distance < this.COLLIDE_VOLUME + 0.2) {
-                    // 归零向上的速度
-                    if (this.playerVelocity.y > 0) {
-                        this.playerVelocity.y = 0;
+            // ========== 向上射线（索引 1 = dwomToUpRay）==========
+            this._raycaster.set(this._worldRayOrigins[1], this._worldRayDirs[1]);
+            this._raycaster.far = upFar;
+            let upIntersets = this._raycaster.intersectObjects(this._colliders, false);
+            // 调试：记录向上射线
+            if (!debugRecorded) {
+                const hasHit = upIntersets.length > 0;
+                let intersetPoint = null;
+                if (hasHit) {
+                    let closestDist = Infinity;
+                    for (const int of upIntersets) {
+                        const d = int.point.distanceTo(worldPos);
+                        if (d < closestDist) {
+                            closestDist = d;
+                            intersetPoint = int.point;
+                        }
                     }
-                    // 计算需要下移的距离
-                    const adjustY = this.COLLIDE_VOLUME + 0.2 - hit.distance;
-                    if (adjustY > 0) {
-                        positionIncremental.y -= Math.min(adjustY, 0.01); // 限制每次调整量
-                    }
-                    hasCollision = true;
                 }
+                devRayData[1] = {
+                    origin: this._worldRayOrigins[1].clone(),
+                    farPoint: hasHit
+                        ? intersetPoint.clone()
+                        : this._worldRayOrigins[1].clone().addScaledVector(this._worldRayDirs[1], upFar),
+                    hit: hasHit,
+                };
+                debugRecorded = true;
             }
-            if (recordDebug) {
-                // 向上射线调试数据
-                const upFar = new Vector3().copy(upRayOrigin).addScaledVector(this.VERTICAL_UP, this.COLLIDE_VOLUME + 0.2);
-                const upHit = upHits.length > 0;
-                devRayData.push({
-                    origin: upRayOrigin.clone(),
-                    farPoint: upHit ? upHits[0].point.clone() : upFar,
-                    hit: upHit,
-                });
+            if (upIntersets.length > 0) {
+                let interset = upIntersets[0];
+                if (upIntersets.length > 1) {
+                    for (let j = 1; j < upIntersets.length; j++) {
+                        if (upIntersets[j].point.distanceTo(worldPos) < interset.point.distanceTo(worldPos)) {
+                            interset = upIntersets[j];
+                        }
+                    }
+                }
+                this.playerVelocity.y = 0;
+                // 与 xsh: face.worldNormal.setLength(0.01) 一致
+                if (interset.face) {
+                    const faceNormal = interset.face.normal.clone();
+                    const worldQuat = new Quaternion();
+                    interset.object.getWorldQuaternion(worldQuat);
+                    faceNormal.applyQuaternion(worldQuat).setLength(0.01);
+                    positionIncremental.add(faceNormal);
+                }
+                else {
+                    positionIncremental.y -= 0.01;
+                }
+                goOnComputer = true;
             }
         }
         // ========== 更新调试射线（dev 模式）==========
         if (this.dev && devRayData) {
             this._initDebugLines();
-            for (let i = 0; i < devRayData.length && i < 6; i++) {
-                const data = devRayData[i];
-                // 跳过未收集到的（可能迭代次数不够）
-                this._updateDebugLine(i, data.origin, data.farPoint, data.hit);
+            for (let di = 0; di < 6; di++) {
+                const data = devRayData[di];
+                if (data) {
+                    this._updateDebugLine(di, data.origin, data.farPoint, data.hit);
+                }
             }
         }
         // 应用推离

package/ThreeBase.d.ts

@@ -78,13 +78,27 @@ export default class ThreeBase extends EventDispatcher {
     needRender: boolean;
     ssao: {
         enable: boolean;
+        debug: boolean;
         radius: number;
+        falloff: number;
         bias: number;
         intensity: number;
         sampleCount: number;
         blurRadius: number;
         strength: number;
     };
+    emissiveAO: {
+        enable: boolean;
+        debug: boolean;
+        radius: number;
+        falloff: number;
+        bias: number;
+        intensity: number;
+        sampleCount: number;
+        blurRadius: number;
+        strength: number;
+    };
+    emissiveRenderTarget: WebGLRenderTarget<Texture>;
     stopRender(): void;
     render(): void;
     private renderBindThis;

package/ThreeBase.js

@@ -16,6 +16,7 @@ import frosted_glass_pass from "./pass/frosted_glass_pass";
 import glow_pass from "./pass/glow_pass";
 import stroke_pass from "./pass/stroke_pass";
 import ssao_pass from "./pass/ssao_pass";
+import emissive_ao_pass from "./pass/emissive_ao_pass";
 import { copyShader } from "./shaders";
 import { baseTextureToRenderShader } from "./shaders/baseTextureToRenderShader";
 import threeLoader from "./threeLoader";
@@ -454,13 +455,33 @@ export default class ThreeBase extends EventDispatcher {
     // SSAO 配置
     ssao = {
         enable: false,
-        radius: 0.5,
-        bias: 0.025,
-        intensity: 1.5,
-        sampleCount: 16,
+        debug: false,
+        radius: 2.0, // 世界空间遮蔽半径
+        falloff: 5.0, // 世界空间衰减距离
+        bias: 0.3, // 切面距离阈值（过滤平坦面）
+        intensity: 1.0, // 遮蔽强度
+        sampleCount: 16, // 采样数
         blurRadius: 2.0,
         strength: 1.0,
     };
+    // Emissive AO 配置 - 发光物体照亮周围
+    emissiveAO = {
+        enable: false,
+        debug: false,
+        radius: 3.0, // 世界空间光照半径
+        falloff: 8.0, // 世界空间衰减距离
+        bias: 0.2, // 切面距离阈值
+        intensity: 1.0, // 光照强度
+        sampleCount: 16, // 采样数
+        blurRadius: 2.0,
+        strength: 1.0,
+    };
+    // 发光纹理渲染目标（用于存储发光物体的颜色）
+    emissiveRenderTarget = new WebGLRenderTarget(128, 128, {
+        minFilter: LinearFilter,
+        magFilter: LinearFilter,
+        format: RGBAFormat,
+    });
     // 停止渲染
     stopRender() {
         threeUtils.removeEventListener("requestAnimationFrame", this.renderBindThis);
@@ -530,6 +551,20 @@ export default class ThreeBase extends EventDispatcher {
         this.renderer.setRenderTarget(this.depthRenderTarget);
         this.renderer.clear();
         this.renderer.render(this.scene, camera);
+        // 如果启用 Emissive AO，渲染发光物体到专门的渲染目标
+        if (this.emissiveAO.enable) {
+            this.emissiveRenderTarget.setSize(this.size.x * Math.max(window.devicePixelRatio, this.minDevicePixelRatio), this.size.y * Math.max(window.devicePixelRatio, this.minDevicePixelRatio));
+            this.renderer.setRenderTarget(this.emissiveRenderTarget);
+            this.renderer.clear();
+            const emissiveScene = new Scene();
+            this.scene.traverseVisible((obj) => {
+                const material = obj.material;
+                if (material && material.emissive && material.emissiveIntensity > 0) {
+                    emissiveScene.add(obj.clone());
+                }
+            });
+            this.renderer.render(emissiveScene, camera);
+        }
         // 切回 baseRenderTarget，后处理 pass 需要把效果叠加到颜色渲染目标上
         this.renderer.setRenderTarget(this.baseRenderTarget);
         // 后处理特效渲染(描边,发光,颜色覆盖,bloom,磨砂玻璃)
@@ -538,21 +573,29 @@ export default class ThreeBase extends EventDispatcher {
             glow_pass(this.renderer, camera, obj, this.baseDepthTexture, Math.max(window.devicePixelRatio, this.minDevicePixelRatio));
             bloom_pass(this.renderer, camera, obj, this.baseRenderTarget, this.baseDepthTexture, Math.max(window.devicePixelRatio, this.minDevicePixelRatio));
         });
+        // 渲染场景到屏幕
         this.renderer.setRenderTarget(null);
         this.renderer.clear();
         this.renderRendererTarget(this.baseRenderTarget);
-        this.scene.traverseVisible((obj) => {
-            cover_pass(this.renderer, camera, obj, this.baseDepthTexture, Math.max(window.devicePixelRatio, this.minDevicePixelRatio));
-        });
-        // 一次性处理所有支持毛玻璃特效的对象
-        frosted_glass_pass(this.renderer, camera, this.scene, this.baseRenderTarget, this.baseDepthTexture, Math.max(window.devicePixelRatio, this.minDevicePixelRatio));
-        // SSAO 放在最后，叠加在所有特效之上
+        // SSAO 后处理（基于深度计算遮蔽，乘法叠加到屏幕）
         if (this.ssao.enable) {
             ssao_pass(this.renderer, camera, this.baseDepthTexture, Math.max(window.devicePixelRatio, this.minDevicePixelRatio), {
                 ...this.ssao,
                 cameraFar: camera.far,
             });
         }
+        // Emissive AO 后处理（发光物体照亮周围）
+        if (this.emissiveAO.enable) {
+            emissive_ao_pass(this.renderer, camera, this.baseDepthTexture, this.emissiveRenderTarget.texture, Math.max(window.devicePixelRatio, this.minDevicePixelRatio), {
+                ...this.emissiveAO,
+                cameraFar: camera.far,
+            });
+        }
+        this.scene.traverseVisible((obj) => {
+            cover_pass(this.renderer, camera, obj, this.baseDepthTexture, Math.max(window.devicePixelRatio, this.minDevicePixelRatio));
+        });
+        // 一次性处理所有支持毛玻璃特效的对象
+        frosted_glass_pass(this.renderer, camera, this.scene, this.baseRenderTarget, this.baseDepthTexture, Math.max(window.devicePixelRatio, this.minDevicePixelRatio));
         this.dispatchEvent({ type: "afterRender" });
     }
     renderBindThis = this.render.bind(this);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "three-base",
-  "version": "2.0.134",
+  "version": "2.0.137",
   "description": "three 3d three-base",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/"
@@ -45,6 +45,7 @@
     "vite": "*",
     "jszip": "^3.10.1",
     "html2canvas": "^1.4.1",
-    "three-mesh-bvh": "^0.8.3"
+    "three-mesh-bvh": "^0.8.3",
+    "@zumer/snapdom": "^1.9.14"
   }
 }

package/pass/emissive_ao_pass.d.ts

@@ -0,0 +1,13 @@
+import { Camera, DepthTexture, WebGLRenderer } from "three";
+export default function emissive_ao_pass(renderer: WebGLRenderer, camera: Camera, depthTexture: DepthTexture, emissiveTexture: any, devicePixelRatio: number, options: {
+    enable: boolean;
+    debug?: boolean;
+    radius?: number;
+    falloff?: number;
+    bias?: number;
+    intensity?: number;
+    sampleCount?: number;
+    blurRadius?: number;
+    strength?: number;
+    cameraFar?: number;
+}): void;