From 648b94e7417441cef1f4caec5b5da52b24eba594 Mon Sep 17 00:00:00 2001
From: Lenheart <947330670@qq.com>
Date: Wed, 1 Apr 2026 05:27:55 +0800
Subject: [PATCH] =?UTF-8?q?refactor(application):=20=E5=B0=86SquirrelVM?=
 =?UTF-8?q?=E6=89=A7=E8=A1=8C=E9=80=BB=E8=BE=91=E6=94=B9=E4=B8=BA=E5=90=AF?=
 =?UTF-8?q?=E5=8A=A8=E5=9B=9E=E8=B0=83?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

修改Application::run方法，接收一个启动回调函数参数，将原本直接执行的SquirrelVM::run逻辑改为由调用方通过回调控制。同时更新相关文档说明这一变更。
---
 .../include/frostbite2D/core/application.h       |  7 +++++--
 Frostbite2D/src/frostbite2D/core/application.cpp |  7 +++----
 Game/src/main.cpp                                |  6 +++++-
 docs/开发文档.md                                 | 16 +++++++++-------
 4 files changed, 22 insertions(+), 14 deletions(-)

diff --git a/Frostbite2D/include/frostbite2D/core/application.h b/Frostbite2D/include/frostbite2D/core/application.h
index f18efbe..708443a 100644
--- a/Frostbite2D/include/frostbite2D/core/application.h
+++ b/Frostbite2D/include/frostbite2D/core/application.h
@@ -57,6 +57,8 @@ struct AppConfig {
  */
 class Application {
 public:
+    using StartCallback = Function<void()>;
+
     /**
      * @brief 获取单例实例
      * @return 应用程序实例引用
@@ -86,8 +88,9 @@ public:
 
     /**
      * @brief 运行主循环
+     * @param callback 主循环开始前执行一次的启动回调
      */
-    void run();
+    void run(StartCallback callback);
 
     /**
      * @brief 请求退出
@@ -200,4 +203,4 @@ private:
 };
 
 
-}
\ No newline at end of file
+}
diff --git a/Frostbite2D/src/frostbite2D/core/application.cpp b/Frostbite2D/src/frostbite2D/core/application.cpp
index ddfb2aa..dc09c45 100644
--- a/Frostbite2D/src/frostbite2D/core/application.cpp
+++ b/Frostbite2D/src/frostbite2D/core/application.cpp
@@ -18,7 +18,6 @@
 #include <frostbite2D/platform/windows.h>
 #include <frostbite2D/resource/asset.h>
 #include <frostbite2D/resource/npk_archive.h>
-#include <frostbite2D/script/squirrel_vm.h>
 #include <frostbite2D/resource/pvf_archive.h>
 #include <frostbite2D/resource/sound_pack_archive.h>
 #include <frostbite2D/scene/scene.h>
@@ -181,7 +180,7 @@ bool Application::initCoreModules() {
   return true;
 }
 
-void Application::run() {
+void Application::run(StartCallback callback) {
   if (!initialized_) {
     SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "Application not initialized!");
     return;
@@ -204,8 +203,8 @@ void Application::run() {
   fpsTimer_ = 0.0f;
   currentFps_ = 0;
 
-  if (SquirrelVM::get().isInitialized()) {
-    SquirrelVM::get().run();
+  if (callback) {
+    callback();
   }
 
   mainLoop();
diff --git a/Game/src/main.cpp b/Game/src/main.cpp
index bcc0a28..4e1c1a2 100644
--- a/Game/src/main.cpp
+++ b/Game/src/main.cpp
@@ -230,7 +230,11 @@ int main(int argc, char **argv) {
   //   SDL_Log("File: %s", path.c_str());
   // }
 
-  app.run();
+  app.run([]() {
+    if (SquirrelVM::get().isInitialized()) {
+      SquirrelVM::get().run();
+    }
+  });
 
   SDL_Log("Application exited normally");
   app.shutdown();
diff --git a/docs/开发文档.md b/docs/开发文档.md
index bb23548..bdb8cc6 100644
--- a/docs/开发文档.md
+++ b/docs/开发文档.md
@@ -133,7 +133,7 @@ Nintendo Switch 平台使用 devkitPro/libnx/portlibs 工具链与库。
 3. 初始化脚本系统和资源归档
 4. 创建场景并压入 `SceneManager`
 5. 创建文本、动画、精灵、测试 Actor
-6. 调用 `Application::run()`
+6. 调用 `Application::run(callback)`
 7. 退出时调用 `Application::shutdown()`
 
 一个简化后的运行主线如下：
@@ -151,8 +151,8 @@ main
   -> 初始化 SquirrelVM / PvfArchive / NpkArchive / FontManager
   -> SceneManager::PushScene
   -> 创建 Sprite / TextSprite / Animation / Actor
-  -> Application::run
-     -> 可选执行 SquirrelVM::run
+  -> Application::run(callback)
+     -> 调用方提供的启动回调
      -> 主循环
         -> SDL_PollEvent
         -> SDL 事件转换为引擎事件
@@ -191,7 +191,7 @@ main
 需要注意的实现细节：
 
 - `initCoreModules()` 内部会先设置 `Asset` 工作目录，再做 SDL/窗口/渲染器初始化。
-- `run()` 会在主循环前检查 `SquirrelVM` 是否已初始化，如果已初始化则先执行 `SquirrelVM::run()`。
+- `run(callback)` 会在主循环前执行一次调用方传入的启动回调；`Application` 本身不再直接依赖 Squirrel。
 - `shutdown()` 中会清空场景栈、关闭渲染器、关闭音频系统、关闭归档系统，然后销毁窗口。
 
 ## 5.2 Window
@@ -485,9 +485,9 @@ SquirrelVM::get().setScriptDirectory("assets/scripts");
 SquirrelVM::get().init();
 ```
 
-随后在 `Application::run()` 中，如果 VM 已初始化，会先执行 `SquirrelVM::run()`。
+随后由调用方在 `Application::run(callback)` 的启动回调中决定是否执行 `SquirrelVM::run()`。
 
-这意味着脚本系统目前是“可选启动模块”，而不是 `Application::init()` 的强制步骤。
+这意味着脚本系统目前是“由上层控制的可选启动模块”，而不是 `Application::init()` 或 `Application::run()` 的强制步骤。
 
 ## 10. 音频系统
 
@@ -624,7 +624,9 @@ if (!app.init(config)) {
 auto scene = MakePtr<Scene>();
 SceneManager::get().PushScene(scene);
 
-app.run();
+app.run([]() {
+  // optional startup logic
+});
 app.shutdown();
 ```