diff --git a/Source/PHY/Public/Characters/PHYCharacterBase.h b/Source/PHY/Public/Characters/PHYCharacterBase.h index e583ecc..8ed70e9 100644 --- a/Source/PHY/Public/Characters/PHYCharacterBase.h +++ b/Source/PHY/Public/Characters/PHYCharacterBase.h @@ -24,261 +24,326 @@ class USLSCharacterMovementComponent; class USLSIntegrationComponent; /** - * @brief PHY 玩家?AI 共用角色基类? * - * 基类直接继承 ACharacter,并通过项目级组件和接口适配 GAS、GCS、GGS、UGC 与后续运动系统? */ + * @brief PHY 玩家和 AI 共用的角色基类。 + * + * 基类直接继承 ACharacter,并通过项目级组件和接口适配 GAS、GCS、GGS、 + * UGC 与 Smooth Locomotion 等系统。 + */ UCLASS(Abstract, BlueprintType, Blueprintable) class PHY_API APHYCharacterBase : public ACharacter, public IAbilitySystemInterface, public IGameplayTagAssetInterface, public IGCS_CombatEntityInterface { GENERATED_BODY() public: - /** @brief 构造基础角色组件?*/ + /** @brief 创建角色基类并挂载项目核心组件。 */ APHYCharacterBase(const FObjectInitializer& ObjectInitializer = FObjectInitializer::Get()); - /** @brief 注册 ModularGameplay 组件接收者?*/ + /** @brief 注册 ModularGameplay 组件接收者。 */ virtual void PreInitializeComponents() override; - /** @brief ?Possess ?PlayerState 初始化前绑定显示?Mesh 桥接组件?*/ + /** @brief 在 Possess 和 PlayerState 初始化前绑定显示 Mesh 桥接组件。 */ virtual void PostInitializeComponents() override; - /** @brief 初始化角色运行时组件?*/ + /** @brief 初始化角色运行时状态和组件。 */ virtual void BeginPlay() override; - /** @brief 移除 ModularGameplay 组件接收者?*/ + /** @brief 移除 ModularGameplay 组件接收者。 */ virtual void EndPlay(const EEndPlayReason::Type EndPlayReason) override; - /** @brief 控制器接管时刷新项目状态?*/ + /** @brief 控制器接管角色时刷新项目状态。 */ virtual void PossessedBy(AController* NewController) override; - /** @brief 控制器复制到客户端后刷新项目状态?*/ + /** @brief 控制器复制到客户端后刷新项目状态。 */ virtual void OnRep_Controller() override; - /** @brief 获取当前角色使用?AbilitySystemComponent?*/ + /** @brief 获取当前角色使用的 AbilitySystemComponent。 */ virtual UAbilitySystemComponent* GetAbilitySystemComponent() const override; - /** @brief 收集 ASC 与角色状态组件提供的 GameplayTag?*/ + /** @brief 收集 ASC 与角色状态组件提供的 GameplayTag。 */ virtual void GetOwnedGameplayTags(FGameplayTagContainer& TagContainer) const override; - /** @brief 初始化当?Avatar 对应?ASC?*/ + /** + * @brief 初始化当前 Avatar 对应的 ASC。 + * @param NewAbilitySystemComponent 要绑定到该角色的 ASC。 + * @param OwnerActor ASC 的 OwnerActor,玩家通常为 PlayerState,AI 通常为自身。 + */ UFUNCTION(BlueprintCallable, Category="PHY|Character|Ability") virtual void InitializeAbilitySystem(UAbilitySystemComponent* NewAbilitySystemComponent, AActor* OwnerActor); - /** @brief 清理角色缓存?ASC 引用?*/ + /** @brief 清理角色缓存的 ASC 引用。 */ UFUNCTION(BlueprintCallable, Category="PHY|Character|Ability") virtual void ClearAbilitySystem(); - /** @brief 查询 ASC 是否已经完成项目级初始化?*/ + /** @brief 查询 ASC 是否已经完成项目级初始化。 */ UFUNCTION(BlueprintCallable, BlueprintPure, Category="PHY|Character|Ability") bool IsAbilitySystemReady() const { return bAbilitySystemReady; } - /** @brief 接收输入 Tag 并路由到移动、交互或 GAS Ability?*/ + /** + * @brief 接收输入 Tag 并路由到移动、交互或 GAS Ability。 + * @param InputTag 输入系统派发的 GameplayTag。 + * @param TriggerEvent Enhanced Input 触发事件。 + * @return 成功处理时返回 true。 + */ UFUNCTION(BlueprintCallable, Category="PHY|Character|Input") virtual bool HandleInputTag(FGameplayTag InputTag, ETriggerEvent TriggerEvent); - /** @brief 设置移动意图,并在客户端请求服务端同步?*/ + /** + * @brief 设置角色移动意图,并在客户端请求服务端同步。 + * @param NewMovementIntent 世界空间移动意图。 + */ UFUNCTION(BlueprintCallable, Category="PHY|Character|Movement") virtual void SetMovementIntent(FVector NewMovementIntent); - /** @brief 设置项目级战斗目标?*/ + /** + * @brief 设置项目级战斗目标。 + * @param NewCombatTargetActor 新的战斗目标 Actor。 + */ UFUNCTION(BlueprintCallable, Category="PHY|Character|Combat") virtual void SetCombatTargetActor(AActor* NewCombatTargetActor); - /** @brief 请求开始交互?*/ + /** + * @brief 请求开始交互。 + * @param OptionIndex 交互选项索引。 + * @return 交互请求被接受时返回 true。 + */ UFUNCTION(BlueprintCallable, Category="PHY|Character|Interaction") virtual bool RequestInteraction(int32 OptionIndex = 0); - /** @brief 请求一次性即时交互?*/ + /** + * @brief 请求执行一次即时交互。 + * @param OptionIndex 交互选项索引。 + * @return 交互请求被接受时返回 true。 + */ UFUNCTION(BlueprintCallable, Category="PHY|Character|Interaction") virtual bool RequestInstantInteraction(int32 OptionIndex = 0); - /** @brief 请求结束当前交互?*/ + /** @brief 请求结束当前交互。 */ UFUNCTION(BlueprintCallable, Category="PHY|Character|Interaction") virtual void EndInteraction(); - /** @brief 请求切换当前可交互对象?*/ + /** + * @brief 请求切换当前可交互目标。 + * @param bNext 为 true 时切到下一个目标,否则切到上一个目标。 + */ UFUNCTION(BlueprintCallable, Category="PHY|Character|Interaction") virtual void CycleInteractionTarget(bool bNext); + /** @brief 获取角色状态组件。 */ UFUNCTION(BlueprintCallable, BlueprintPure, Category="PHY|Character") UPHYCharacterStateComponent* GetCharacterStateComponent() const { return CharacterStateComponent; } - /** @brief 获取 GCS 战斗组件?*/ + /** @brief 获取 GCS 战斗系统组件。 */ UFUNCTION(BlueprintCallable, BlueprintPure, Category="PHY|Character") UGCS_CombatSystemComponent* GetCombatSystemComponent() const { return CombatSystemComponent; } - /** @brief 获取 GCS 目标组件?*/ + /** @brief 获取 GCS 目标系统组件。 */ UFUNCTION(BlueprintCallable, BlueprintPure, Category="PHY|Character") UGCS_TargetingSystemComponent* GetTargetingSystemComponent() const { return TargetingSystemComponent; } - /** @brief 获取 GGS 交互组件?*/ + /** @brief 获取 GGS 交互系统组件。 */ UFUNCTION(BlueprintCallable, BlueprintPure, Category="PHY|Character") UGGS_InteractionSystemComponent* GetInteractionSystemComponent() const { return InteractionSystemComponent; } - /** @brief 获取 GGS 布娃娃组件?*/ + /** @brief 获取 GGS 布娃娃组件。 */ UFUNCTION(BlueprintCallable, BlueprintPure, Category="PHY|Character") UGGS_RagdollComponent* GetRagdollComponent() const { return RagdollComponent; } - /** @brief 获取上下文效果组件?*/ + /** @brief 获取 GES 上下文效果组件。 */ UFUNCTION(BlueprintCallable, BlueprintPure, Category="PHY|Character") UGES_ContextEffectComponent* GetContextEffectComponent() const { return ContextEffectComponent; } - /** @brief 获取角色 Mesh Bridge 组件?*/ + /** @brief 获取角色 Mesh Bridge 组件。 */ UFUNCTION(BlueprintCallable, BlueprintPure, Category="PHY|Character|Animation") UPHYCharacterMeshBridgeComponent* GetMeshBridgeComponent() const { return MeshBridgeComponent; } - /** @brief 获取 SLS 角色运动组件?*/ + /** @brief 获取 SLS 角色移动组件。 */ UFUNCTION(BlueprintCallable, BlueprintPure, Category="PHY|Character|Locomotion") USLSCharacterMovementComponent* GetSLSCharacterMovementComponent() const; - /** @brief 获取 SLS 集成入口组件?*/ + /** @brief 获取 SLS 集成入口组件。 */ UFUNCTION(BlueprintCallable, BlueprintPure, Category="PHY|Character|Locomotion") USLSIntegrationComponent* GetSLSIntegrationComponent() const { return SLSIntegrationComponent; } - /** @brief 获取 GenericGameSystem 可选集成入口组件?*/ + /** @brief 获取 GenericGameSystem 可选集成入口组件。 */ UFUNCTION(BlueprintCallable, BlueprintPure, Category="PHY|Character|Locomotion") UActorComponent* GetGenericIntegrationComponent() const { return GenericIntegrationComponent; } - /** @brief 获取显示?Mesh 组件,职业和外观 Mesh 应应用到该组件?*/ + /** @brief 获取显示层 Mesh 组件,职业和外观 Mesh 应当应用到该组件。 */ UFUNCTION(BlueprintCallable, BlueprintPure, Category="PHY|Character|Animation") USkeletalMeshComponent* GetDisplayMeshComponent() const { return DisplayMeshComponent; } - /** @brief 获取当前战斗目标 Actor?*/ + /** @brief 获取当前战斗目标 Actor。 */ virtual AActor* GetCombatTargetActor_Implementation() const override; - /** @brief 获取连击定义表,首期骨架默认不绑定表?*/ + /** @brief 获取连击定义表,首期骨架默认不绑定表。 */ virtual const UDataTable* GetComboDefinitionTable_Implementation() const override; - /** @brief 获取当前战斗目标场景对象?*/ + /** @brief 获取当前战斗目标场景对象。 */ virtual USceneComponent* GetCombatTargetObject_Implementation() const override; - /** @brief 查询能力动作,首期骨架默认返回空?*/ + /** + * @brief 查询可用 Ability 动作,首期骨架默认返回空。 + * @param AbilityTags 能力标签集合。 + * @param SourceTags 来源标签集合。 + * @param TargetTags 目标标签集合。 + * @param AbilityActions 输出的能力动作列表。 + * @return 找到可用动作时返回 true。 + */ virtual bool QueryAbilityActions_Implementation(FGameplayTagContainer AbilityTags, FGameplayTagContainer SourceTags, FGameplayTagContainer TargetTags, TArray& AbilityActions) override; - /** @brief 按上下文查询能力动作,首期骨架默认返回空?*/ + /** + * @brief 按上下文查询可用 Ability 动作,首期骨架默认返回空。 + * @param Context 查询上下文对象。 + * @param AbilityTags 能力标签集合。 + * @param SourceTags 来源标签集合。 + * @param TargetTags 目标标签集合。 + * @param AbilityActions 输出的能力动作列表。 + * @return 找到可用动作时返回 true。 + */ virtual bool QueryAbilityActionsByContext_Implementation(UObject* Context, FGameplayTagContainer AbilityTags, FGameplayTagContainer SourceTags, FGameplayTagContainer TargetTags, TArray& AbilityActions) override; - /** @brief ?Tag 查询当前武器?*/ + /** + * @brief 按 Tag 查询当前武器。 + * @param Query 用于匹配武器标签的查询。 + * @return 匹配到的武器对象。 + */ virtual UObject* QueryWeapon_Implementation(const FGameplayTagQuery& Query) const override; - /** @brief 设置旋转模式?*/ + /** @brief 设置旋转模式。 */ virtual void SetRotationMode_Implementation(FGameplayTag NewRotationMode) override; - /** @brief 获取旋转模式?*/ + /** @brief 获取旋转模式。 */ virtual FGameplayTag GetRotationMode_Implementation() const override; - /** @brief 设置移动集合?*/ + /** @brief 设置移动集合。 */ virtual void SetMovementSet_Implementation(FGameplayTag NewMovementSet) override; - /** @brief 获取移动集合?*/ + /** @brief 获取移动集合。 */ virtual FGameplayTag GetMovementSet_Implementation() const override; - /** @brief 设置移动状态?*/ + /** @brief 设置移动状态。 */ virtual void SetMovementState_Implementation(FGameplayTag NewMovementState) override; - /** @brief 获取移动状态?*/ + /** @brief 获取移动状态。 */ virtual FGameplayTag GetMovementState_Implementation() const override; - /** @brief 开始死亡流程?*/ + /** @brief 开始死亡流程。 */ virtual void StartDeath_Implementation() override; - /** @brief 完成死亡流程?*/ + /** @brief 完成死亡流程。 */ virtual void FinishDeath_Implementation() override; - /** @brief 查询角色是否死亡?*/ + /** @brief 查询角色是否死亡。 */ virtual bool IsDead_Implementation() const override; - /** @brief 获取移动意图?*/ + /** @brief 获取移动意图。 */ virtual FVector GetMovementIntent_Implementation() const override; - /** @brief 获取当前武器?*/ + /** + * @brief 获取当前武器。 + * @param Context 可选查询上下文。 + * @return 当前武器对象。 + */ virtual UObject* GetCurrentWeapon_Implementation(UObject* Context = nullptr) const override; - /** @brief 设置当前武器?*/ + /** @brief 设置当前武器。 */ virtual void SetCurrentWeapon_Implementation(UObject* Weapon) override; - /** @brief 获取指定 Socket 的相对变换?*/ + /** + * @brief 获取指定 Socket 的相对变换。 + * @param InSkeletalMeshComponent 用于查找 Socket 的骨骼网格组件。 + * @param StaticMesh 静态网格参考。 + * @param SkeletalMesh 骨骼网格参考。 + * @param SocketName Socket 名称。 + * @param OutTransform 输出相对变换。 + * @return 成功取得变换时返回 true。 + */ virtual bool GetRelativeTransformToSocket_Implementation(const USkeletalMeshComponent* InSkeletalMeshComponent, const UStaticMesh* StaticMesh, const USkeletalMesh* SkeletalMesh, FName SocketName, FTransform& OutTransform) const override; protected: - /** @brief 将输?Tag 映射?Ability Tag?*/ + /** + * @brief 将输入 Tag 映射为 Ability Tag。 + * @param InputTag 输入系统提供的 Tag。 + * @return 对应的 Ability Tag。 + */ virtual FGameplayTag GetAbilityTagForInputTag(FGameplayTag InputTag) const; - /** @brief 应用 Character 配置默认值?*/ + /** @brief 应用 Character 配置默认值。 */ virtual void ApplyCharacterSettings(); - /** @brief 服务端同步移动意图?*/ + /** @brief 服务端同步移动意图。 */ UFUNCTION(Server, Unreliable) void ServerSetMovementIntent(FVector NewMovementIntent); - /** @brief 服务端设置战斗目标?*/ + /** @brief 服务端设置战斗目标。 */ UFUNCTION(Server, Reliable) void ServerSetCombatTargetActor(AActor* NewCombatTargetActor); - /** @brief 服务端执行开始交互?*/ + /** @brief 服务端执行开始交互。 */ UFUNCTION(Server, Reliable) void ServerRequestInteraction(int32 OptionIndex); - /** @brief 服务端执行即时交互?*/ + /** @brief 服务端执行即时交互。 */ UFUNCTION(Server, Reliable) void ServerRequestInstantInteraction(int32 OptionIndex); - /** @brief 服务端结束交互?*/ + /** @brief 服务端结束交互。 */ UFUNCTION(Server, Reliable) void ServerEndInteraction(); - /** @brief 服务端切换交互目标?*/ + /** @brief 服务端切换交互目标。 */ UFUNCTION(Server, Reliable) void ServerCycleInteractionTarget(bool bNext); - /** @brief 角色共享状态组件?*/ + /** @brief 角色共享状态组件。 */ UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category="PHY|Character") TObjectPtr CharacterStateComponent; - /** @brief GCS 战斗系统组件?*/ + /** @brief GCS 战斗系统组件。 */ UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category="PHY|Character") TObjectPtr CombatSystemComponent; - /** @brief GCS 目标系统组件?*/ + /** @brief GCS 目标系统组件。 */ UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category="PHY|Character") TObjectPtr TargetingSystemComponent; - /** @brief GCS 战斗队伍代理组件?*/ + /** @brief GCS 战斗队伍代理组件。 */ UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category="PHY|Character") TObjectPtr CombatTeamAgentComponent; - /** @brief GGS 交互系统组件?*/ + /** @brief GGS 交互系统组件。 */ UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category="PHY|Character") TObjectPtr InteractionSystemComponent; - /** @brief GGS 布娃娃组件?*/ + /** @brief GGS 布娃娃组件。 */ UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category="PHY|Character") TObjectPtr RagdollComponent; - /** @brief GES 上下文效果组件?*/ + /** @brief GES 上下文效果组件。 */ UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category="PHY|Character") TObjectPtr ContextEffectComponent; - /** @brief 运动?Mesh 与显示层 Mesh 的桥接组件?*/ + /** @brief 运动源 Mesh 与显示层 Mesh 的桥接组件。 */ UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category="PHY|Character|Animation") TObjectPtr MeshBridgeComponent; - /** @brief SLS 插件集成入口组件,由运动层集中接入?*/ + /** @brief SLS 插件集成入口组件,由运动层集中接入。 */ UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category="PHY|Character|Locomotion") TObjectPtr SLSIntegrationComponent; - /** @brief GenericGameSystem 可选集成入口组件?*/ + /** @brief GenericGameSystem 可选集成入口组件。 */ UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category="PHY|Character|Locomotion") TObjectPtr GenericIntegrationComponent; - /** @brief 显示?Mesh 组件,承载职业和外观 Mesh?*/ + /** @brief 显示层 Mesh 组件,承载职业和外观 Mesh。 */ UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category="PHY|Character|Animation") TObjectPtr DisplayMeshComponent; - /** @brief 当前 Avatar 缓存?ASC,玩家来?PlayerState,AI 来自自身?*/ + /** @brief 当前 Avatar 缓存的 ASC,玩家来自 PlayerState,AI 来自自身。 */ UPROPERTY(Transient) TObjectPtr CachedAbilitySystemComponent; - /** @brief ASC 是否已经初始化为当前 Avatar?*/ + /** @brief ASC 是否已经初始化为当前 Avatar。 */ UPROPERTY(Transient) bool bAbilitySystemReady = false; };