PHY/Plugins/GCS/Source/GenericCombatSystem/Public/Weapon/GCS_WeaponActor.h

// Copyright 2025 https://yuewu.dev/en  All Rights Reserved.

#pragma once

#include "CoreMinimal.h"
#include "GameplayTagAssetInterface.h"
#include "GCS_CombatStructLibrary.h"
#include "GCS_WeaponInterface.h"
#include "Collision/GCS_TraceStructLibrary.h"
#include "GameFramework/Actor.h"
#include "GCS_WeaponActor.generated.h"

/**
 * Delegate for weapon active state changes.
 * 武器激活状态更改的委托。
 */
DECLARE_DYNAMIC_MULTICAST_DELEGATE_OneParam(FGCS_WeaponActiveStateChangedSignature, bool, bIsActive);

/**
 * Default implementation of the weapon interface as an actor.
 * 作为Actor的武器接口默认实现。
 * @note Extend this class for custom weapon logic. 扩展此类以实现自定义武器逻辑。
 */
UCLASS(BlueprintType, Blueprintable, Abstract, ClassGroup=(GCS))
class GENERICCOMBATSYSTEM_API AGCS_WeaponActor : public AActor, public IGCS_WeaponInterface, public IGameplayTagAssetInterface
{
	GENERATED_BODY()

public:
	/**
	 * Default constructor.
	 * 默认构造函数。
	 */
	AGCS_WeaponActor(const FObjectInitializer& ObjectInitializer = FObjectInitializer::Get());

	/**
	 * Gets the pawn owning this weapon.
	 * 获取拥有此武器的Pawn。
	 * @return The owning pawn. 所属Pawn。
	 */
	virtual APawn* GetWeaponOwner_Implementation() const override;

	/**
	 * Gets the gameplay tags associated with the weapon.
	 * 获取与武器关联的游戏标签。
	 * @return The weapon's gameplay tags. 武器游戏标签。
	 */
	virtual const FGameplayTagContainer GetWeaponTags_Implementation() const override;

	/**
	 * Retrieves lifetime replicated properties.
	 * 获取生命周期复制属性。
	 * @param OutLifetimeProps The lifetime properties. 生命周期属性。
	 */
	virtual void GetLifetimeReplicatedProps(TArray<FLifetimeProperty>& OutLifetimeProps) const override;

	/**
	 * Sets the weapon's active state.
	 * 设置武器的激活状态。
	 * @param bNewActive The new active state. 新激活状态。
	 */
	virtual void SetWeaponActive_Implementation(bool bNewActive) override;

	/**
	 * Checks if the weapon is active.
	 * 检查武器是否激活。
	 * @return True if the weapon is active. 如果武器激活返回true。
	 */
	virtual bool IsWeaponActive_Implementation() const override;

	/**
	 * Gets the main primitive component of the weapon.
	 * 获取武器的主要原始组件。
	 * @return The primitive component. 原始组件。
	 */
	virtual UPrimitiveComponent* GetPrimitiveComponent_Implementation() const override;

	/**
	 * Gets the owned gameplay tags.
	 * 获取拥有的游戏标签。
	 * @param TagContainer The gameplay tag container (output). 游戏标签容器（输出）。
	 */
	virtual void GetOwnedGameplayTags(FGameplayTagContainer& TagContainer) const override;

protected:
	/**
	 * Called when the game starts.
	 * 游戏开始时调用。
	 */
	virtual void BeginPlay() override;

	/**
	 * Called when the game ends.
	 * 游戏结束时调用。
	 * @param EndPlayReason The reason for ending. 结束原因。
	 */
	virtual void EndPlay(const EEndPlayReason::Type EndPlayReason) override;

	/**
	 * Handles weapon active state changes.
	 * 处理武器激活状态变化。
	 * @param Prev The previous active state. 之前的激活状态。
	 */
	UFUNCTION(BlueprintCallable, BlueprintNativeEvent, Category = "GCS|Weapon")
	void OnWeaponActiveStateChanged(bool Prev);

	/**
	 * Refreshes trace instances and registers/unregisters trace events.
	 * 刷新碰撞检测实例并注册/取消注册碰撞事件。
	 */
	UFUNCTION(BlueprintCallable, BlueprintNativeEvent, Category="GCS|WeaponTrace", meta=(BlueprintProtected))
	void RefreshTraceInstance();
	virtual void RefreshTraceInstance_Implementation();

	/**
	 * Allow you to customize the source object used for weapon traces.
	 * 允许你自定义用于武器碰撞检测的源对象。
	 * @note The source object is the weapon itself by default. 默认是武器本身就是源对象.
	 * @return The object used as source object for weapon trace.
	 */
	UFUNCTION(BlueprintCallable, BlueprintNativeEvent, Category="GCS|WeaponTrace", meta=(BlueprintProtected))
	UObject* GetSourceObjectForTrace();
	virtual UObject* GetSourceObjectForTrace_Implementation();

	/**
	 * Allow you to customize the source component used for different weapon traces.
	 * 允许你自定义用于不同武器碰撞检测的源组件。
	 * @note The source component is the weapon primitive component by default. 默认是武器的PrimitiveComponent就是源组件.
	 * @return The component used as source component for weapon trace.
	 */
	UFUNCTION(BlueprintCallable, BlueprintNativeEvent, Category="GCS|WeaponTrace", meta=(BlueprintProtected))
	UPrimitiveComponent* GetSourceComponentForTrace(const FGameplayTag& TraceTag) const;
	virtual UPrimitiveComponent* GetSourceComponentForTrace_Implementation(const FGameplayTag& TraceTag) const;

	/**
	 * Handles weapon trace hits.
	 * 处理武器碰撞命中。
	 * @param TraceHandle The collision trace instance. 碰撞检测实例。
	 * @param HitResult The hit result. 命中结果。
	 */
	UFUNCTION(BlueprintCallable, BlueprintNativeEvent, Category="GCS|WeaponTrace")
	void OnAnyTraceHit(const FGCS_TraceHandle& TraceHandle, const FHitResult& HitResult);

	/**
	 * Handles trace state changes.
	 * 处理碰撞状态变化。
	 * @param TraceHandle The collision trace instance. 碰撞检测实例。
	 * @param NewState The new state. 新状态。
	 */
	UFUNCTION(BlueprintCallable, BlueprintNativeEvent, Category="GCS|WeaponTrace")
	void OnAnyTraceStateChanged(const FGCS_TraceHandle& TraceHandle, bool NewState);

	/**
	 * Delegate for weapon active state changes.
	 * 武器激活状态更改的委托。
	 */
	UPROPERTY(BlueprintAssignable)
	FGCS_WeaponActiveStateChangedSignature OnWeaponActiveStateChangedEvent;

public:
	/**
	 * Called every frame.
	 * 每帧调用。
	 * @param DeltaSeconds Time since last frame. 上一帧以来的时间。
	 */
	virtual void Tick(float DeltaSeconds) override;

protected:
	/**
	 * Gameplay tags for the weapon.
	 * 武器的游戏标签。
	 */
	UPROPERTY(EditDefaultsOnly, BlueprintReadWrite, Category = "WeaponSetting")
	FGameplayTagContainer WeaponTags;

	/**
	 * List of collision trace settings created when the weapon is activated.
	 * 武器激活时创建的碰撞检测设置列表。
	 */
	UPROPERTY(EditDefaultsOnly, BlueprintReadOnly, Category = "WeaponSetting|Trace")
	TArray<FGCS_TraceDefinition> TraceDefinitions;

	/**
	 * Tag name for looking up the mesh component.
	 * 查找网格组件的标签名称。
	 */
	UPROPERTY(EditDefaultsOnly, BlueprintReadOnly, Category="WeaponSetting")
	FName WeaponMeshTagName{TEXT("WeaponMesh")};

	UPROPERTY(EditDefaultsOnly, BlueprintReadOnly, Category="WeaponSetting", meta=(RequiredAssetDataTags = "RowStructure=/Script/GenericCombatSystem.GCS_ComboDefinition"))
	bool bGiveAbilitiesFromComboDefinitionTable{true};

	/**
	 * The combo definition table associated with this weapon.
	 * 与此武器关联的连击定义表。
	 */
	UPROPERTY(EditDefaultsOnly, BlueprintReadOnly, Category="WeaponSetting", meta=(RequiredAssetDataTags = "RowStructure=/Script/GenericCombatSystem.GCS_ComboDefinition"))
	TObjectPtr<const UDataTable> ComboDefinitionTable{nullptr};

	/**
	 * Traces associated with this weapon.
	 * 与该武器关联的碰撞检测.
	 */
	UPROPERTY(VisibleInstanceOnly, BlueprintReadOnly, Category="WeaponState")
	TArray<FGCS_TraceHandle> TraceHandles;

	/**
	 * Indicates if the weapon is active.
	 * 表示武器是否激活。
	 */
	UPROPERTY(EditDefaultsOnly, BlueprintReadOnly, ReplicatedUsing = OnWeaponActiveStateChanged, Category = "WeaponState")
	bool bWeaponActive;

#if WITH_EDITOR
	virtual EDataValidationResult IsDataValid(class FDataValidationContext& Context) const override;
#endif
};