three-base 2.0.145 → 2.0.166

package/FPScontrol.d.ts

@@ -133,6 +133,26 @@ export default class FPScontrol extends EventDispatcher<FPScontrolEventTypeMap>
     readonly GRAVITY: number;
     STEPS_PER_FRAME: number;
     speed: number;
+    /**
+     * ⭐ 鼠标转视角的**除数**（越小越灵敏、越大越慢）—— 皇上 2026-10-09 旨「把写死的 /500 提成可调参数」。
+     * ⚠️ 它是**除数不是速度**：`rotation -= movement / lookSpeed`，所以
+     *   500 = 现状（皇上定的基线，一字未动）；拧小= 手更敏感，拧大 = 更「重」。
+     * ⚠️ 历史包袱：原为三处写死的字面量 500（第一人称 yaw/pitch + 第三人称 Y）。
+     *   本字段作为**唯一口径**，默认 500 ⇒ 数值与旧版逐位一致，不是行为变更。
+     */
+    lookSpeed: number;
+    /**
+     * ⭐ 水平转向反转（皇上 2026-10-09 旨「水平+俯仰全反」的可配置入口）。
+     * false = 常规（鼠标右移视角右转）；true = 反转（鼠标右移视角左转）。
+     * 与 `invertLookY` **各自独立**，可以只反一个、也可以两个都反。
+     */
+    invertLookX: boolean;
+    /**
+     * ⭐ 俯仰（pitch）反转：false = 常规（鼠标上移视角上抬）；true = 反转（鼠标上移视角下压）。
+     * ⚠️ 翻转**只影响观察方向**，不碰 `camera.rotation.order = "YXZ"` 与 pitch 的物理含义
+     *   ⇒ 碰撞射线仍旧只跟随 yaw（见 `_localRayOrigins` 那段），翻转后**贴墙/顶天花板判定不受影响**。
+     */
+    invertLookY: boolean;
     camera: Camera;
     inertia: boolean;
     /** 是否允许跳跃（空格触发）。false 时按空格不跳。默认 true */

package/FPScontrol.js

@@ -185,6 +185,26 @@ export default class FPScontrol extends EventDispatcher {
     GRAVITY = 10; // 重力（皇上定案：固定 10，不做编辑项 ⇒ readonly，写它编译就报错）
     STEPS_PER_FRAME = 2; // 每帧碰撞计算的次数
     speed = 1; // 速度
+    /**
+     * ⭐ 鼠标转视角的**除数**（越小越灵敏、越大越慢）—— 皇上 2026-10-09 旨「把写死的 /500 提成可调参数」。
+     * ⚠️ 它是**除数不是速度**：`rotation -= movement / lookSpeed`，所以
+     *   500 = 现状（皇上定的基线，一字未动）；拧小= 手更敏感，拧大 = 更「重」。
+     * ⚠️ 历史包袱：原为三处写死的字面量 500（第一人称 yaw/pitch + 第三人称 Y）。
+     *   本字段作为**唯一口径**，默认 500 ⇒ 数值与旧版逐位一致，不是行为变更。
+     */
+    lookSpeed = 500;
+    /**
+     * ⭐ 水平转向反转（皇上 2026-10-09 旨「水平+俯仰全反」的可配置入口）。
+     * false = 常规（鼠标右移视角右转）；true = 反转（鼠标右移视角左转）。
+     * 与 `invertLookY` **各自独立**，可以只反一个、也可以两个都反。
+     */
+    invertLookX = false;
+    /**
+     * ⭐ 俯仰（pitch）反转：false = 常规（鼠标上移视角上抬）；true = 反转（鼠标上移视角下压）。
+     * ⚠️ 翻转**只影响观察方向**，不碰 `camera.rotation.order = "YXZ"` 与 pitch 的物理含义
+     *   ⇒ 碰撞射线仍旧只跟随 yaw（见 `_localRayOrigins` 那段），翻转后**贴墙/顶天花板判定不受影响**。
+     */
+    invertLookY = false;
     camera;
     // 移动时是否保持惯性 由外部来配置
     inertia = true;
@@ -588,6 +608,46 @@ export default class FPScontrol extends EventDispatcher {
             digits: 2,
             desc: "第一人称移动速度倍率（面板与右侧表单同一个字段）",
         },
+        {
+            group: "移动与视角",
+            label: "视角灵敏度",
+            key: "lookSpeed",
+            min: 50,
+            max: 2000,
+            step: 10,
+            digits: 0,
+            desc: "鼠标转视角的**除数**（越小越灵敏、越大越慢）。500 = 旧版写死值，拧到它与旧版逐位一致。例：250 灵敏一倍、1000 慢一倍",
+        },
+        {
+            // ⚠️ 布尔字段按 0/1 数值旋钮挂：FpsParamSpec 的 min/max/step/digits 是数值型，
+            //   故用 get/set 把 boolean 换算成 0/1（面板上拧 1 = 开、0 = 关），字段本身仍是 boolean。
+            group: "移动与视角",
+            label: "水平反转",
+            key: "invertLookX",
+            min: 0,
+            max: 1,
+            step: 1,
+            digits: 0,
+            desc: "0 = 常规（鼠标右移视角右转）；1 = 反转（鼠标右移视角左转）。与「俯仰反转」各自独立，可只反一个",
+            get: (fps) => (fps.invertLookX ? 1 : 0),
+            set: (fps, v) => {
+                fps.invertLookX = v >= 0.5;
+            },
+        },
+        {
+            group: "移动与视角",
+            label: "俯仰反转",
+            key: "invertLookY",
+            min: 0,
+            max: 1,
+            step: 1,
+            digits: 0,
+            desc: "0 = 常规（鼠标上移视角上抬）；1 = 反转（鼠标上移视角下压）。⚠️ 只改观察方向，碰撞射线仍只跟随 yaw ⇒ 贴墙/顶天花板判定不受影响",
+            get: (fps) => (fps.invertLookY ? 1 : 0),
+            set: (fps, v) => {
+                fps.invertLookY = v >= 0.5;
+            },
+        },
         {
             group: "移动与视角",
             label: "跳跃初速度",
@@ -1235,17 +1295,24 @@ export default class FPScontrol extends EventDispatcher {
     };
     mousemove = (event) => {
         if (this.enable && this.isMousedown) {
+            // ⭐ 2026-10-09 皇上旨「把上下左右的交互反过来」：除数改读可写字段 `lookSpeed`（默认 500 = 旧值，一字未动），
+            //   并加两个**各自独立**的反转开关。写成 × (invert ? -1 : 1) 而不是改符号的写法，
+            //   是为了避免出现 `-=-` 这种双重取负的歧义。
+            //   ⚠️ 俯仰取反**不动** `_thirdPersonAngleX` 的 clamp 之外任何东西 —— 限位对称，翻转后依然 ±89°。
+            const s = this.lookSpeed;
+            const sx = this.invertLookX ? -1 : 1;
+            const sy = this.invertLookY ? -1 : 1;
             if (this.thirdPerson) {
                 // 第三人称：旋转轨道角
-                this._thirdPersonAngleY -= event.movementX / 500;
+                this._thirdPersonAngleY -= event.movementX / s * sx;
                 // 俯仰与第一人称同向：鼠标下移 → 视角下压 → 相机升高俯视（故用 +=）
-                this._thirdPersonAngleX += event.movementY / 500;
+                this._thirdPersonAngleX += event.movementY / s * sy;
                 this._thirdPersonAngleX = clamp(this._thirdPersonAngleX, degToRad(-89), degToRad(89));
             }
             else {
                 // 第一人称：直接旋转相机
-                this.camera.rotation.y -= event.movementX / 500;
-                this.camera.rotation.x -= event.movementY / 500;
+                this.camera.rotation.y -= event.movementX / s * sx;
+                this.camera.rotation.x -= event.movementY / s * sy;
             }
         }
     };

package/FPScontrol.ts

@@ -236,6 +236,26 @@ export default class FPScontrol extends EventDispatcher<FPScontrolEventTypeMap>
     readonly GRAVITY: number = 10; // 重力（皇上定案：固定 10，不做编辑项 ⇒ readonly，写它编译就报错）
     STEPS_PER_FRAME: number = 2; // 每帧碰撞计算的次数
     speed: number = 1; // 速度
+    /**
+     * ⭐ 鼠标转视角的**除数**（越小越灵敏、越大越慢）—— 皇上 2026-10-09 旨「把写死的 /500 提成可调参数」。
+     * ⚠️ 它是**除数不是速度**：`rotation -= movement / lookSpeed`，所以
+     *   500 = 现状（皇上定的基线，一字未动）；拧小= 手更敏感，拧大 = 更「重」。
+     * ⚠️ 历史包袱：原为三处写死的字面量 500（第一人称 yaw/pitch + 第三人称 Y）。
+     *   本字段作为**唯一口径**，默认 500 ⇒ 数值与旧版逐位一致，不是行为变更。
+     */
+    lookSpeed: number = 500;
+    /**
+     * ⭐ 水平转向反转（皇上 2026-10-09 旨「水平+俯仰全反」的可配置入口）。
+     * false = 常规（鼠标右移视角右转）；true = 反转（鼠标右移视角左转）。
+     * 与 `invertLookY` **各自独立**，可以只反一个、也可以两个都反。
+     */
+    invertLookX: boolean = false;
+    /**
+     * ⭐ 俯仰（pitch）反转：false = 常规（鼠标上移视角上抬）；true = 反转（鼠标上移视角下压）。
+     * ⚠️ 翻转**只影响观察方向**，不碰 `camera.rotation.order = "YXZ"` 与 pitch 的物理含义
+     *   ⇒ 碰撞射线仍旧只跟随 yaw（见 `_localRayOrigins` 那段），翻转后**贴墙/顶天花板判定不受影响**。
+     */
+    invertLookY: boolean = false;
     camera: Camera;
     // 移动时是否保持惯性 由外部来配置
     inertia: boolean = true;
@@ -642,6 +662,46 @@ export default class FPScontrol extends EventDispatcher<FPScontrolEventTypeMap>
             digits: 2,
             desc: "第一人称移动速度倍率（面板与右侧表单同一个字段）",
         },
+        {
+            group: "移动与视角",
+            label: "视角灵敏度",
+            key: "lookSpeed",
+            min: 50,
+            max: 2000,
+            step: 10,
+            digits: 0,
+            desc: "鼠标转视角的**除数**（越小越灵敏、越大越慢）。500 = 旧版写死值，拧到它与旧版逐位一致。例：250 灵敏一倍、1000 慢一倍",
+        },
+        {
+            // ⚠️ 布尔字段按 0/1 数值旋钮挂：FpsParamSpec 的 min/max/step/digits 是数值型，
+            //   故用 get/set 把 boolean 换算成 0/1（面板上拧 1 = 开、0 = 关），字段本身仍是 boolean。
+            group: "移动与视角",
+            label: "水平反转",
+            key: "invertLookX",
+            min: 0,
+            max: 1,
+            step: 1,
+            digits: 0,
+            desc: "0 = 常规（鼠标右移视角右转）；1 = 反转（鼠标右移视角左转）。与「俯仰反转」各自独立，可只反一个",
+            get: (fps) => (fps.invertLookX ? 1 : 0),
+            set: (fps, v) => {
+                fps.invertLookX = v >= 0.5;
+            },
+        },
+        {
+            group: "移动与视角",
+            label: "俯仰反转",
+            key: "invertLookY",
+            min: 0,
+            max: 1,
+            step: 1,
+            digits: 0,
+            desc: "0 = 常规（鼠标上移视角上抬）；1 = 反转（鼠标上移视角下压）。⚠️ 只改观察方向，碰撞射线仍只跟随 yaw ⇒ 贴墙/顶天花板判定不受影响",
+            get: (fps) => (fps.invertLookY ? 1 : 0),
+            set: (fps, v) => {
+                fps.invertLookY = v >= 0.5;
+            },
+        },
         {
             group: "移动与视角",
             label: "跳跃初速度",
@@ -1284,17 +1344,24 @@ export default class FPScontrol extends EventDispatcher<FPScontrolEventTypeMap>
     };
     mousemove = (event: MouseEvent): void => {
         if (this.enable && this.isMousedown) {
+            // ⭐ 2026-10-09 皇上旨「把上下左右的交互反过来」：除数改读可写字段 `lookSpeed`（默认 500 = 旧值，一字未动），
+            //   并加两个**各自独立**的反转开关。写成 × (invert ? -1 : 1) 而不是改符号的写法，
+            //   是为了避免出现 `-=-` 这种双重取负的歧义。
+            //   ⚠️ 俯仰取反**不动** `_thirdPersonAngleX` 的 clamp 之外任何东西 —— 限位对称，翻转后依然 ±89°。
+            const s = this.lookSpeed;
+            const sx = this.invertLookX ? -1 : 1;
+            const sy = this.invertLookY ? -1 : 1;
             if (this.thirdPerson) {
                 // 第三人称：旋转轨道角
-                this._thirdPersonAngleY -= event.movementX / 500;
+                this._thirdPersonAngleY -= event.movementX / s * sx;
                 // 俯仰与第一人称同向：鼠标下移 → 视角下压 → 相机升高俯视（故用 +=）
-                this._thirdPersonAngleX += event.movementY / 500;
+                this._thirdPersonAngleX += event.movementY / s * sy;
                 this._thirdPersonAngleX = clamp(this._thirdPersonAngleX, degToRad(-89), degToRad(89));
             }
             else {
                 // 第一人称：直接旋转相机
-                this.camera.rotation.y -= event.movementX / 500;
-                this.camera.rotation.x -= event.movementY / 500;
+                this.camera.rotation.y -= event.movementX / s * sx;
+                this.camera.rotation.x -= event.movementY / s * sy;
             }
         }
     };

package/MeshBase.js

@@ -127,7 +127,8 @@ export default class MeshBase extends Group {
                 this.reset(mesh.clone(true));
             }
         }
-        await new Promise((resolve) => requestAnimationFrame(resolve));
+        // ⭐ 2026-10-09 皇上旨：走 threeUtils 公共 rAF 链，不再另起独立 rAF 回调
+        await threeUtils.waitNextFrame();
         this.loaded = true;
         // 加载完成事件
         dispatchCustomEvent(this, { type: "loaded" });
@@ -147,7 +148,10 @@ export default class MeshBase extends Group {
                 if (this.resoles.length === 0) {
                     (async () => {
                         while (!this.loaded) {
-                            await new Promise((resolve) => requestAnimationFrame(resolve));
+                            //⭐ 2026-10-09 皇上旨「整条 rAF 链只走 threeUtils 一条」：
+                            //   原生 rAF 是**独立于主循环的另一个回调**，同一帧并行跑；
+                            //   模型多时（十几个 GLB 同时 awaitLoaded）每帧多十几个回调 ⇒ 卡顿。
+                            await threeUtils.waitNextFrame();
                         }
                         while (this.resoles.length > 0) {
                             const resole = this.resoles.pop();

package/MeshBase.ts

@@ -131,7 +131,8 @@ export default class MeshBase extends Group {
                 this.reset(mesh.clone(true));
             }
         }
-        await new Promise((resolve) => requestAnimationFrame(resolve));
+        // ⭐ 2026-10-09 皇上旨：走 threeUtils 公共 rAF 链，不再另起独立 rAF 回调
+        await threeUtils.waitNextFrame();
         this.loaded = true;
         // 加载完成事件
         dispatchCustomEvent(this, { type: "loaded" });
@@ -151,7 +152,10 @@ export default class MeshBase extends Group {
                 if (this.resoles.length === 0) {
                     (async () => {
                         while (!this.loaded) {
-                            await new Promise((resolve) => requestAnimationFrame(resolve));
+                            //⭐ 2026-10-09 皇上旨「整条 rAF 链只走 threeUtils 一条」：
+                            //   原生 rAF 是**独立于主循环的另一个回调**，同一帧并行跑；
+                            //   模型多时（十几个 GLB 同时 awaitLoaded）每帧多十几个回调 ⇒ 卡顿。
+                            await threeUtils.waitNextFrame();
                         }
                         while (this.resoles.length > 0) {
                             const resole = this.resoles.pop();

package/MktMesh/assetUrl.js

@@ -94,15 +94,16 @@ export function stripAssetHost(url, projName) {
             return url;
         // 去掉前导 `/`：得到真正的相对路径（`/a/b.jpg` → `a/b.jpg`；`/` → `""`）
         let path = rest.replace(/^\/+/, "");
-        // 上传目录前缀整段丢掉，只留文件名（query / fragment 原样跟在后面）
+        // 上传目录前缀整段丢掉，换成**项目名**（皇上 19:53 旨）；项目名缺失时退回「无项目名」的裸文件名。
+        // ⭐ 无论哪种形态，产出的地址都必须能被 `absAssetUrl` **原样还原**回真身 OSS 地址
+        //   （这是「运行期地址不动、只在导出 json 里临时改」的前提 —— 顶替必须是可逆的）。
         if (path === UPLOAD_DIR_PREFIX || path.startsWith(`${UPLOAD_DIR_PREFIX}/`)) {
             const tail = path.slice(UPLOAD_DIR_PREFIX.length + 1); // 越过 `three-base_upload/` ⇒ `panorama/x_0.jpg`
             const cut = tail.search(/[/?#]/); // 截到第一个分隔符（`/` `?` `#`）
             // ⚠️ slice(cut) 会把那个分隔符一起带上（`panorama/x.jpg` → `/x.jpg`）⇒ 要 slice(cut+1)
             const file = cut < 0 ? tail : tail.slice(cut + 1); // 文件名（含后面的 ?/#）
             const dir = safeSeg(projName ?? "");
-            path = dir ? `${dir}/${file}` : file;
-            return path;
+            return dir ? `${dir}/${file}` : file;
         }
         // ⭐ 幂等对称：`{项目名}/x.jpg` 这种**已顶替过**的形态（还原回绝对后再剥）要认出来，
         //   否则项目名段会被原样留着、形态跟首轮落盘的不一致 ⇒ 导出→导入→导出闭环对不上。
@@ -142,13 +143,23 @@ export function absAssetUrl(url, projName) {
     if (isLocalUrl(url) || !isPathLike(url))
         return url;
     const path = url.replace(/^\/+/, "");
+    // ⛔ 空路径（`/` 或 `/` 去掉斜杠后）不是文件名，别当裸文件名补上传目录（实测会补出 `host/three-base_upload/panorama/`）
+    if (path === "")
+        return `${MKT_ASSET_HOST}/`;
     const segs = path.split("/");
-    // 只在「恰好两段」且「首段不是已知站点目录」时，才按「项目名/文件名」还原
-    if (segs.length === 2 && !KNOWN_TOP_DIRS.includes(segs[0])) {
+    // ⭐ 情形①：**裸文件名**（`x_26.jpg`，无目录）—— 这是 `stripAssetHost` 无项目名时的落盘形态，
+    //   它必然来自上传目录 ⇒ 直接还原回 `three-base_upload/panorama/`。
+    //   ⛔ 漏了这一条就会补成 `https://host/x_26.jpg`（丢了上传目录）⇒ 线上取图 404（皇上 10-09 实测撞到）。
+    if (segs.length === 1)
+        return `${MKT_ASSET_HOST}/${UPLOAD_FULL_PREFIX}/${segs[0]}`;
+    // 情形②：`{项目名}/文件名`（两段、首段不是已知站点目录）⇒ 同样还原回上传目录。
+    //   判据与 `strip` 侧镜像，两边用同一把尺（`segs0IsProjectDir`）才能保证「顶替可逆」。
+    if (segs.length === 2 && segs0IsProjectDir(segs[0])) {
         const dir = safeSeg(projName ?? "");
         // 传了项目名就严格比它（最可靠）；没传才放宽到「非已知目录即可认」
         if (!dir || segs[0] === dir)
             return `${MKT_ASSET_HOST}/${UPLOAD_FULL_PREFIX}/${segs[1]}`;
     }
+    // 情形③：其余形态（`three-base/model/a.glb`、已是 `three-base_upload/…` 的）⇒ 原样补域名，不还原。
     return `${MKT_ASSET_HOST}/${path}`;
 }

package/MktMesh/assetUrl.ts

@@ -98,15 +98,16 @@ export function stripAssetHost(url: string, projName?: string): string {
         if (rest !== "" && !/^[/?#]/.test(rest)) return url;
         // 去掉前导 `/`：得到真正的相对路径（`/a/b.jpg` → `a/b.jpg`；`/` → `""`）
         let path = rest.replace(/^\/+/, "");
-        // 上传目录前缀整段丢掉，只留文件名（query / fragment 原样跟在后面）
+        // 上传目录前缀整段丢掉，换成**项目名**（皇上 19:53 旨）；项目名缺失时退回「无项目名」的裸文件名。
+        // ⭐ 无论哪种形态，产出的地址都必须能被 `absAssetUrl` **原样还原**回真身 OSS 地址
+        //   （这是「运行期地址不动、只在导出 json 里临时改」的前提 —— 顶替必须是可逆的）。
         if (path === UPLOAD_DIR_PREFIX || path.startsWith(`${UPLOAD_DIR_PREFIX}/`)) {
             const tail = path.slice(UPLOAD_DIR_PREFIX.length + 1); // 越过 `three-base_upload/` ⇒ `panorama/x_0.jpg`
             const cut = tail.search(/[/?#]/);                        // 截到第一个分隔符（`/` `?` `#`）
             // ⚠️ slice(cut) 会把那个分隔符一起带上（`panorama/x.jpg` → `/x.jpg`）⇒ 要 slice(cut+1)
             const file = cut < 0 ? tail : tail.slice(cut + 1);        // 文件名（含后面的 ?/#）
             const dir = safeSeg(projName ?? "");
-            path = dir ? `${dir}/${file}` : file;
-            return path;
+            return dir ? `${dir}/${file}` : file;
         }
         // ⭐ 幂等对称：`{项目名}/x.jpg` 这种**已顶替过**的形态（还原回绝对后再剥）要认出来，
         //   否则项目名段会被原样留着、形态跟首轮落盘的不一致 ⇒ 导出→导入→导出闭环对不上。
@@ -144,12 +145,20 @@ export function absAssetUrl(url: string, projName?: string): string {
     if (typeof url !== "string" || url === "") return url;
     if (isLocalUrl(url) || !isPathLike(url)) return url;
     const path = url.replace(/^\/+/, "");
+    // ⛔ 空路径（`/` 或 `/` 去掉斜杠后）不是文件名，别当裸文件名补上传目录（实测会补出 `host/three-base_upload/panorama/`）
+    if (path === "") return `${MKT_ASSET_HOST}/`;
     const segs = path.split("/");
-    // 只在「恰好两段」且「首段不是已知站点目录」时，才按「项目名/文件名」还原
-    if (segs.length === 2 && !KNOWN_TOP_DIRS.includes(segs[0])) {
+    // ⭐ 情形①：**裸文件名**（`x_26.jpg`，无目录）—— 这是 `stripAssetHost` 无项目名时的落盘形态，
+    //   它必然来自上传目录 ⇒ 直接还原回 `three-base_upload/panorama/`。
+    //   ⛔ 漏了这一条就会补成 `https://host/x_26.jpg`（丢了上传目录）⇒ 线上取图 404（皇上 10-09 实测撞到）。
+    if (segs.length === 1) return `${MKT_ASSET_HOST}/${UPLOAD_FULL_PREFIX}/${segs[0]}`;
+    // 情形②：`{项目名}/文件名`（两段、首段不是已知站点目录）⇒ 同样还原回上传目录。
+    //   判据与 `strip` 侧镜像，两边用同一把尺（`segs0IsProjectDir`）才能保证「顶替可逆」。
+    if (segs.length === 2 && segs0IsProjectDir(segs[0])) {
         const dir = safeSeg(projName ?? "");
         // 传了项目名就严格比它（最可靠）；没传才放宽到「非已知目录即可认」
         if (!dir || segs[0] === dir) return `${MKT_ASSET_HOST}/${UPLOAD_FULL_PREFIX}/${segs[1]}`;
     }
+    // 情形③：其余形态（`three-base/model/a.glb`、已是 `three-base_upload/…` 的）⇒ 原样补域名，不还原。
     return `${MKT_ASSET_HOST}/${path}`;
 }

package/PlaneWithHtml.js

@@ -9,6 +9,7 @@ import { Texture, DoubleSide, Mesh, MeshBasicMaterial, PlaneGeometry, Vector2 }
 import { MathUtils } from "three";
 const { degToRad } = MathUtils;
 import threeLoader from "./threeLoader";
+import threeUtils from "./threeUtils";
 // html 文本面板
 export default class PlaneWithHtml extends Mesh {
     constructor(html = "", backgroundColor = "#00000000") {
@@ -56,7 +57,8 @@ export default class PlaneWithHtml extends Mesh {
         this.material.map = texture;
         this.material.map.anisotropy = threeLoader.anisotropy;
         this.material.needsUpdate = true;
-        await new Promise(resolve => requestAnimationFrame(resolve));
+        // ⭐ 2026-10-09 皇上旨：走 threeUtils 公共 rAF 链，不再另起独立 rAF 回调
+        await threeUtils.waitNextFrame();
         this.visible = true;
         this.div.remove();
         this.dispatchEvent({ type: "loaded" });

package/PlaneWithHtml.ts

@@ -9,6 +9,7 @@ import { Texture, DoubleSide, Mesh, MeshBasicMaterial, PlaneGeometry, Vector2 }
 import { MathUtils } from "three";
 const { degToRad } = MathUtils;
 import threeLoader from "./threeLoader";
+import threeUtils from "./threeUtils";
 
 type HexColorString = `#${string}`;
 
@@ -62,7 +63,8 @@ export default class PlaneWithHtml extends Mesh {
         this.material.map = texture;
         this.material.map.anisotropy = threeLoader.anisotropy;
         this.material.needsUpdate = true;
-        await new Promise(resolve => requestAnimationFrame(resolve));
+        // ⭐ 2026-10-09 皇上旨：走 threeUtils 公共 rAF 链，不再另起独立 rAF 回调
+        await threeUtils.waitNextFrame();
         this.visible = true;
         this.div.remove();
         this.dispatchEvent({ type: "loaded" } as never);

package/SpriteWithHtml.js

@@ -7,6 +7,7 @@
 import { snapdom } from "@zumer/snapdom";
 import { Texture, Sprite } from "three";
 import threeLoader from "./threeLoader";
+import threeUtils from "./threeUtils";
 // html 文本面板
 export default class SpriteWithHtml extends Sprite {
     constructor(html = "", backgroundColor = "#00000000") {
@@ -36,7 +37,8 @@ export default class SpriteWithHtml extends Sprite {
         this.material.map.anisotropy = threeLoader.anisotropy;
         this.material.alphaTest = 0.1;
         this.material.needsUpdate = true;
-        await new Promise(resolve => requestAnimationFrame(resolve));
+        // ⭐ 2026-10-09 皇上旨：走 threeUtils 公共 rAF 链，不再另起独立 rAF 回调
+        await threeUtils.waitNextFrame();
         this.visible = true;
         this.div.remove();
         this.dispatchEvent({ type: "loaded" });

package/SpriteWithHtml.ts

@@ -8,6 +8,7 @@ import { snapdom } from "@zumer/snapdom";
 import { Texture, Sprite } from "three";
 import threeLoader from "./threeLoader";
 import type { SpriteWithHtmlEventMap } from "./EventMap";
+import threeUtils from "./threeUtils";
 
 type HexColorString = `#${string}`;
 
@@ -42,7 +43,8 @@ export default class SpriteWithHtml extends Sprite {
         this.material.map.anisotropy = threeLoader.anisotropy;
         this.material.alphaTest = 0.1;
         this.material.needsUpdate = true;
-        await new Promise(resolve => requestAnimationFrame(resolve));
+        // ⭐ 2026-10-09 皇上旨：走 threeUtils 公共 rAF 链，不再另起独立 rAF 回调
+        await threeUtils.waitNextFrame();
         this.visible = true;
         this.div.remove();
         this.dispatchEvent({ type: "loaded" } as never);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "three-base",
-  "version": "2.0.145",
+  "version": "2.0.166",
   "description": "A Three.js extension library providing common 3D components, animations, materials, and utilities",
   "author": "xiaosihan",
   "publishConfig": {

package/threeUtils.d.ts

@@ -11,6 +11,24 @@ declare class ThreeUtils extends EventDispatcher<ThreeUtilsEventTypeMap> {
     _center: Vector3;
     _clock: Clock;
     requestAnimationFrame(): void;
+    /**
+     * 等下一帧（**本库唯一的「等一帧」入口**，皇上 2026-10-09 旨）。
+     *
+     * ⛔ 为什么不再用原生 `await new Promise(r => requestAnimationFrame(r))`：
+     *   那是**独立于本类主循环的另一个 rAF 回调**，同一帧里与主循环并行跑 ⇒ 每帧多一次调度，
+     *   模型多时（如同时加载十几个 GLB，每个都 `awaitLoaded`）会积成每帧几十个回调 ⇒ 卡顿。
+     *   走本方法则**全部挂在本类这一条链上**（本类已把节流控到 30ms/帧），零额外调度。
+     *
+     * 典型用法（原三处`await new Promise(r => requestAnimationFrame(r))` 逐字替换即可）：
+     * ```ts
+     * import threeUtils from "three-base/threeUtils";
+     * await threeUtils.waitNextFrame();
+     * ```
+     */
+    waitNextFrame(): Promise<void>;
+    /** 结算所有 `waitNextFrame` 的挂起项（每帧由 `requestAnimationFrame` 调一次） */
+    private _nextFrameWaiters;
+    private _flushNextFrameWaiters;
     private _keepZoomDoms;
     /**
      *计算需要保持比例的元素

package/threeUtils.js

@@ -33,10 +33,44 @@ class ThreeUtils extends EventDispatcher {
         //执行一个计划任务
         let work = this.workList.splice(0, 1)[0];
         work && work();
+        // ⭐ 2026-10-09 皇上旨「整条 rAF 链只走 threeUtils 一条」：先结算本帧挂起的「等下一帧」，
+        //   再排下一拍 ⇒ 与 dispatchEvent 同拍派发，语义 =「下一帧的此刻」，与原生 rAF 同口径。
+        //   ⚠️ 必须在 dispatchEvent **之后**结算：挂在事件上的 resolve 期望的就是下一帧，别在同一帧里被清掉。
+        this._flushNextFrameWaiters();
         setTimeout(() => {
             this.requestAnimationFrame();
         }, 30 - this._clock.getDelta());
     }
+    /**
+     * 等下一帧（**本库唯一的「等一帧」入口**，皇上 2026-10-09 旨）。
+     *
+     * ⛔ 为什么不再用原生 `await new Promise(r => requestAnimationFrame(r))`：
+     *   那是**独立于本类主循环的另一个 rAF 回调**，同一帧里与主循环并行跑 ⇒ 每帧多一次调度，
+     *   模型多时（如同时加载十几个 GLB，每个都 `awaitLoaded`）会积成每帧几十个回调 ⇒ 卡顿。
+     *   走本方法则**全部挂在本类这一条链上**（本类已把节流控到 30ms/帧），零额外调度。
+     *
+     * 典型用法（原三处`await new Promise(r => requestAnimationFrame(r))` 逐字替换即可）：
+     * ```ts
+     * import threeUtils from "three-base/threeUtils";
+     * await threeUtils.waitNextFrame();
+     * ```
+     */
+    waitNextFrame() {
+        return new Promise((resolve) => {
+            this._nextFrameWaiters.push(resolve);
+        });
+    }
+    /** 结算所有 `waitNextFrame` 的挂起项（每帧由 `requestAnimationFrame` 调一次） */
+    _nextFrameWaiters = [];
+    _flushNextFrameWaiters() {
+        if (this._nextFrameWaiters.length === 0)
+            return;
+        // 先摘出来再逐个调：回调里可能又挂新的（新挂的要等下一帧，不在本拍结算）
+        const waiters = this._nextFrameWaiters;
+        this._nextFrameWaiters = [];
+        for (const resolve of waiters)
+            resolve();
+    }
     // 需要保持宽高比的元素列表
     _keepZoomDoms = [];
     /**

package/threeUtils.ts

@@ -50,11 +50,46 @@ class ThreeUtils extends EventDispatcher<ThreeUtilsEventTypeMap> {
         //执行一个计划任务
         let work = this.workList.splice(0, 1)[0];
         work && work();
+        // ⭐ 2026-10-09 皇上旨「整条 rAF 链只走 threeUtils 一条」：先结算本帧挂起的「等下一帧」，
+        //   再排下一拍 ⇒ 与 dispatchEvent 同拍派发，语义 =「下一帧的此刻」，与原生 rAF 同口径。
+        //   ⚠️ 必须在 dispatchEvent **之后**结算：挂在事件上的 resolve 期望的就是下一帧，别在同一帧里被清掉。
+        this._flushNextFrameWaiters();
         setTimeout(() => {
             this.requestAnimationFrame();
         }, 30 - this._clock.getDelta());
     }
 
+    /**
+     * 等下一帧（**本库唯一的「等一帧」入口**，皇上 2026-10-09 旨）。
+     *
+     * ⛔ 为什么不再用原生 `await new Promise(r => requestAnimationFrame(r))`：
+     *   那是**独立于本类主循环的另一个 rAF 回调**，同一帧里与主循环并行跑 ⇒ 每帧多一次调度，
+     *   模型多时（如同时加载十几个 GLB，每个都 `awaitLoaded`）会积成每帧几十个回调 ⇒ 卡顿。
+     *   走本方法则**全部挂在本类这一条链上**（本类已把节流控到 30ms/帧），零额外调度。
+     *
+     * 典型用法（原三处`await new Promise(r => requestAnimationFrame(r))` 逐字替换即可）：
+     * ```ts
+     * import threeUtils from "three-base/threeUtils";
+     * await threeUtils.waitNextFrame();
+     * ```
+     */
+    waitNextFrame(): Promise<void> {
+        return new Promise<void>((resolve) => {
+            this._nextFrameWaiters.push(resolve);
+        });
+    }
+
+    /** 结算所有 `waitNextFrame` 的挂起项（每帧由 `requestAnimationFrame` 调一次） */
+    private _nextFrameWaiters: Array<() => void> = [];
+
+    private _flushNextFrameWaiters(): void {
+        if (this._nextFrameWaiters.length === 0) return;
+        // 先摘出来再逐个调：回调里可能又挂新的（新挂的要等下一帧，不在本拍结算）
+        const waiters = this._nextFrameWaiters;
+        this._nextFrameWaiters = [];
+        for (const resolve of waiters) resolve();
+    }
+
     // 需要保持宽高比的元素列表
     private _keepZoomDoms: KeepZoomDom[] = [];