@kkarum/framework 2.3.17

package/utils/FWResLoader.ts

@@ -0,0 +1,139 @@
+export default class FWResLoader {
+  /**
+   * 通过任务系统按帧加载资源
+   */
+  public static threadLoad(options: {
+    assets: FW.AssetProperty[];
+    cb?: (progress: number) => void;
+  }): void {
+    const totalAssetsCount = options.assets.length;
+    let loadedAssetsCount = 0;
+
+    const task = FW.Entry.taskMgr.createTask({
+      frameBudget: 1 / 20,
+      tasksFrameCount: 5,
+      log: true,
+    });
+
+    const loadTask = async function* (): FW.TaskGenerator {
+      yield {
+        type: FW.EventDefine.TaskEvent.START,
+        progress: 0,
+        message: "资源加载开始",
+      };
+
+      for (const asset of options.assets) {
+        try {
+          await FW.Entry.resMgr.loadAsset({
+            bundle: asset.bundle,
+            path: asset.path,
+            type: asset.type,
+          });
+
+          loadedAssetsCount++;
+
+          const currentProgress = loadedAssetsCount / totalAssetsCount;
+
+          options.cb?.(currentProgress);
+
+          yield {
+            type: FW.EventDefine.TaskEvent.PROGRESS,
+            progress: currentProgress,
+            message: `资源加载中-> 资源路径:${asset.path} ,资源数:${loadedAssetsCount}/${totalAssetsCount},进度百分比:${currentProgress}`,
+          };
+        } catch (error) {
+          FW.Log.error(`加载资源失败: ${asset.path}`, error);
+          loadedAssetsCount++;
+          yield {
+            type: FW.EventDefine.TaskEvent.PROGRESS,
+            progress: loadedAssetsCount / totalAssetsCount,
+            message: `资源加载失败->: ${asset.path}`,
+          };
+        }
+      }
+
+      yield {
+        type: FW.EventDefine.TaskEvent.COMPLETE,
+        progress: 1,
+        message: "资源加载完成",
+      };
+    };
+
+    task.start(loadTask);
+  }
+
+  /**
+   * 加载bundle并收集预加载资源
+   */
+  public static async loadBundlesAndCollectAssets(
+    bundles: string[],
+  ): Promise<{
+    priorityAssets: FW.AssetProperty[];
+    backStageAssets: FW.AssetProperty[];
+  }> {
+    const priorityAssets: FW.AssetProperty[] = [];
+    const backStageAssets: FW.AssetProperty[] = [];
+
+    for (const bundleName of bundles) {
+      await FW.Entry.resMgr.loadBundle(bundleName);
+      const assetsConfig = FW.Entry.getComponent<FW.AssetConfig>(
+        `${bundleName}${FW.SystemDefine.FWBindTag.CONFIG}`,
+      );
+
+      if (!assetsConfig) continue;
+
+      const find = (o: any) => {
+        if (!o) return;
+        Object.keys(o).forEach((key) => {
+          const value: FW.AssetProperty | any = o[key];
+          const path: string = (value as any)?.path;
+          const priorityLoaded: boolean = (value as any)?.priorityLoaded;
+          if (path) {
+            (priorityLoaded ? priorityAssets : backStageAssets).push({
+              bundle: bundleName,
+              path,
+            });
+          } else if (typeof value === "object") {
+            find(value);
+          }
+        });
+      };
+
+      find((assetsConfig as any).preLoad);
+    }
+
+    return {
+      priorityAssets,
+      backStageAssets,
+    };
+  }
+
+  /**
+   * 通过线程任务加载资源并返回完成Promise
+   */
+  public static async loadAssetsWithThread(options: {
+    assets: FW.AssetProperty[];
+    cb?: (progress: number) => void;
+  }): Promise<void> {
+    const { assets, cb } = options;
+    if (!assets || assets.length === 0) {
+      cb?.(1);
+      return;
+    }
+
+    return new Promise<void>((resolve) => {
+      let loadedCount = 0;
+
+      FWResLoader.threadLoad({
+        assets,
+        cb: (progress: number) => {
+          cb?.(progress);
+          if (++loadedCount >= assets.length) {
+            resolve();
+          }
+        },
+      });
+    });
+  }
+}
+

package/utils/FWResLoader.ts.meta

@@ -0,0 +1,10 @@
+{
+  "ver": "1.1.0",
+  "uuid": "ca26ad6e-2aad-45c8-84b3-9a5052e47023",
+  "importer": "typescript",
+  "isPlugin": false,
+  "loadPluginInWeb": true,
+  "loadPluginInNative": true,
+  "loadPluginInEditor": false,
+  "subMetas": {}
+}

package/utils/FWTask.ts

@@ -0,0 +1,227 @@
+export default class FWTask implements FW.Task {
+  private taskQueue: FW.TaskGenerator[] = [];
+  private status: FW.SystemDefine.FWTaskStatus = FW.SystemDefine.FWTaskStatus.IDLE;
+  private isPaused = false;
+  private frameBudget: number;
+  private tasksFrameCount: number;
+  private taskCounter: number;
+  private totalTaskDuration: number;
+  private taskStartTime: string;
+  private log: boolean;
+  private performanceData: {
+    frameTimes: number[];
+    detailedFrames: FW.FrameDetail[];
+    events: FW.TaskEvent[];
+  };
+
+  readonly id: number;
+
+  constructor(options: FW.TaskOptions) {
+    this.id = options.taskId || Date.now();
+    this.taskCounter = 0;
+    this.totalTaskDuration = 0;
+    this.log = options.log ?? true;
+    this.frameBudget = options.frameBudget ?? 16;
+    this.tasksFrameCount = options.tasksFrameCount ?? 3;
+    this.performanceData = {
+      frameTimes: [],
+      detailedFrames: [],
+      events: [],
+    };
+  }
+
+  start(generator: FW.TaskFunction): FW.Task {
+    this.reset();
+    const taskId = `TaskId:${this.id}->TaskCounter${this.taskCounter++}`;
+    const gen = generator();
+    (gen as any).taskId = taskId;
+    this.taskQueue = [gen];
+    this.status = FW.SystemDefine.FWTaskStatus.RUNNING;
+    this.recordEvent({
+      type: FW.EventDefine.TaskEvent.START,
+      message: '任务开始',
+      taskId,
+    });
+    this.taskStartTime = FW.Entry.timeMgr.getTime();
+    this.executeFrame();
+    return this;
+  }
+
+  add(generator: FW.TaskFunction): FW.Task {
+    const taskId = `TaskId:${this.id}->TaskCounter${this.taskCounter++}`;
+    const gen = generator();
+    (gen as any).taskId = taskId;
+    this.taskQueue.push(gen);
+    this.recordEvent({
+      type: FW.EventDefine.TaskEvent.PROGRESS,
+      message: '新任务加入队列',
+      taskId,
+    });
+    if (this.status !== FW.SystemDefine.FWTaskStatus.RUNNING && !this.isPaused) {
+      this.status = FW.SystemDefine.FWTaskStatus.RUNNING;
+      this.executeFrame();
+    }
+    return this;
+  }
+
+  stop(): void {
+    this.taskCounter = 0;
+    this.taskQueue = [];
+    this.taskStartTime = '';
+    this.tasksFrameCount = 0;
+    this.totalTaskDuration = 0;
+  }
+
+  pause(): void {
+    this.isPaused = true;
+    this.status = FW.SystemDefine.FWTaskStatus.PAUSED;
+    this.recordEvent({
+      type: FW.EventDefine.TaskEvent.PAUSE,
+      message: '任务已暂停',
+    });
+  }
+
+  resume(): void {
+    if (this.taskQueue.length === 0) return;
+
+    this.isPaused = false;
+    this.status = FW.SystemDefine.FWTaskStatus.RUNNING;
+    this.recordEvent({
+      type: FW.EventDefine.TaskEvent.PROGRESS,
+      message: '任务已恢复',
+    });
+    this.executeFrame();
+  }
+
+  reset(): void {
+    this.taskQueue = [];
+    this.status = FW.SystemDefine.FWTaskStatus.IDLE;
+    this.isPaused = false;
+    this.performanceData = {
+      frameTimes: [],
+      detailedFrames: [],
+      events: [],
+    };
+  }
+
+  getStatus(): FW.SystemDefine.FWTaskStatus {
+    return this.status;
+  }
+
+  private async executeFrame(): Promise<void> {
+    if (this.isPaused || this.taskQueue.length === 0) return;
+
+    const frameStart = performance.now();
+    let processed = 0;
+    let frameTasks: FW.TaskExecutionRecord[] = [];
+    const startTime = FW.Entry.timeMgr.getTime();
+
+    while (
+      this.taskQueue.length > 0 &&
+      processed < this.tasksFrameCount &&
+      performance.now() - frameStart < this.frameBudget
+    ) {
+      const task = this.taskQueue[0];
+
+      const taskId = (task as any).taskId || `id-${processed}`;
+
+      const result = await task.next();
+
+      if (result.done) {
+        this.taskQueue.shift();
+        this.recordEvent({
+          type: FW.EventDefine.TaskEvent.COMPLETE,
+          progress: 1,
+          message: '任务完成',
+          taskId,
+        });
+      } else if (result.value) {
+        this.recordEvent({
+          ...result.value,
+          taskId,
+        });
+      }
+
+      frameTasks.push({
+        taskId: taskId,
+        result: result.done ? FW.EventDefine.TaskEvent.COMPLETE : FW.EventDefine.TaskEvent.YIELDED,
+        message: (result?.value as any)?.message,
+      });
+
+      processed++;
+    }
+
+    const frameTime = performance.now() - frameStart;
+    this.totalTaskDuration += frameTime;
+    this.performanceData.frameTimes.push(frameTime);
+    this.performanceData.detailedFrames.push({
+      frameStart: startTime,
+      frameEnd: FW.Entry.timeMgr.getTime(),
+      frameTime: frameTime,
+      tasksProcessed: processed,
+      tasks: frameTasks,
+      frameBudget: this.frameBudget,
+      frameBudgetUsed: frameTime / this.frameBudget,
+    });
+
+    if (this.taskQueue.length === 0) {
+      this.status = FW.SystemDefine.FWTaskStatus.COMPLETED;
+      this.recordEvent({
+        type: FW.EventDefine.TaskEvent.ALL_COMPLETE,
+        progress: 1,
+        message: '所有任务完成',
+      });
+      FW.Log.system('任务性能报告->', this.getPerformanceReport());
+      return;
+    }
+
+    requestAnimationFrame(async () => await this.executeFrame());
+  }
+
+  getPerformanceReport(): FW.TaskPerformanceReport {
+    const frameTimes = this.performanceData.frameTimes;
+    const avgFrameTime = frameTimes.reduce((sum, t) => sum + t, 0) / frameTimes.length || 0;
+
+    const frameDurations = [];
+    for (let i = 1; i < frameTimes.length; i++) {
+      frameDurations.push(frameTimes[i] - frameTimes[i - 1]);
+    }
+    const avgFrameDuration =
+      frameDurations.reduce((sum, d) => sum + d, 0) / frameDurations.length || 0;
+    const frameJitter =
+      frameDurations.reduce((sum, d) => sum + Math.abs(d - avgFrameDuration), 0) /
+        frameDurations.length || 0;
+
+    const budgetUsage =
+      this.performanceData.detailedFrames
+        .map((f) => f.frameBudgetUsed)
+        .reduce((sum, u) => sum + u, 0) / this.performanceData.detailedFrames.length || 0;
+
+    return {
+      startTime: this.taskStartTime,
+      endTime: FW.Entry.timeMgr.getTime(),
+      totalTasks: this.performanceData.detailedFrames.length,
+      totalFrames: frameTimes.length,
+      totalDuration: Number((this.totalTaskDuration / 1000).toFixed(2)),
+      avgFrameTime: avgFrameTime,
+      longestFrame: Math.max(...frameTimes),
+      shortestFrame: Math.min(...frameTimes),
+      frameJitter: frameJitter,
+      budgetUsage: budgetUsage,
+      timeline: this.performanceData.events.map((e) => ({
+        taskId: e.taskId,
+        type: e.type,
+        progress: e.progress,
+        message: e.message,
+      })),
+      frameDetails: [...this.performanceData.detailedFrames],
+    };
+  }
+
+  private recordEvent(event: FW.TaskEvent): void {
+    this.performanceData.events.push(event);
+    if (this.log) {
+      FW.Log.debug(`[任务${this.id}]`, event.message || `${event.type} ${event.progress}%`);
+    }
+  }
+}

package/utils/FWTask.ts.meta

@@ -0,0 +1,10 @@
+{
+  "ver": "1.1.0",
+  "uuid": "f84e273f-f5fb-4938-a45d-0d22c7cb05c1",
+  "importer": "typescript",
+  "isPlugin": false,
+  "loadPluginInWeb": true,
+  "loadPluginInNative": true,
+  "loadPluginInEditor": false,
+  "subMetas": {}
+}

package/utils/FWUtils.ts

@@ -0,0 +1,15 @@
+export default class FWUtils {
+  /**
+   * 从 URL 中获取完整文件名（含扩展名）
+   */
+  public getFileName(url: string): string {
+    try {
+      const urlObj = new URL(url);
+      const pathname = urlObj.pathname;
+      return pathname.substring(pathname.lastIndexOf('/') + 1);
+    } catch {
+      const cleanUrl = url.split('?')[0].split('#')[0];
+      return cleanUrl.substring(cleanUrl.lastIndexOf('/') + 1);
+    }
+  }
+}

package/utils/FWUtils.ts.meta

@@ -0,0 +1,10 @@
+{
+  "ver": "1.1.0",
+  "uuid": "b87b47df-cb7e-47d2-9999-0b18172676ca",
+  "importer": "typescript",
+  "isPlugin": false,
+  "loadPluginInWeb": true,
+  "loadPluginInNative": true,
+  "loadPluginInEditor": false,
+  "subMetas": {}
+}

package/utils.meta

@@ -0,0 +1,13 @@
+{
+  "ver": "1.1.3",
+  "uuid": "8f19d5ca-c389-4ba5-8a8c-6cd9e75a256f",
+  "importer": "folder",
+  "isBundle": false,
+  "bundleName": "",
+  "priority": 1,
+  "compressionType": {},
+  "optimizeHotUpdate": {},
+  "inlineSpriteFrames": {},
+  "isRemoteBundle": {},
+  "subMetas": {}
+}