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

#pragma once

#include "CoreMinimal.h"
#include "GCS_TraceStructLibrary.h"
#include "Engine/CancellableAsyncAction.h"
#include "GCS_AsyncAction_CollisionTrace.generated.h"

class UGCS_TraceSystemComponent;

/**
 * Async action for setting up and listening to collision trace hits.
 * 设置并监听碰撞检测命中的异步动作。
 */
UCLASS()
class GENERICCOMBATSYSTEM_API UGCS_AsyncAction_CollisionTrace : public UCancellableAsyncAction
{
	GENERATED_BODY()

public:
	/**
	 * Creates and activates trace instances from definitions and listens for hits.
	 * 从定义创建并激活碰撞检测实例并监听命中。
	 * @param TraceSystem The collision trace system component. 碰撞检测系统组件。
	 * @param TraceDefinitions The traces definitions will be created and added to collision trace system. 要新建的碰撞实例的定义。
	 * @param PrimitiveComponent The primitive component for tracing. 用于追踪的原始组件。
	 * @param OptionalSourceObject The optional source object. 可选的源对象.
	 * @return The async action instance. 异步动作实例。
	 */
	UFUNCTION(BlueprintCallable, BlueprintCosmetic, Category="GUIS", meta = (WorldContext = "WorldContextObject", BlueprintInternalUseOnly = "true"))
	static UGCS_AsyncAction_CollisionTrace* SetupAndListenForCollisionTraceHit(UGCS_TraceSystemComponent* TraceSystem, const TArray<FGCS_TraceDefinition>& TraceDefinitions,
	                                                                           UPrimitiveComponent* PrimitiveComponent, UObject* OptionalSourceObject = nullptr);

	/**
	 * Activates the async action.
	 * 激活异步动作。
	 */
	virtual void Activate() override;

	/**
	 * Cancels the async action.
	 * 取消异步动作。
	 */
	virtual void Cancel() override;

	/**
	 * Delegate for collision trace hit events.
	 * 碰撞检测命中事件的委托。
	 */
	DECLARE_DYNAMIC_MULTICAST_DELEGATE_TwoParams(FCollisionTraceSignature, const FGCS_TraceHandle, Handle, const FHitResult&, HitResult);

	/**
	 * Called before trace instances are activated.
	 * 在激活碰撞检测实例前调用。
	 */
	/**
	 * Called before trace instances are activated.
	 * 在激活碰撞检测实例前调用。
	 */
	UPROPERTY(BlueprintAssignable)
	FCollisionTraceSignature BeforeActive;

	/**
	 * Fired when a trace instance hits something.
	 * 当碰撞检测实例命中某物时触发。
	 */
	UPROPERTY(BlueprintAssignable)
	FCollisionTraceSignature OnHit;

protected:
	/**
	 * Handles trace instance hit events.
	 * 处理碰撞检测实例命中事件。
	 * @param TraceHandle The trace instance. 碰撞检测实例。
	 * @param HitResult The hit result. 命中结果。
	 */
	UFUNCTION()
	void TraceHitCallback(const FGCS_TraceHandle& TraceHandle, const FHitResult& HitResult);

	/**
	 * The collision system component.
	 * 碰撞系统组件。
	 */
	UPROPERTY()
	TWeakObjectPtr<UGCS_TraceSystemComponent> TraceSystem;

	/**
	 * The primitive component for tracing.
	 * 用于追踪的原始组件。
	 */
	UPROPERTY()
	TWeakObjectPtr<UPrimitiveComponent> SourceComponent;

	/**
	 * The optional source object.
	 * 可选的源对象。
	 */
	UPROPERTY()
	TWeakObjectPtr<UObject> SourceObject;

	/**
	 * The trace definitions to create.
	 * 要创建的碰撞检测定义。
	 */
	UPROPERTY()
	TArray<FGCS_TraceDefinition> TraceDefinitions;

	/**
	 * The monitored trace instances.
	 * 监听的碰撞检测实例。
	 */
	UPROPERTY()
	TArray<FGCS_TraceHandle> TraceHandles;
};