Refine Live2D loading behavior

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: LIlGG

README.md

@@ -72,13 +72,14 @@ TIPS 文件格式
     "hour": "6-7",               // 时间，小时为单位，需要为区间，例如 6-7 代表 6 点到 7 点之间
     "text": []                   // Live2d 消息框显示内容。为数组则随机选择一条显示
   ],
-  "message": {                   // 固定消息，通常代表特定事件
-    "default": [],               // 页面空闲时显示的消息
-    "console": [],               // 打开控制台时显示的消息
-    "copy": [],                  // 复制内容时显示的消息
-    "visibilitychange": []       // 多标签页，从其他标签页返回当前标签页时显示的消息
-  }
-}
+   "message": {                   // 固定消息，通常代表特定事件
+     "default": [],               // 页面空闲时显示的消息
+     "console": [],               // 打开控制台时显示的消息
+     "copy": [],                  // 复制内容时显示的消息
+     "loading": [],               // 模型加载时显示的消息
+     "visibilitychange": []       // 多标签页，从其他标签页返回当前标签页时显示的消息
+   }
+ }
 ```
 
 #### 1. 使用主题提供的 TIPS 文件（推荐）

packages/live2d/src/context/config-context.ts

@@ -27,6 +27,7 @@ export interface TipMessage extends ObjectAny {
   default?: string[] | string;
   console?: string[] | string;
   copy?: string[] | string;
+  loading?: string[] | string;
   visibilitychange?: string[] | string;
 }
 

packages/live2d/src/events/tip-events.ts

@@ -14,11 +14,9 @@ import {
   BEFORE_INIT_EVENT_NAME,
   type BeforeInitEvent,
 } from "@/live2d/events/before-init";
+import { MODEL_READY_EVENT_NAME } from "@/live2d/events/model-ready";
 import { dataWithinRange } from "@/live2d/helpers/dateWithinRange";
-import { getPluginTips } from "@/live2d/helpers/getPluginTips";
-import { loadFullTipsResource } from "@/live2d/helpers/loadFullTipsResource";
-import { loadTipsResource } from "@/live2d/helpers/loadTipsResource";
-import { mergeTips } from "@/live2d/helpers/mergeTips";
+import { loadMergedTips } from "@/live2d/helpers/loadMergedTips";
 import { sendMessage } from "@/live2d/helpers/sendMessage";
 import { timeWithinRange } from "@/live2d/helpers/timeWithinRange";
 import { isString } from "@/live2d/utils/isString";
@@ -29,6 +27,7 @@ import {
   hasWebsiteHome,
 } from "@/live2d/utils/util";
 let activeTipEvents: TipEventController | undefined;
+let isInitialModelReady = false;
 
 const _getWelComeMessage = (times: TipTime[]) => {
   if (hasWebsiteHome) {
@@ -216,16 +215,24 @@ const _userActionEvent = (
 class TipEventController {
   private readonly abortController = new AbortController();
   private readonly disposers: Array<() => void> = [];
+  private hasShownWelcome = false;
 
   constructor(
     private readonly config: Live2dConfig,
     private readonly tips: TipConfig,
   ) {}
 
-  start(): void {
+  start(modelReady: boolean): void {
     const { signal } = this.abortController;
     if (this.config.firstOpenSite) {
-      _welcomeEvent(this.tips.time);
+      if (modelReady) {
+        this.showWelcomeMessage();
+      } else {
+        window.addEventListener(MODEL_READY_EVENT_NAME, this.handleModelReady, {
+          signal,
+          once: true,
+        });
+      }
     }
 
     const userActionState = _userActionEvent(this.tips.message, signal);
@@ -266,52 +273,38 @@ class TipEventController {
     }
     this.disposers.length = 0;
   }
-}
 
-const _loadTips = async (config: Live2dConfig) => {
-  if (!config) {
-    return;
-  }
-  // 后台配置 tips，其中包含 mouseover 及 click 两种配置，以及单独配置的 message
-  const pluginTips = getPluginTips(config);
-  // 主题设置 tips，只会包含 mouseover 及 click 两种配置（会过滤掉其他配置）
-  const themeTipsResult = await loadTipsResource(config.themeTipsPath);
-  const themeTips: TipConfig = {
-    click: themeTipsResult?.click || [],
-    mouseover: themeTipsResult?.mouseover || [],
-    seasons: [],
-    time: [],
-    message: {},
+  private readonly handleModelReady = () => {
+    this.showWelcomeMessage();
   };
-  const fullOrDefaultTips = await _getFullOrDefaultTips(config);
-  // 合并三种 tips
-  return mergeTips({
-    pluginTips,
-    themeTips,
-    fullOrDefaultTips,
-  });
-};
 
-export const _getFullOrDefaultTips = async (
-  config: Live2dConfig,
-): Promise<TipConfig> => {
-  return loadFullTipsResource(config?.tipsPath, async () => {
-    return (await import("../libs/live2d-tips.json")).default;
-  });
-};
+  private showWelcomeMessage(): void {
+    if (this.hasShownWelcome) {
+      return;
+    }
+
+    this.hasShownWelcome = true;
+    _welcomeEvent(this.tips.time);
+  }
+}
 
 window.addEventListener(BEFORE_INIT_EVENT_NAME, async (event) => {
+  isInitialModelReady = false;
   const config = (event as BeforeInitEvent).detail.config;
   if (!config) {
     return;
   }
 
-  const tips = await _loadTips(config);
+  const tips = await loadMergedTips(config);
   if (!tips) {
     return;
   }
 
   activeTipEvents?.dispose();
   activeTipEvents = new TipEventController(config, tips);
-  activeTipEvents.start();
+  activeTipEvents.start(isInitialModelReady);
+});
+
+window.addEventListener(MODEL_READY_EVENT_NAME, () => {
+  isInitialModelReady = true;
 });

packages/live2d/src/helpers/loadMergedTips.ts

@@ -0,0 +1,47 @@
+import type { Live2dConfig, TipConfig } from "@/live2d/context/config-context";
+import { getPluginTips } from "@/live2d/helpers/getPluginTips";
+import { loadFullTipsResource } from "@/live2d/helpers/loadFullTipsResource";
+import { loadTipsResource } from "@/live2d/helpers/loadTipsResource";
+import { mergeTips } from "@/live2d/helpers/mergeTips";
+
+const mergedTipsCache = new WeakMap<Live2dConfig, Promise<TipConfig>>();
+
+const loadDefaultTips = async (): Promise<TipConfig> => {
+  return (await import("../libs/live2d-tips.json")).default;
+};
+
+const createThemeTips = async (config: Live2dConfig): Promise<TipConfig> => {
+  const themeTipsResult = await loadTipsResource(config.themeTipsPath);
+  return {
+    click: themeTipsResult?.click || [],
+    mouseover: themeTipsResult?.mouseover || [],
+    seasons: [],
+    time: [],
+    message: {},
+  };
+};
+
+const createMergedTips = async (config: Live2dConfig): Promise<TipConfig> => {
+  const pluginTips = getPluginTips(config);
+  const themeTips = await createThemeTips(config);
+  const fullOrDefaultTips = await loadFullTipsResource(
+    config?.tipsPath,
+    loadDefaultTips,
+  );
+  return mergeTips({
+    pluginTips,
+    themeTips,
+    fullOrDefaultTips,
+  });
+};
+
+export const loadMergedTips = (config: Live2dConfig): Promise<TipConfig> => {
+  const cachedTips = mergedTipsCache.get(config);
+  if (cachedTips) {
+    return cachedTips;
+  }
+
+  const nextTips = createMergedTips(config);
+  mergedTipsCache.set(config, nextTips);
+  return nextTips;
+};

packages/live2d/src/helpers/loadTipsResource.ts

@@ -80,7 +80,13 @@ const isTipMessage = (value: unknown): value is TipMessage => {
   if (!isRecord(value)) {
     return false;
   }
-  const optionalFields = ["default", "console", "copy", "visibilitychange"];
+  const optionalFields = [
+    "default",
+    "console",
+    "copy",
+    "loading",
+    "visibilitychange",
+  ];
   return optionalFields.every((field) => {
     const nextValue = value[field];
     return nextValue === undefined || isTipText(nextValue);

packages/live2d/src/libs/live2d-tips.json

@@ -407,6 +407,11 @@
 		],
 		"console": "哈哈，你打开了控制台，是想要看看我的小秘密吗？",
 		"copy": "你都复制了些什么呀，转载要记得加上出处哦！",
+		"loading": [
+			"稍等一下下哦，人家正在梳理小裙摆，马上就来陪你啦～",
+			"呜喵～正在努力赶来中，请再给人家一点点时间嘛！",
+			"正在元气加载中！等我整理好发饰，就出来和你贴贴啦～"
+		],
 		"visibilitychange": "哇，你终于回来了～"
 	}
 }