three-base 2.0.137 → 2.0.145

package/Grass/Grass.d.ts

@@ -1,8 +1,8 @@
-import { Mesh, MeshLambertMaterial, PlaneGeometry } from "three";
+import { Mesh, MeshLambertMaterial, PlaneGeometry, Texture } from "three";
 export default class Grass extends Mesh {
     constructor();
     geometry: PlaneGeometry;
-    map: import("three").Texture;
+    map: Texture;
     material: MeshLambertMaterial;
     setSize(width: number, height: number): void;
 }

package/Grass/Grass.ts

@@ -0,0 +1,38 @@
+/*
+ * @Author: xiaosihan
+ * @Date: 2024-09-14 22:58:16
+ * @Last Modified by: xiaosihan
+ * @Last Modified time: 2024-09-14 23:20:39
+ */
+import { DoubleSide, MathUtils, Mesh, MeshLambertMaterial, PlaneGeometry, RepeatWrapping, Texture, TextureLoader, } from "three";
+import grassJPG from "./grass.jpg";
+// 草地Mesh
+export default class Grass extends Mesh {
+    constructor() {
+        super();
+    }
+    geometry: PlaneGeometry = (() => {
+        const geometry: PlaneGeometry = new PlaneGeometry(1, 1, 1, 1);
+        geometry.rotateX(MathUtils.degToRad(90));
+        return geometry;
+    })();
+    map: Texture = (() => {
+        const map: Texture = new TextureLoader().load(grassJPG);
+        map.wrapS = map.wrapT = RepeatWrapping;
+        map.repeat.set(1, 1);
+        return map;
+    })();
+    material: MeshLambertMaterial = (() => {
+        const material: MeshLambertMaterial = new MeshLambertMaterial({
+            map: this.map,
+            side: DoubleSide,
+        });
+        return material;
+    })();
+    // 设置尺寸
+    setSize(width: number, height: number): void {
+        this.scale.set(width, 1, height);
+        this.map.repeat.set(width, height);
+        // this.material.uniforms.size.value.set(width * 0.001, height * 0.001);
+    }
+}

package/Grass/index.d.ts

@@ -1 +1,2 @@
 export { default } from "./Grass";
+export * from "./Grass";

package/Grass/index.js

@@ -1 +1,2 @@
 export { default } from "./Grass";
+export * from "./Grass";

package/Grass/index.ts

@@ -0,0 +1,2 @@
+export { default } from "./Grass";
+export * from "./Grass";

package/Ground1/Ground1.d.ts

@@ -1,11 +1,10 @@
-import { BufferGeometry, Camera, Clock, Group, Material, Matrix4, Mesh, PlaneGeometry, Scene, ShaderMaterial, WebGLRenderer } from "three";
+import { Matrix4, Mesh, PlaneGeometry, ShaderMaterial } from "three";
+/** 装饰地板（随机渐变的深灰、不透明） */
 export default class Ground1 extends Mesh {
     tempMatrix: Matrix4;
     constructor();
     renderOrder: number;
     geometry: PlaneGeometry;
     setSize(width: number, height: number): void;
-    clock: Clock;
-    onBeforeRender: (renderer: WebGLRenderer, scene: Scene, camera: Camera, geometry: BufferGeometry, material: Material, group: Group) => void;
     material: ShaderMaterial;
 }

package/Ground1/Ground1.js

@@ -3,18 +3,43 @@
  * @Date: 2022-09-20 23:06:00
  * @Last Modified by: xiaosihan
  * @Last Modified time: 2024-08-17 02:16:56
+ *
+ * ⭐ 2026-09-20 皇上旨两改：
+ *   ① 原「科技感装饰地板」（三张格子贴图 + 紫色扩散动画 `#8D108E` + 格子线 `#263C56`）
+ *      → 深灰地板（每帧 3 次贴图采样、贴图平铺无各向异性 → 摩尔纹 + home 页卡顿元凶之一）。
+ *   ② 皇上再旨「地板就是**随机渐变**的深灰色、**不透明**」：
+ *      → 深灰区间内用 **value noise 做随机渐变**（无贴图、零采样，天然无摩尔纹）；
+ *      → `transparent: false`、alpha 恒 1（不透明）。
+ *
+ *   ⚠️ 不透明带来的变化与对策：
+ *   - 原靠「径向 alpha 淡出」柔化 500×500 地板的边界；不透明后改用**径向压暗**（乘 0.72~1.0）
+ *     弱化硬边 —— 若哪天皇上要「边界完全消失」，只能改回 alpha 淡出（即恢复 transparent）。
+ *   - 调试线（FPScontrol）两条口径分家（2026-09-25 皇上逐条定案）：**10 条射线辅助线开深度测试**，
+ *     正是靠本地板「不透明 + depthWrite:true」才挡得住埋进地里的那半截线；**8/9 两条回弹向量线
+ *     保持穿透显示**（关深度测试 + renderOrder:9999），照旧常显在最前。
+ *     ⚠️ 若哪天把本地板改回 transparent + depthWrite:false，射线辅助线会重新穿地浮出来。
+ *
+ *   ⚠️ 改动红线（这几条被别处依赖，**不许顺手改**）：
+ *   - `userData.fpsCollision = true`：FPScontrol 把地板当碰撞体（见 FPScontrol.ts 地面处理段）。
+ *   - `userData.aoFloor = true`：ssao_pass / debugExcludedShader 的「地板类半透明」特例按此标记走
+ *     （默认不写进可见深度图；物体落在地板上仍有接触 AO）。
+ *   - ShaderMaterial 必须含 logdepthbuf chunk；linear 输出必须 `#include <colorspace_fragment>`；
+ *     否则末端 sRGB 编码会二次编码 → 发白。
  */
-import { Clock, Color, DoubleSide, Matrix4, Mesh, PlaneGeometry, ShaderChunk, ShaderMaterial, Vector2, } from "three";
-import { degToRad } from "three/src/math/MathUtils";
-import floorMap1PNG from "./floorMap1.png";
-import floorMap2PNG from "./floorMap2.png";
-import floorMap3PNG from "./floorMap3.png";
-import threeLoader from "../threeLoader";
-// 装饰地板1
+import { Color, DoubleSide, Matrix4, Mesh, PlaneGeometry, ShaderChunk, ShaderMaterial } from "three";
+import { MathUtils } from "three";
+const { degToRad } = MathUtils;
+/** 装饰地板（随机渐变的深灰、不透明） */
 export default class Ground1 extends Mesh {
     tempMatrix = new Matrix4();
     constructor() {
         super();
+        // 标记为自己参与 FPS 碰撞检测
+        this.userData.fpsCollision = true;
+        // 标记为"地板类半透明"：参与世界空间 AO（物体落在它上需要接触 AO），
+        // 但透过它看到的物体（如从下方透视）仍照常显示描边/辉光、且不被它的接触 AO 乘黑。
+        // 见 three-base/pass/ssao_pass.ts 的复合守卫说明。
+        this.userData.aoFloor = true;
     }
     renderOrder = -1;
     geometry = (() => {
@@ -25,24 +50,15 @@ export default class Ground1 extends Mesh {
     // 设置尺寸
     setSize(width, height) {
         this.scale.set(width, 1, height);
-        // this.material.uniforms.size.value.set(width * 0.001, height * 0.001);
     }
-    clock = new Clock();
-    onBeforeRender = (renderer, scene, camera, geometry, material, group) => {
-        const elapsedTime = this.clock.getElapsedTime();
-        this.material.uniforms.speed.value = (elapsedTime * 0.1) % 0.6;
-        this.material.uniforms.speed2.value = ((elapsedTime * 0.1) % 0.6) - 0.1;
-    };
     material = new ShaderMaterial({
         uniforms: {
-            size: { value: new Vector2(10, 10) }, // 尺寸
-            speed: { value: 0 }, // 扩散值0-1
-            speed2: { value: 0 }, // 扩散值0-1
-            speedColor: { value: new Color("#8D108E") }, // 格子扩散颜色
-            lineColor: { value: new Color("#263C56") }, // 格子线的颜色
-            map1: { value: threeLoader.getTexture(floorMap1PNG) }, // 贴图纹理
-            map2: { value: threeLoader.getTexture(floorMap2PNG) }, // 贴图纹理
-            map3: { value: threeLoader.getTexture(floorMap3PNG) }, // 贴图纹理
+            /** 随机渐变的**暗端**深灰（three 的 Color 存 linear，末端 colorspace_fragment 编码回 sRGB） */
+            colorDark: { value: new Color("#2A2E33") },
+            /** 随机渐变的**亮端**深灰 */
+            colorLight: { value: new Color("#3D434B") },
+            /** 低频噪声格数（越大斑块越碎；9 → 500×500 地板上每块约 55m 的大块渐变） */
+            noiseScale: { value: 9 },
         },
         vertexShader: `
             ${ShaderChunk.common}
@@ -56,54 +72,42 @@ export default class Ground1 extends Mesh {
         `,
         fragmentShader: `
             ${ShaderChunk.logdepthbuf_pars_fragment}
-            uniform sampler2D map1;
-            uniform sampler2D map2;
-            uniform sampler2D map3;
-            uniform vec2 size;
-            uniform vec3 lineColor;
-            uniform float speed;
-            uniform float speed2;
-            uniform vec3 speedColor;
+            uniform vec3 colorDark;
+            uniform vec3 colorLight;
+            uniform float noiseScale;
             varying vec2 vUv;
-            void main() {
-
-                // 中心点
-                vec2 center = vec2(0.5,0.5);
-
-                vec4 map1Color = texture2D(map1, fract( vUv * size) );
-
-                // 格子中心渐变颜色
-                if(distance( vUv , center ) < speed){
-                    map1Color = mix(map1Color, vec4(speedColor, 1.0),  clamp((1.0 - (distance(distance( vUv , center ), speed) * 8.0) ) * map1Color.a, 0.0, 1.0 ) );
-                }
-
-                vec4 map2Color = texture2D(map2, fract( vUv * size) );
-
-                vec4 map3Color = texture2D(map3, fract( vUv * size) );
 
-                // 正方形装饰中心渐变颜色
-                if(distance( vUv , center ) < speed2){
-                    map3Color = mix(map3Color, map3Color * 3.0,  clamp((1.0 - (distance(distance( vUv , center ), speed) * 4.0) ) * map3Color.a, 0.0, 1.0 ) );
-                }
-
-                vec4 mapColor = mix(map1Color, map2Color, map2Color.a);
-
-                mapColor = mix(mapColor, map3Color, map3Color.a);
-
-                //添加背景色
-                mapColor = mix(mapColor, vec4(lineColor.rgb, 1.0 ), 1.0 - mapColor.a);
+            // 伪随机 hash → value noise：无贴图、零采样，天然没有平铺摩尔纹
+            float hash21(vec2 p) {
+                return fract(sin(dot(p, vec2(127.1, 311.7))) * 43758.5453123);
+            }
+            float valueNoise(vec2 p) {
+                vec2 i = floor(p);
+                vec2 f = fract(p);
+                vec2 u = f * f * (3.0 - 2.0 * f); // smoothstep 插值 → 柔和渐变，不是硬格子
+                return mix(mix(hash21(i), hash21(i + vec2(1.0, 0.0)), u.x),
+                           mix(hash21(i + vec2(0.0, 1.0)), hash21(i + vec2(1.0, 1.0)), u.x), u.y);
+            }
 
-                // 设置透明度
-                mapColor.a = 1.0 - (distance( vUv , center ) * 2.0);
+            void main() {
+                // 两个八度叠加：低频大块渐变 + 中频细节 → 深灰区间内的**随机渐变**
+                float n = valueNoise(vUv * noiseScale) * 0.65
+                        + valueNoise(vUv * noiseScale * 3.1) * 0.35;
+                vec3 col = mix(colorDark, colorLight, clamp(n, 0.0, 1.0));
 
-                gl_FragColor = mapColor;
+                // ⚠️ 不透明地板无法用 alpha 淡出边界 → 改用径向压暗弱化 500×500 的硬边
+                float edge = 1.0 - smoothstep(0.34, 0.5, distance(vUv, vec2(0.5, 0.5)));
+                col *= mix(0.72, 1.0, edge);
 
+                gl_FragColor = vec4(col, 1.0); // 不透明
                 ${ShaderChunk.logdepthbuf_fragment}
+                #include <colorspace_fragment>
             }
         `,
         depthTest: true,
         depthWrite: true,
-        transparent: true,
+        // ⭐ 皇上 2026-09-20 旨：地板**不透明**
+        transparent: false,
         side: DoubleSide,
     });
 }

package/Ground1/Ground1.ts

@@ -0,0 +1,114 @@
+/*
+ * @Author: xiaosihan
+ * @Date: 2022-09-20 23:06:00
+ * @Last Modified by: xiaosihan
+ * @Last Modified time: 2024-08-17 02:16:56
+ *
+ * ⭐ 2026-09-20 皇上旨两改：
+ *   ① 原「科技感装饰地板」（三张格子贴图 + 紫色扩散动画 `#8D108E` + 格子线 `#263C56`）
+ *      → 深灰地板（每帧 3 次贴图采样、贴图平铺无各向异性 → 摩尔纹 + home 页卡顿元凶之一）。
+ *   ② 皇上再旨「地板就是**随机渐变**的深灰色、**不透明**」：
+ *      → 深灰区间内用 **value noise 做随机渐变**（无贴图、零采样，天然无摩尔纹）；
+ *      → `transparent: false`、alpha 恒 1（不透明）。
+ *
+ *   ⚠️ 不透明带来的变化与对策：
+ *   - 原靠「径向 alpha 淡出」柔化 500×500 地板的边界；不透明后改用**径向压暗**（乘 0.72~1.0）
+ *     弱化硬边 —— 若哪天皇上要「边界完全消失」，只能改回 alpha 淡出（即恢复 transparent）。
+ *   - 调试线（FPScontrol）两条口径分家（2026-09-25 皇上逐条定案）：**10 条射线辅助线开深度测试**，
+ *     正是靠本地板「不透明 + depthWrite:true」才挡得住埋进地里的那半截线；**8/9 两条回弹向量线
+ *     保持穿透显示**（关深度测试 + renderOrder:9999），照旧常显在最前。
+ *     ⚠️ 若哪天把本地板改回 transparent + depthWrite:false，射线辅助线会重新穿地浮出来。
+ *
+ *   ⚠️ 改动红线（这几条被别处依赖，**不许顺手改**）：
+ *   - `userData.fpsCollision = true`：FPScontrol 把地板当碰撞体（见 FPScontrol.ts 地面处理段）。
+ *   - `userData.aoFloor = true`：ssao_pass / debugExcludedShader 的「地板类半透明」特例按此标记走
+ *     （默认不写进可见深度图；物体落在地板上仍有接触 AO）。
+ *   - ShaderMaterial 必须含 logdepthbuf chunk；linear 输出必须 `#include <colorspace_fragment>`；
+ *     否则末端 sRGB 编码会二次编码 → 发白。
+ */
+import { Color, DoubleSide, Matrix4, Mesh, PlaneGeometry, ShaderChunk, ShaderMaterial } from "three";
+import { MathUtils } from "three";
+const { degToRad } = MathUtils;
+
+/** 装饰地板（随机渐变的深灰、不透明） */
+export default class Ground1 extends Mesh {
+    tempMatrix: Matrix4 = new Matrix4();
+    constructor() {
+        super();
+        // 标记为自己参与 FPS 碰撞检测
+        this.userData.fpsCollision = true;
+        // 标记为"地板类半透明"：参与世界空间 AO（物体落在它上需要接触 AO），
+        // 但透过它看到的物体（如从下方透视）仍照常显示描边/辉光、且不被它的接触 AO 乘黑。
+        // 见 three-base/pass/ssao_pass.ts 的复合守卫说明。
+        this.userData.aoFloor = true;
+    }
+    renderOrder: number = -1;
+    geometry: PlaneGeometry = (() => {
+        const geo: PlaneGeometry = new PlaneGeometry(1, 1, 1, 1);
+        geo.rotateX(degToRad(-90));
+        return geo;
+    })();
+    // 设置尺寸
+    setSize(width: number, height: number): void {
+        this.scale.set(width, 1, height);
+    }
+    material: ShaderMaterial = new ShaderMaterial({
+        uniforms: {
+            /** 随机渐变的**暗端**深灰（three 的 Color 存 linear，末端 colorspace_fragment 编码回 sRGB） */
+            colorDark: { value: new Color("#2A2E33") },
+            /** 随机渐变的**亮端**深灰 */
+            colorLight: { value: new Color("#3D434B") },
+            /** 低频噪声格数（越大斑块越碎；9 → 500×500 地板上每块约 55m 的大块渐变） */
+            noiseScale: { value: 9 },
+        },
+        vertexShader: `
+            ${ShaderChunk.common}
+            ${ShaderChunk.logdepthbuf_pars_vertex}
+            varying vec2 vUv;
+            void main() {
+                vUv = uv;
+                gl_Position = projectionMatrix * modelViewMatrix * vec4( position, 1.0 );
+                ${ShaderChunk.logdepthbuf_vertex}
+            }
+        `,
+        fragmentShader: `
+            ${ShaderChunk.logdepthbuf_pars_fragment}
+            uniform vec3 colorDark;
+            uniform vec3 colorLight;
+            uniform float noiseScale;
+            varying vec2 vUv;
+
+            // 伪随机 hash → value noise：无贴图、零采样，天然没有平铺摩尔纹
+            float hash21(vec2 p) {
+                return fract(sin(dot(p, vec2(127.1, 311.7))) * 43758.5453123);
+            }
+            float valueNoise(vec2 p) {
+                vec2 i = floor(p);
+                vec2 f = fract(p);
+                vec2 u = f * f * (3.0 - 2.0 * f); // smoothstep 插值 → 柔和渐变，不是硬格子
+                return mix(mix(hash21(i), hash21(i + vec2(1.0, 0.0)), u.x),
+                           mix(hash21(i + vec2(0.0, 1.0)), hash21(i + vec2(1.0, 1.0)), u.x), u.y);
+            }
+
+            void main() {
+                // 两个八度叠加：低频大块渐变 + 中频细节 → 深灰区间内的**随机渐变**
+                float n = valueNoise(vUv * noiseScale) * 0.65
+                        + valueNoise(vUv * noiseScale * 3.1) * 0.35;
+                vec3 col = mix(colorDark, colorLight, clamp(n, 0.0, 1.0));
+
+                // ⚠️ 不透明地板无法用 alpha 淡出边界 → 改用径向压暗弱化 500×500 的硬边
+                float edge = 1.0 - smoothstep(0.34, 0.5, distance(vUv, vec2(0.5, 0.5)));
+                col *= mix(0.72, 1.0, edge);
+
+                gl_FragColor = vec4(col, 1.0); // 不透明
+                ${ShaderChunk.logdepthbuf_fragment}
+                #include <colorspace_fragment>
+            }
+        `,
+        depthTest: true,
+        depthWrite: true,
+        // ⭐ 皇上 2026-09-20 旨：地板**不透明**
+        transparent: false,
+        side: DoubleSide,
+    });
+}

package/Ground1/index.ts

@@ -0,0 +1 @@
+export { default } from "./Ground1";

package/MeshBase.d.ts

@@ -12,6 +12,7 @@ export default class MeshBase extends Group {
     };
     getSuffix(filename: string): string;
     reset(...object: Object3D[]): this;
+    protected ensureNormals(root: Object3D): void;
     loadModel(url: string | File | Array<File>, filename?: string): Promise<void>;
     frustumCulled: boolean;
     castShadow: boolean;

package/MeshBase.js

@@ -1,8 +1,15 @@
-import { AnimationMixer, Clock, Group, Vector3, } from "three";
+/*
+ * @Author: xiaosihan
+ * @Date: 2022-02-24 22:49:42
+ * @Last Modified by: xiaosihan
+ * @Last Modified time: 2025-06-25
+ */
+import { AnimationMixer, Clock, Group, Mesh, Vector3 } from "three";
 import threeUtils from "./threeUtils";
 import threeLoader from "./threeLoader";
 import * as SkeletonUtils from "three/examples/jsm/utils/SkeletonUtils";
 import { isString } from "lodash";
+import { dispatchCustomEvent } from "./EventMap";
 // 模型基类
 export default class MeshBase extends Group {
     constructor(url) {
@@ -27,13 +34,27 @@ export default class MeshBase extends Group {
         const match = filename.match(/\.([^\.]+)$/);
         return match ? match[1].toLowerCase() : "";
     }
-    // 重置子元素
     reset(...object) {
         threeUtils.dipose(this);
-        super.clear();
-        super.add(...object);
+        for (const child of this.children) {
+            child.parent = null;
+        }
+        for (const item of object) {
+            this.add(item);
+        }
         return this;
     }
+    // 兜底：为缺失顶点法线的几何体计算法线。
+    // 某些 glb/stl 模型仅有 POSITION 没有 NORMAL（如 public/models/bottle.glb），
+    // 会让法线 pass 输出零向量 -> AO 算出 NaN -> 整片被乘黑，且 PBR 金属材质无法正确受光 -> 发黑。
+    // 在加载完成后统一兜底，保证光照与 AO 都正确；已含法线的模型不受影响。
+    ensureNormals(root) {
+        root.traverse((obj) => {
+            if (obj instanceof Mesh && obj.geometry && !obj.geometry.getAttribute("normal")) {
+                obj.geometry.computeVertexNormals();
+            }
+        });
+    }
     // 如果url 是blob地址的话,就用suffix字段来制定模型的类型
     async loadModel(url, filename = "") {
         //获取模型文件的地址
@@ -63,6 +84,7 @@ export default class MeshBase extends Group {
                 }
                 return modelurl;
             }
+            return "";
         })();
         this.url = modelurl || "";
         if (!modelurl) {
@@ -84,6 +106,10 @@ export default class MeshBase extends Group {
         } while (MeshBase.loadModeling.get(modelurl));
         if (MeshBase.models.get(modelurl)) {
             const mesh = MeshBase.models.get(modelurl);
+            // 兜底：为缺失顶点法线的几何体补算法线。某些 glb/stl 模型只有 POSITION，
+            // 没有 NORMAL，会导致：① 法线 pass 输出零向量 -> AO 算出 NaN -> 整片被乘黑；
+            // ② PBR 金属材质无法正确光照 -> 颜色发黑。统一在加载后兜底，光照与 AO 都正确。
+            this.ensureNormals(mesh);
             // 判断是否有动画
             this.hasAnimation = mesh.animations.length > 0;
             if (this.hasAnimation) {
@@ -104,7 +130,7 @@ export default class MeshBase extends Group {
         await new Promise((resolve) => requestAnimationFrame(resolve));
         this.loaded = true;
         // 加载完成事件
-        this.dispatchEvent({ type: "loaded" });
+        dispatchCustomEvent(this, { type: "loaded" });
     }
     // 超出绘制区域时不绘制
     frustumCulled = false;
@@ -138,9 +164,8 @@ export default class MeshBase extends Group {
         // 等待加载完成
         await this.awaitLoaded();
         this.traverse((obj) => {
-            const mesh = obj;
-            if (mesh.isMesh) {
-                callback(mesh);
+            if (obj instanceof Mesh) {
+                callback(obj);
             }
         });
     }
@@ -172,11 +197,10 @@ export default class MeshBase extends Group {
         }
         // 深度应用属性
         this.traverse((obj) => {
-            const mesh = obj;
-            if (mesh.isMesh) {
-                mesh.frustumCulled = this.frustumCulled;
-                mesh.castShadow = this.castShadow;
-                mesh.receiveShadow = this.receiveShadow;
+            if (obj instanceof Mesh) {
+                obj.frustumCulled = this.frustumCulled;
+                obj.castShadow = this.castShadow;
+                obj.receiveShadow = this.receiveShadow;
             }
         });
         super.updateMatrix();