feat(场景管理): 添加UIScene支持并重构场景管理器

refactor(渲染器): 优化相机切换时的渲染批处理

feat(调试工具): 新增游戏调试UI场景和九宫格面板组件

fix(动画系统): 跳过缺失的动画资源加载并记录日志

perf(资源加载): 使用BinaryFileStreamReader优化NPK文件解析

feat(地图系统): 支持多边形可行走区域调试显示

style(代码格式): 清理多余空格和统一文件编码

docs(注释): 补充关键类和方法的文档说明

test(启动跟踪): 添加启动过程性能跟踪工具

chore(依赖): 添加SDL2_ttf库支持

Game/include/character/CharacterAnimation.h

@@ -8,6 +8,7 @@
 #include <functional>
 #include <map>
 #include <string>
+#include <unordered_set>
 #include <vector>
 
 namespace frostbite2D {
@@ -44,6 +45,7 @@ private:
   Animation* GetPrimaryAnimation(const std::string& actionName) const;
   Animation* GetCurrentPrimaryAnimation() const;
   void RefreshRuntimeCallbacks();
+  bool shouldSkipMissingAnimation(const std::string& aniPath);
 
   void CreateAnimationBySlot(const std::string& actionName,
                              const std::string& slotName,
@@ -57,6 +59,8 @@ private:
   int direction_ = 1;
   ActionFrameFlagCallback actionFrameFlagCallback_;
   ActionEndCallback actionEndCallback_;
+  std::unordered_set<std::string> missingAnimationPaths_;
+  size_t skippedMissingAnimationCount_ = 0;
 };
 
 } // namespace frostbite2D

Game/include/common/GameDebugActor.h

@@ -0,0 +1,47 @@
+#pragma once
+
+#include <frostbite2D/2d/actor.h>
+
+namespace frostbite2D {
+
+class CharacterObject;
+class GameMap;
+class NineSliceActor;
+class TextSprite;
+
+/**
+ * @brief Reusable singleton debug actor for UI scenes.
+ */
+class GameDebugActor : public Actor {
+public:
+  static GameDebugActor& get();
+  static Ptr<GameDebugActor> getPtr();
+
+  GameDebugActor(const GameDebugActor&) = delete;
+  GameDebugActor& operator=(const GameDebugActor&) = delete;
+
+  bool AttachToScene(Scene* scene);
+  bool AttachToParent(Actor* parent);
+  void DetachFromParent();
+
+  void SetDebugMap(GameMap* map);
+  void SetTrackedCharacter(CharacterObject* character);
+  void ClearDebugContext();
+
+  void OnUpdate(float deltaTime) override;
+
+private:
+  void initOverlay();
+  void updateOverlay();
+  void setOverlayVisible(bool visible);
+
+  GameDebugActor();
+  ~GameDebugActor() override = default;
+
+  GameMap* debugMap_ = nullptr;
+  CharacterObject* trackedCharacter_ = nullptr;
+  RefPtr<NineSliceActor> background_;
+  RefPtr<TextSprite> coordText_;
+};
+
+} // namespace frostbite2D

Game/include/map/GameDataLoader.h

@@ -63,7 +63,7 @@ struct MapConfig {
   std::vector<BackgroundAnimationConfig> backgroundAnimations;
   std::vector<MapAnimationConfig> mapAnimations;
   std::vector<std::string> soundIds;
-  std::vector<Rect> virtualMovableAreas;
+  std::vector<Vec2> virtualMovablePolygon;
   std::vector<Rect> townMovableAreas;
   std::vector<MoveAreaTarget> townMovableAreaTargets;
 };

Game/include/map/GameMap.h

@@ -49,6 +49,7 @@ public:
   Rect GetMovablePositionArea(size_t index) const;
 
   int GetBackgroundRepeatWidth() const { return backgroundRepeatWidth_; }
+  bool IsDebugModeEnabled() const { return debugMode_; }
 
 private:
   /// 初始化固定图层。图层名字与 DNF 地图层概念保持一致。
@@ -75,14 +76,14 @@ private:
   /// bottom 层里的专用地板容器，固定放在该层最底部，避免地图动画被地板压住。
   RefPtr<Actor> tileRoot_;
   /// 角色可行走矩形区域。
-  std::vector<Rect> movableArea_;
+  std::vector<Vec2> movablePolygon_;
   /// 进入后会触发切图/传送的矩形区域。
   std::vector<Rect> moveArea_;
   /// 地板铺设后推导出的横向覆盖宽度，用于背景动画横向平铺。
   int backgroundRepeatWidth_ = 0;
   /// 地图配置里的整体 Y 偏移；既影响层位置，也影响地板校准。
   int mapOffsetY_ = 0;
-  bool debugMode_ = false;
+  bool debugMode_ = true;
   /// 当前地图正在播放的背景音乐。
   Ptr<Music> currentMusic_;
 };

Game/include/map/GameMapLayer.h

@@ -9,11 +9,14 @@ class GameMapLayer : public Actor {
 public:
   void Render() override;
 
-  void AddDebugFeasibleAreaInfo(const Rect& rect, int type);
+  void SetDebugFeasibleAreaPolygon(const std::vector<Vec2>& polygon);
+  void AddDebugMoveAreaInfo(const Rect& rect);
+  void ClearDebugAreaInfo();
   void AddObject(RefPtr<Actor> obj);
 
 private:
-  std::vector<Rect> feasibleAreaInfoList_;
+  std::vector<Vec2> feasibleAreaPolygon_;
+  std::vector<Rect> feasibleAreaFillRects_;
   std::vector<Rect> moveAreaInfoList_;
 };
 

Game/include/scene/GameDebugUIScene.h

@@ -0,0 +1,22 @@
+#pragma once
+
+#include <frostbite2D/scene/ui_scene.h>
+
+namespace frostbite2D {
+
+class CharacterObject;
+class GameMap;
+
+class GameDebugUIScene : public UIScene {
+public:
+  GameDebugUIScene() = default;
+  ~GameDebugUIScene() override = default;
+
+  void onEnter() override;
+  void onExit() override;
+
+  void SetDebugContext(GameMap* map, CharacterObject* character);
+  void ClearDebugContext();
+};
+
+} // namespace frostbite2D

Game/include/scene/GameMapTestScene.h

@@ -1,8 +1,9 @@
-#pragma once
+#pragma once
 
 #include "camera/GameCameraController.h"
 #include "character/CharacterObject.h"
 #include "map/GameMap.h"
+#include "scene/GameDebugUIScene.h"
 #include <frostbite2D/scene/scene.h>
 
 namespace frostbite2D {
@@ -19,6 +20,7 @@ public:
 private:
   GameCameraController cameraController_;
   RefPtr<CharacterObject> character_;
+  RefPtr<GameDebugUIScene> debugScene_;
   bool initialized_ = false;
   RefPtr<GameMap> map_;
 };

Game/include/ui/NineSliceActor.h

@@ -0,0 +1,54 @@
+#pragma once
+
+#include <array>
+#include <string>
+
+#include <frostbite2D/2d/actor.h>
+#include <frostbite2D/2d/sprite.h>
+
+namespace frostbite2D {
+
+/**
+ * @brief Composes 9 consecutive NPK frames into a resizable nine-slice panel.
+ */
+class NineSliceActor : public Actor {
+public:
+  NineSliceActor();
+  ~NineSliceActor() override = default;
+
+  static Ptr<NineSliceActor> createFromNpk(const std::string& imgPath,
+                                           size_t startIndex = 0);
+
+  bool SetSlices(const std::string& imgPath, size_t startIndex);
+  void SetSize(const Vec2& size);
+  void SetSize(float width, float height);
+
+  const std::string& GetImgPath() const { return imgPath_; }
+  size_t GetStartIndex() const { return startIndex_; }
+
+private:
+  enum SliceIndex : size_t {
+    TopLeft = 0,
+    Top = 1,
+    TopRight = 2,
+    Left = 3,
+    Center = 4,
+    Right = 5,
+    BottomLeft = 6,
+    Bottom = 7,
+    BottomRight = 8,
+    SliceCount = 9
+  };
+
+  void updateLayout();
+  void applySliceLayout(Ptr<Sprite> sprite, const Vec2& position,
+                        const Vec2& size);
+  Vec2 getNaturalSize() const;
+
+  std::string imgPath_;
+  size_t startIndex_ = 0;
+  std::array<Ptr<Sprite>, SliceCount> sliceSprites_;
+  std::array<Vec2, SliceCount> sliceNaturalSizes_ = {};
+};
+
+} // namespace frostbite2D