three-base 2.0.145 → 2.0.168

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[] = [];