feat: 添加游戏数学工具类并重构相关代码

refactor: 将数学工具函数移至GameMath类
feat(音频): 实现地图音频控制器
feat(调试): 添加游戏调试UI组件
feat(地图): 增加移动区域边界获取方法
fix(角色): 修复角色移动区域抑制逻辑
refactor(世界): 重构游戏世界场景初始化
docs(音频): 完善音频数据库注释

Game/include/audio/MapAudioController.h

@@ -0,0 +1,48 @@
+#pragma once
+
+#include <frostbite2D/audio/music.h>
+#include <frostbite2D/audio/sound.h>
+#include <optional>
+#include <string>
+#include <unordered_map>
+#include <vector>
+
+namespace frostbite2D {
+
+struct MapAudioTrack {
+  std::string id;
+  std::string path;
+};
+
+struct MapAudioState {
+  std::optional<MapAudioTrack> bgmTrack;
+  std::vector<MapAudioTrack> ambientLoops;
+};
+
+class MapAudioController {
+public:
+  static MapAudioController& get();
+
+  void ApplyMapAudio(const MapAudioState& state);
+  void ClearMapAudio();
+
+private:
+  struct ActiveAmbientLoop {
+    MapAudioTrack track;
+    RefPtr<Sound> sound;
+    int channel = -1;
+  };
+
+  MapAudioController() = default;
+
+  void ApplyBgmTrack(const std::optional<MapAudioTrack>& bgmTrack);
+  void ApplyAmbientLoops(const std::vector<MapAudioTrack>& ambientLoops);
+  void StopAmbientLoop(ActiveAmbientLoop& loop);
+  static std::string NormalizeTrackKey(const MapAudioTrack& track);
+
+  std::optional<MapAudioTrack> currentBgmTrack_;
+  RefPtr<Music> currentBgmMusic_;
+  std::unordered_map<std::string, ActiveAmbientLoop> activeAmbientLoops_;
+};
+
+} // namespace frostbite2D

Game/include/character/CharacterActionTypes.h

@@ -1,5 +1,6 @@
 #pragma once
 
+#include "common/math/GameMath.h"
 #include <frostbite2D/types/type_math.h>
 #include <string>
 #include <unordered_map>
@@ -81,8 +82,8 @@ struct CharacterMotor {
   float gravity = 1600.0f;
 
   void SetGroundPosition(const Vec2& groundPosition) {
-    position.x = RoundWorldCoordinate(groundPosition.x);
-    position.y = RoundWorldCoordinate(groundPosition.y);
+    position.x = gameMath::RoundWorldCoordinate(groundPosition.x);
+    position.y = gameMath::RoundWorldCoordinate(groundPosition.y);
     positionRemainder_ = Vec2::Zero();
   }
 
@@ -167,10 +168,6 @@ struct CharacterMotor {
   }
 
 private:
-  static int32 RoundWorldCoordinate(float value) {
-    return static_cast<int32>(std::lround(value));
-  }
-
   static int32 ConsumeWholeUnits(float& remainder) {
     if (remainder >= 1.0f) {
       int32 wholeUnits = static_cast<int32>(std::floor(remainder));

Game/include/common/math/GameMath.h

@@ -0,0 +1,19 @@
+#pragma once
+
+#include <frostbite2D/types/type_math.h>
+#include <vector>
+
+namespace frostbite2D::gameMath {
+
+int32 RoundWorldCoordinate(float value);
+Vec2 MakeIntegerWorldPoint(int x, int y);
+Vec3 MakeIntegerWorldPosition(int x, int y, int z);
+
+bool IsPointOnSegment(const Vec2& point, const Vec2& start, const Vec2& end);
+bool IsPointInPolygon(const std::vector<Vec2>& polygon, const Vec2& point);
+bool IsPointMovable(const std::vector<Vec2>& polygon, int x, int y);
+
+std::vector<Vec2> BuildRectPolygon(const Rect& rect);
+std::vector<Rect> BuildPolygonFillRects(const std::vector<Vec2>& polygon);
+
+} // namespace frostbite2D::gameMath

Game/include/map/GameMap.h

@@ -49,6 +49,7 @@ public:
   size_t FindMoveAreaIndex(const Vec3& curPos) const;
   const std::vector<MapMoveArea>& GetMoveAreaInfo() const;
   size_t GetMoveAreaCount() const { return moveArea_.size(); }
+  game::MoveAreaBounds GetMovablePositionBounds(size_t index) const;
   Rect GetMovablePositionArea(size_t index) const;
   const std::string& GetMapPath() const { return mapConfig_.mapPath; }
   void SetDebugHighlightedMoveAreaIndex(size_t index);

Game/include/world/GameTown.h

@@ -25,6 +25,7 @@ public:
 
   int GetCurAreaIndex() const { return curMapIndex_; }
   RefPtr<GameMap> GetArea(int index) const;
+  RefPtr<GameMap> GetCurrentArea() const;
   const std::vector<MapInfo>& GetAreas() const { return mapList_; }
 
   void Update(float deltaTime) override;

Game/include/world/GameWorld.h

@@ -7,6 +7,11 @@
 
 namespace frostbite2D {
 
+class Actor;
+class CharacterObject;
+class GameDebugUIScene;
+class GameMap;
+
 class GameWorld : public Scene {
 public:
   GameWorld();
@@ -19,6 +24,13 @@ public:
   void AddCharacter(RefPtr<Actor> actor, int townId);
   void MoveCharacter(RefPtr<Actor> actor, int townId, int area);
   void RequestMoveCharacter(RefPtr<Actor> actor, int townId, int area);
+  void UpdateMoveAreaSuppression(GameMap* map, size_t moveAreaIndex);
+  bool ShouldSuppressMoveArea(GameMap* map, size_t moveAreaIndex) const;
+
+  Actor* GetMainActor() const;
+  CharacterObject* GetMainCharacter() const;
+  GameTown* GetCurrentTown() const;
+  GameMap* GetCurrentMap() const;
 
   static GameWorld* GetWorld();
 
@@ -29,13 +41,25 @@ private:
     int area = -1;
   };
 
+  struct SuppressedMoveArea {
+    GameMap* map = nullptr;
+    size_t moveAreaIndex = GameMap::kInvalidMoveAreaIndex;
+  };
+
   bool InitWorld();
+  bool InitMainCharacter(int townId);
   void ProcessPendingCharacterMove();
+  void EnsureDebugScene();
+  void RefreshDebugContext();
+  void SetSuppressedMoveArea(GameMap* map, size_t moveAreaIndex);
+  void ClearSuppressedMoveArea();
 
   std::map<int, std::string> townPathMap_;
   std::map<int, RefPtr<GameTown>> townMap_;
   RefPtr<Actor> mainActor_;
+  RefPtr<GameDebugUIScene> debugScene_;
   std::optional<PendingCharacterMove> pendingCharacterMove_;
+  std::optional<SuppressedMoveArea> suppressedMoveArea_;
   int curTown_ = -1;
   bool initialized_ = false;
 };