feat(animation): 添加动画状态回调支持

refactor(character): 重构角色动作处理逻辑

feat(swordman): 实现剑士基础攻击和技能1处理

refactor(state): 优化状态机与动作上下文管理

feat(input): 改进输入系统支持动作请求队列

refactor(movement): 重构移动系统支持行走/奔跑模式

Game/include/character/CharacterObject.h

@@ -97,6 +97,26 @@ public:
   CharacterMotor& GetMotorMutable() { return motor_; }
   CharacterCommandBuffer& GetCommandBufferMutable() { return commandBuffer_; }
   float GetLastDeltaTime() const { return lastDeltaTime_; }
+  const CharacterRuntimeBlackboard& GetRuntimeBlackboard() const { return runtimeBlackboard_; }
+  CharacterRuntimeBlackboard& GetRuntimeBlackboardMutable() { return runtimeBlackboard_; }
+
+  /// @brief Prepare one-shot data for the next action transition.
+  ///
+  /// The returned context is consumed by the next successful `EnterAction()`.
+  CharacterActionContextData& PreparePendingActionContext(
+      const std::string& requestedActionId,
+      const std::string& sourceActionId = std::string(),
+      CharacterStateId sourceStateId = CharacterStateId::Idle);
+  void ClearPendingActionContext();
+  bool HasPendingActionContext() const { return pendingActionContext_.valid; }
+  const CharacterActionContextData* GetPendingActionContext() const;
+  CharacterActionContextData* GetPendingActionContextMutable();
+
+  /// @brief Read transition metadata for the currently running action.
+  const CharacterActionContextData* GetCurrentActionContext() const;
+  CharacterActionContextData* GetCurrentActionContextMutable();
+  bool HasCurrentActionContext() const { return currentActionContext_.valid; }
+  void ClearCurrentActionContext();
 
   /// @brief 按逻辑动作 id 查询动作定义。
   const CharacterActionDefinition* FindAction(const std::string& actionId) const;
@@ -105,13 +125,24 @@ public:
   const CharacterActionDefinition* RequireAction(const std::string& actionId,
                                                  const char* phase) const;
 
-  /// @brief 按动作定义播放动画；缺少 animationTag 或资源不存在时会输出详细错误并退出。
-  bool PlayActionDefinition(const CharacterActionDefinition& action, const char* phase);
-
   /// @brief 播放某个动画标签。
   ///
   /// 当前只是对 `SetAction()` 的语义包装，方便状态机表达“播放动作标签”。
   void PlayAnimationTag(const std::string& actionTag);
+  bool HasAnimationTag(const std::string& actionTag) const;
+
+  /// @brief 查询当前动作主动画是否已经播放完成。
+  bool IsCurrentAnimationFinished() const;
+
+  /// @brief 读取当前动作主动画的帧信息，方便状态类/脚本做运行时判断。
+  int GetCurrentAnimationFrameIndex() const;
+  int GetCurrentAnimationFrameCount() const;
+  float GetCurrentAnimationProgressNormalized() const;
+  animation::AniFrame GetCurrentAnimationFrameInfo() const;
+
+  /// @brief 绑定当前动作主动画的运行时回调，供后续脚本系统接入。
+  void SetAnimationFrameFlagCallback(CharacterAnimation::ActionFrameFlagCallback callback);
+  void SetAnimationEndCallback(CharacterAnimation::ActionEndCallback callback);
 
   /// @brief 输出角色动作/动画的致命错误，并请求应用退出。
   void ReportFatalCharacterError(const char* phase,
@@ -136,6 +167,9 @@ public:
   const CharacterEquipmentManager& GetEquipmentManager() const { return equipmentManager_; }
 
 private:
+  void CommitPendingActionContext(const std::string& defaultRequestedActionId,
+                                  const std::string& defaultSourceActionId,
+                                  CharacterStateId defaultSourceStateId);
   bool SetActionStrict(const std::string& actionName,
                        const char* phase,
                        const std::string& requestedActionId);
@@ -159,7 +193,7 @@ private:
   /// 负责拼装装备部件，决定分层 Avatar 的表现资源。
   CharacterEquipmentManager equipmentManager_;
 
-  /// 动作定义表：把逻辑 actionId 映射到帧数据、取消规则、动画标签等。
+  /// 动作定义表：保存显式注册的逻辑动作入口。
   CharacterActionLibrary actionLibrary_;
 
   /// 输入适配层，把键盘/手柄事件收敛成统一命令。
@@ -171,7 +205,16 @@ private:
   /// 当前帧从命令缓冲整理出的“角色意图”。
   CharacterIntent currentIntent_;
 
-  /// 状态调度器，负责状态切换、动作进入和帧事件推进。
+  /// Character-wide shared runtime data for skills, buffs, and future scripts.
+  CharacterRuntimeBlackboard runtimeBlackboard_;
+
+  /// One-shot payload prepared before switching into the next action.
+  CharacterActionContextData pendingActionContext_;
+
+  /// Metadata attached to the action currently running inside Action state.
+  CharacterActionContextData currentActionContext_;
+
+  /// 状态调度器，负责状态切换与动作进入。
   CharacterStateMachine stateMachine_;
 
   /// 纯运动数据：位置、速度、落地状态和朝向都在这里维护。
@@ -188,6 +231,8 @@ private:
 
   /// 是否允许从事件系统接收输入；AI/剧情接管时可临时关闭。
   bool inputEnabled_ = true;
+
+  friend class CharacterStateMachine;
 };
 
 } // namespace frostbite2D