feat(角色): 添加角色阴影渲染功能

新增 CharacterShadowActor 类用于处理角色阴影的渲染
在 CharacterObject 中实现阴影的同步和渲染逻辑
移除 GameDebugActor 中不再使用的合成纹理预览代码
添加 EnsureCompositeTextureReady 方法确保纹理准备就绪

Game/include/character/CharacterAnimation.h

@@ -51,6 +51,7 @@ public:
   animation::AniFrame GetCurrentFrameInfo() const;
   void SetActionFrameFlagCallback(ActionFrameFlagCallback callback);
   void SetActionEndCallback(ActionEndCallback callback);
+  bool EnsureCompositeTextureReady();
   bool HasCompositeTexture() const;
   Ptr<Texture> GetCompositeTexture() const;
   Vec2 GetCompositeTextureSize() const;

Game/include/character/CharacterObject.h

@@ -5,6 +5,7 @@
 #include "character/CharacterDataLoader.h"
 #include "character/CharacterEquipmentManager.h"
 #include "character/CharacterInputRouter.h"
+#include "character/CharacterShadowActor.h"
 #include "character/CharacterStateMachine.h"
 #include <frostbite2D/2d/actor.h>
 #include <frostbite2D/event/event.h>
@@ -31,7 +32,7 @@ class GameMap;
 class CharacterObject : public Actor {
 public:
   CharacterObject() = default;
-  ~CharacterObject() override = default;
+  ~CharacterObject() override;
 
   /// @brief 二段初始化角色。
   /// @param jobId 职业 id，用来加载职业配置、动作定义和动画资源。
@@ -77,7 +78,10 @@ public:
   ///
   /// 顺序固定为：命令缓冲推进 -> 采样实时输入 -> 生成意图 -> 状态机更新
   /// -> motor 推进 -> 投影到 Actor 坐标。
+  void Update(float deltaTime) override;
   void OnUpdate(float deltaTime) override;
+  void OnAdded(Actor* parent) override;
+  void PrepareRenderFrame();
 
   /// @brief 统一输入入口。
   ///
@@ -182,6 +186,9 @@ private:
   void ApplyMapMovementConstraints(const CharacterWorldPosition& previousPosition);
   void QueueMapTransitionIfNeeded();
   void SyncActorPositionFromWorld();
+  void SyncShadowAttachment();
+  void SyncShadowPresentation();
+  void DetachShadowActor();
   bool SetActionStrict(const std::string& actionName,
                        const char* phase,
                        const std::string& requestedActionId);
@@ -238,6 +245,10 @@ private:
   /// 真正负责播放角色分层动画的 Actor 子节点。
   RefPtr<CharacterAnimation> animationManager_ = nullptr;
 
+  /// ???? normal ???????????
+  RefPtr<CharacterShadowActor> shadowActor_ = nullptr;
+  GameMap* shadowAttachedMap_ = nullptr;
+
   /// 缓存上一帧 deltaTime，方便状态和脚本系统查询。
   float lastDeltaTime_ = 0.0f;
 

Game/include/character/CharacterShadowActor.h

@@ -0,0 +1,32 @@
+#pragma once
+
+#include <frostbite2D/2d/sprite.h>
+
+namespace frostbite2D {
+
+struct CharacterShadowFrameSnapshot {
+  bool visible = false;
+  Ptr<Texture> texture = nullptr;
+  Vec2 textureSize = Vec2::Zero();
+  Vec2 groundAnchorInTexture = Vec2::Zero();
+  Vec2 groundScreenPosition = Vec2::Zero();
+  int zOrder = 0;
+  uint64 textureVersion = 0;
+};
+
+class CharacterShadowActor : public Sprite {
+public:
+  CharacterShadowActor();
+
+  void ApplyFrameSnapshot(const CharacterShadowFrameSnapshot& snapshot);
+
+private:
+  void ApplyTextureState(const CharacterShadowFrameSnapshot& snapshot);
+
+  Ptr<Texture> appliedTexture_ = nullptr;
+  Vec2 appliedTextureSize_ = Vec2::Zero();
+  Vec2 appliedGroundAnchorInTexture_ = Vec2::Zero();
+  uint64 appliedTextureVersion_ = 0;
+};
+
+} // namespace frostbite2D