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

#pragma once

#include "CoreMinimal.h"
#include "Components/ActorComponent.h"
#include "GameplayTagContainer.h"
#include "GCS_TraceDelegates.h"
#include "GCS_TraceStructLibrary.h"
#include "GCS_TraceSystemComponent.generated.h"

class UGCS_TraceSubsystem;
class UPrimitiveComponent;


DECLARE_DYNAMIC_MULTICAST_DELEGATE(FGCS_OnTraceSystemDestroyedSignature);


/**
 * Component for managing collision trace instances.
 * 管理碰撞检测实例的组件。
 */
UCLASS(ClassGroup=(GCS), meta=(BlueprintSpawnableComponent, PrioritizeCategories="GCS"), Blueprintable, HideCategories=(Sockets, Navigation, Tags, ComponentTick, ComponentReplication,
	Cooking, AssetUserData, Replication))
class GENERICCOMBATSYSTEM_API UGCS_TraceSystemComponent : public UActorComponent
{
	GENERATED_BODY()

	friend UGCS_TraceSubsystem;

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

	/**
	 * Gets the collision trace system component from an actor.
	 * 从Actor获取碰撞检测系统组件。
	 * @param Actor The actor to query. 要查询的Actor。
	 * @return The collision trace system component. 碰撞检测系统组件。
	 */
	UFUNCTION(BlueprintCallable, BlueprintPure, Category = "GCS|TraceSystem", Meta = (DefaultToSelf="Actor"))
	static UGCS_TraceSystemComponent* GetTraceSystemComponent(const AActor* Actor);

	/**
	 * Finds the collision trace system component on an actor.
	 * 在Actor上查找碰撞检测系统组件。
	 * @param Actor The actor to query. 要查询的Actor。
	 * @param Component The found component (output). 找到的组件（输出）。
	 * @return True if found. 如果找到返回true。
	 */
	UFUNCTION(BlueprintCallable, Category = "GCS|TraceSystem", Meta = (DefaultToSelf="Actor", ExpandBoolAsExecs="ReturnValue"))
	static bool FindTraceSystemComponent(const AActor* Actor, UGCS_TraceSystemComponent*& Component);

	/**
	 * Initializes the collision trace system.
	 * 初始化碰撞检测系统。
	 */
	UFUNCTION(BlueprintCallable, BlueprintNativeEvent, Category = "GCS|TraceSystem", meta=(DisplayName="Initialize Trace System"))
	void OnInitialize();
	virtual void OnInitialize_Implementation();

	/**
	 * Deinitializes the collision trace system.
	 * 取消初始化碰撞检测系统。
	 */
	UFUNCTION(BlueprintCallable, BlueprintNativeEvent, Category = "GCS|TraceSystem", meta=(DisplayName="Deinitialize Trace System"))
	void OnDeinitialize();
	virtual void OnDeinitialize_Implementation();

	/**
	 * Creates trace instances from definitions.
	 * 从定义创建碰撞检测实例。
	 * @param Definitions The trace definitions. 碰撞检测定义。
	 * @param SourceComponent The primitive component for tracing. 用于追踪的原始组件。
	 * @param SourceObject The source object. 源对象。
	 * @return The created trace instances. 创建的碰撞检测实例。
	 */
	UFUNCTION(BlueprintCallable, Category = "GCS|TraceSystem")
	TArray<FGCS_TraceHandle> AddTracesByDefinitions(const TArray<FGCS_TraceDefinition>& Definitions, UPrimitiveComponent* SourceComponent, UObject* SourceObject);

	/**
	 * Creates trace instances from data table row handles.
	 * 从数据表行句柄创建碰撞检测实例。
	 * @param DefinitionHandles The data table row handles for trace definitions. 碰撞检测定义的数据表行句柄。
	 * @param SourceComponent The primitive component for tracing. 用于追踪的原始组件。
	 * @param SourceObject The source object. 源对象。
	 * @return The created trace instances. 创建的碰撞检测实例。
	 */
	UFUNCTION(BlueprintCallable, Category = "GCS|TraceSystem")
	TArray<FGCS_TraceHandle> AddTracesByDefinitionHandles(UPARAM(meta=(RowType="/Script/GenericCombatSystem.GCS_CollisionTraceDefinition"))
	                                                      const TArray<FDataTableRowHandle>& DefinitionHandles, UPrimitiveComponent* SourceComponent, UObject* SourceObject);

	/**
	 * Creates a single trace instance from a definition.
	 * 从定义创建单个碰撞检测实例。
	 * @param Definition The trace definition. 碰撞检测定义。
	 * @param SourceComponent The primitive component for tracing. 用于追踪的原始组件。
	 * @param SourceObject The source object. 源对象。
	 * @return The created trace instance. 创建的碰撞检测实例。
	 */
	UFUNCTION(BlueprintCallable, Category = "GCS|TraceSystem")
	FGCS_TraceHandle AddTraceByDefinition(const FGCS_TraceDefinition& Definition, UPrimitiveComponent* SourceComponent, UObject* SourceObject);

	/**
	 * Starts traces by tags and source object.
	 * 通过标签和源对象启动碰撞检测。
	 * @param TraceTags The gameplay tags to match. 要匹配的游戏标签。
	 * @param SourceObject The source object. 源对象。
	 * @return The started trace instances. 启动的碰撞检测实例。
	 */
	UFUNCTION(BlueprintCallable, Category = "GCS|TraceSystem")
	TArray<FGCS_TraceHandle> StartTracesByTagsAndSource(const FGameplayTagContainer& TraceTags, const UObject* SourceObject);

	/**
	 * Starts multiple traces by their handles.
	 * 通过句柄启动多个碰撞检测。
	 * @param TraceHandles The trace handles to start. 要启动的碰撞检测句柄。
	 */
	UFUNCTION(BlueprintCallable, Category = "GCS|TraceSystem")
	void StartTracesByHandles(const TArray<FGCS_TraceHandle>& TraceHandles);

	/**
	 * Starts a single trace by its handle.
	 * 通过句柄启动单个碰撞检测。
	 * @param TraceHandle The trace handle to start. 要启动的碰撞检测句柄。
	 */
	UFUNCTION(BlueprintCallable, Category = "GCS|TraceSystem")
	void StartTraceByHandle(const FGCS_TraceHandle& TraceHandle);

	/**
	 * Stops multiple traces by their handles.
	 * 通过句柄停止多个碰撞检测。
	 * @param TraceHandles The trace handles to stop. 要停止的碰撞检测句柄。
	 */
	UFUNCTION(BlueprintCallable, Category = "GCS|TraceSystem")
	void StopTracesByHandles(const TArray<FGCS_TraceHandle>& TraceHandles);

	/**
	 * Stops a single trace by its handle.
	 * 通过句柄停止单个碰撞检测。
	 * @param TraceHandle The trace handle to stop. 要停止的碰撞检测句柄。
	 */
	UFUNCTION(BlueprintCallable, Category = "GCS|TraceSystem")
	void StopTraceByHandle(const FGCS_TraceHandle& TraceHandle);

	/**
	 * Removes a trace by its handle.
	 * 通过句柄移除碰撞检测。
	 * @param TraceHandle The trace handle to remove. 要移除的碰撞检测句柄。
	 */
	UFUNCTION(BlueprintCallable, Category = "GCS|TraceSystem")
	void RemoveTraceByHandle(const FGCS_TraceHandle& TraceHandle);

	/**
	 * Clears all active and cached trace instances.
	 * 清除所有激活和缓存的碰撞检测实例。
	 * @note OnTraceEndPlay event is not fired. OnTraceEndPlay事件不会触发。
	 */
	UFUNCTION(BlueprintCallable, Category = "GCS|TraceSystem")
	void RemoveAllTraces();

	/**
	 * Gets all trace handles with the specified tag.
	 * 获取具有指定标签的所有碰撞检测句柄。
	 * @param TraceToFind The gameplay tag to search for. 要搜索的游戏标签。
	 * @return Array of trace handles with the specified tag. 具有指定标签的碰撞检测句柄数组。
	 */
	UFUNCTION(BlueprintCallable, BlueprintPure, Category = "GCS|TraceSystem")
	TArray<FGCS_TraceHandle> GetTraceHandlesByTag(FGameplayTag TraceToFind) const;

	/**
	 * Gets all trace handles created by the specified source object.
	 * 获取由指定源对象创建的所有碰撞检测句柄。
	 * @param SourceObject The source object to search for. 要搜索的源对象。
	 * @return Array of trace handles from the specified source. 来自指定源的碰撞检测句柄数组。
	 */
	UFUNCTION(BlueprintCallable, BlueprintPure, Category = "GCS|TraceSystem")
	TArray<FGCS_TraceHandle> GetTraceHandlesBySource(const UObject* SourceObject) const;

	/**
	 * Gets all trace handles with the specified tags and source object.
	 * 获取具有指定标签和源对象的所有碰撞检测句柄。
	 * @param TraceTags The gameplay tags to match. 要匹配的游戏标签。
	 * @param SourceObject The source object to match. 要匹配的源对象。
	 * @return Array of trace handles matching the criteria. 匹配条件的碰撞检测句柄数组。
	 */
	UFUNCTION(BlueprintCallable, BlueprintPure, Category = "GCS|TraceSystem")
	TArray<FGCS_TraceHandle> GetTraceHandlesByTagsAndSource(const FGameplayTagContainer& TraceTags, const UObject* SourceObject) const;

	/**
	 * Gets the source actor for the specified trace handle.
	 * 获取指定碰撞检测句柄的源Actor。
	 * @param TraceHandle The trace handle to query. 要查询的碰撞检测句柄。
	 * @return The source actor, or nullptr if not found. 源Actor，如果未找到则返回nullptr。
	 */
	UFUNCTION(BlueprintCallable, BlueprintPure, Category = "GCS|TraceSystem")
	AActor* GetTraceSourceActor(const FGCS_TraceHandle& TraceHandle) const;

	/**
	 * Gets the source component for the specified trace handle.
	 * 获取指定碰撞检测句柄的源组件。
	 * @param TraceHandle The trace handle to query. 要查询的碰撞检测句柄。
	 * @return The source component, or nullptr if not found. 源组件，如果未找到则返回nullptr。
	 */
	UFUNCTION(BlueprintCallable, BlueprintPure, Category = "GCS|TraceSystem")
	UPrimitiveComponent* GetTraceSourceComponent(const FGCS_TraceHandle& TraceHandle) const;

	/**
	 * Checks if the specified trace is currently active.
	 * 检查指定的碰撞检测当前是否激活。
	 * @param TraceHandle The trace handle to check. 要检查的碰撞检测句柄。
	 * @return True if the trace is active. 如果碰撞检测激活则返回true。
	 */
	UFUNCTION(BlueprintCallable, BlueprintPure, Category = "GCS|TraceSystem")
	bool IsTraceActive(const FGCS_TraceHandle& TraceHandle) const;

	virtual TArray<FGCS_TraceHandle> StartTraces(const FGameplayTagContainer& TraceTags, const UObject* SourceObject);

	virtual TArray<FGCS_TraceHandle> AddTraces(const TArray<FGCS_TraceDefinition>& Definitions, UPrimitiveComponent* SourceComponent, UObject* SourceObject);
	virtual TArray<FGCS_TraceHandle> AddTraces(const TArray<FDataTableRowHandle>& DefinitionHandles, UPrimitiveComponent* SourceComponent, UObject* SourceObject);
	virtual FGCS_TraceHandle AddTrace(const FGCS_TraceDefinition& TraceDefinition, UPrimitiveComponent* SourceComponent, UObject* SourceObject);
	virtual FGCS_TraceHandle AddTrace(const FDataTableRowHandle& TraceDefinitionHandle, UPrimitiveComponent* SourceComponent, UObject* SourceObject);

	virtual void StartTraces(const TArray<FGCS_TraceHandle>& TraceHandles);

	virtual void StartTrace(const FGCS_TraceHandle& TraceHandle);

	virtual void StopTraces(const TArray<FGCS_TraceHandle>& TraceHandles);

	virtual void StopTrace(const FGCS_TraceHandle& TraceHandle);

	virtual void RemoveTraces(const TArray<FGCS_TraceHandle>& TraceHandles);
	virtual void RemoveTrace(const FGCS_TraceHandle& TraceHandle);

	/**
	 * Event fired when a trace hits something.
	 * 当碰撞检测命中某物时触发的事件。
	 */
	UPROPERTY(BlueprintAssignable, Category = "GCS|TraceSystem")
	FGCS_OnTraceHitSignature OnTraceHitEvent;

	/**
	 * Event fired when a trace state changes.
	 * 当碰撞检测状态改变时触发的事件。
	 */
	UPROPERTY(BlueprintAssignable, Category = "GCS|TraceSystem")
	FGCS_OnTraceStateChangedSignature OnTraceStateChangedEvent;

	/**
	 * Event fired when a trace starts.
	 * 当碰撞检测开始时触发的事件。
	 */
	UPROPERTY(BlueprintAssignable, Category = "GCS|TraceSystem")
	FGCS_OnTraceStartedSignature OnTraceStartedEvent;

	/**
	 * Event fired when a trace stops.
	 * 当碰撞检测停止时触发的事件。
	 */
	UPROPERTY(BlueprintAssignable, Category = "GCS|TraceSystem")
	FGCS_OnTraceStoppedSignature OnTraceStoppedEvent;

	/**
	 * Event fired when the trace system is destroyed.
	 * 当碰撞检测系统被销毁时触发的事件。
	 */
	FGCS_OnTraceSystemDestroyedSignature OnDestroyedEvent;

protected:
	virtual void OnTraceHitDetected(const FGCS_TraceHandle& TraceHandle, const TArray<FHitResult>& HitResults, const float DeltaTime, const uint32 TickIdx);

	virtual void OnTraceStateChanged(const FGCS_TraceHandle& TraceHandle, bool bNewState);

	/**
	 * 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;

	virtual void OnComponentDestroyed(bool bDestroyingHierarchy) override;

	/**
	 * Whether to auto-initialize on BeginPlay and deinitialize on EndPlay.
	 * 是否在BeginPlay时自动初始化，在EndPlay时自动取消初始化。
	 */
	UPROPERTY(EditAnywhere, Category = "GCS|TraceSystem")
	bool bAutoInitialize{true};

	/**
	 * Default trace definitions created on BeginPlay.
	 * 在BeginPlay时创建的默认碰撞检测定义。
	 * @note SourceComponent will be the actor's main mesh. 源组件会是Actor的主要mesh。
	 */
	UPROPERTY(EditDefaultsOnly, BlueprintReadOnly, Category = "GCS|TraceSystem", meta=(TitleProperty="TraceTag"))
	TArray<FGCS_TraceDefinition> TraceDefinitions;

	FCriticalSection TraceDoneScopeLock;

	TMap<FGCS_TraceHandle, int32> HandleToStateIdx;
	TMultiMap<FGameplayTag, FGCS_TraceHandle> TagToHandles;
	bool bInitialized = false;
};