第一次提交

2026-03-03 01:23:02 +08:00
commit 3e434877e8
1053 changed files with 102411 additions and 0 deletions
--- a/Plugins/GCS/Source/GenericCombatSystem/Public/Bullet/GCS_BulletContainer.h
+++ b/Plugins/GCS/Source/GenericCombatSystem/Public/Bullet/GCS_BulletContainer.h
@@ -0,0 +1,82 @@
+// Copyright 2025 https://yuewu.dev/en  All Rights Reserved.
+
+#pragma once
+
+#include "CoreMinimal.h"
+#include "GameplayTagContainer.h"
+#include "GCS_BulletStructLibrary.h"
+#include "Net/Serialization/FastArraySerializer.h"
+#include "UObject/Object.h"
+#include "GCS_BulletContainer.generated.h"
+
+
+struct FGCS_BulletContainer;
+class UGCS_BulletSystemComponent;
+
+/**
+ * Structure representing an equipment entry in the container.
+ * 表示容器中装备条目的结构体。
+ * @note WIP
+ */
+USTRUCT(BlueprintType)
+struct GENERICCOMBATSYSTEM_API FGCS_BulletEntry : public FFastArraySerializerItem
+{
+	GENERATED_BODY()
+
+	friend FGCS_BulletContainer;
+
+	//The request id of this entry.
+	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="GCS")
+	FGuid Id;
+
+	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="GCS")
+	FGCS_BulletSpawnParameters SpawnParameters;
+};
+
+/**
+ * Container for a list of applied equipment.
+ * 存储已应用装备列表的容器。
+ */
+USTRUCT()
+struct GENERICCOMBATSYSTEM_API FGCS_BulletContainer : public FFastArraySerializer
+{
+	GENERATED_BODY()
+
+	FGCS_BulletContainer()
+		: OwningComponent(nullptr)
+	{
+	}
+
+	FGCS_BulletContainer(UGCS_BulletSystemComponent* InComponent)
+		: OwningComponent(InComponent)
+	{
+	}
+
+	void PreReplicatedRemove(const TArrayView<int32> RemovedIndices, int32 FinalSize);
+
+
+	void PostReplicatedAdd(const TArrayView<int32> AddedIndices, int32 FinalSize);
+
+	void PostReplicatedChange(const TArrayView<int32> ChangedIndices, int32 FinalSize);
+	//~End of FFastArraySerializer contract
+
+	bool NetDeltaSerialize(FNetDeltaSerializeInfo& DeltaParms)
+	{
+		return FastArrayDeltaSerialize<FGCS_BulletEntry, FGCS_BulletContainer>(Entries, DeltaParms, *this);
+	}
+
+
+	int32 IndexOfById(const FGuid& Id) const;
+
+	UPROPERTY(VisibleAnywhere, Category="BulletSystem", meta=(ShowOnlyInnerProperties, DisplayName="Bullets"))
+	TArray<FGCS_BulletEntry> Entries;
+
+	UPROPERTY()
+	TObjectPtr<UGCS_BulletSystemComponent> OwningComponent;
+};
+
+template <>
+struct TStructOpsTypeTraits<FGCS_BulletContainer> : TStructOpsTypeTraitsBase2<FGCS_BulletContainer>
+{
+	enum { WithNetDeltaSerializer = true };
+};
--- a/Plugins/GCS/Source/GenericCombatSystem/Public/Bullet/GCS_BulletInstance.h
+++ b/Plugins/GCS/Source/GenericCombatSystem/Public/Bullet/GCS_BulletInstance.h
@@ -0,0 +1,406 @@
+// Copyright 2025 https://yuewu.dev/en  All Rights Reserved.
+
+#pragma once
+
+#include "CoreMinimal.h"
+#include "GCS_BulletStructLibrary.h"
+#include "GCS_EffectCauserInterface.h"
+#include "GameFramework/Actor.h"
+#include "GCS_BulletInstance.generated.h"
+
+class UGCS_AttackRequest_Bullet;
+class UGCS_BulletSubsystem;
+class UProjectileMovementComponent;
+
+/**
+ * Base class for bullet instances.
+ * 子弹实例的基类。
+ */
+UCLASS(Abstract, BlueprintType, NotBlueprintable)
+class GENERICCOMBATSYSTEM_API AGCS_BulletInstance : public AActor, public IGCS_EffectCauserInterface
+{
+	GENERATED_BODY()
+
+	friend UGCS_BulletSubsystem;
+
+public:
+	/**
+	 * Default constructor.
+	 * 默认构造函数。
+	 */
+	AGCS_BulletInstance();
+
+	/**
+	 * Gets lifetime replicated properties.
+	 * 获取生命周期复制属性。
+	 * @param OutLifetimeProps The lifetime properties. 生命周期属性。
+	 */
+	virtual void GetLifetimeReplicatedProps(TArray<FLifetimeProperty>& OutLifetimeProps) const override;
+
+	/**
+	 * Gets the projectile movement component.
+	 * 获取子弹的运动组件。
+	 * @return The projectile movement component. 运动组件。
+	 */
+	UFUNCTION(BlueprintCallable, BlueprintPure, Category="GCS|Bullet")
+	UProjectileMovementComponent* GetProjectileMovementComponent() const;
+
+	/**
+	 * Sets the bullet definition handle.
+	 * 设置子弹定义句柄。
+	 * @param NewHandle The new definition handle. 新定义句柄。
+	 */
+	UFUNCTION(BlueprintCallable, Category="GCS|Bullet")
+	void SetDefinitionHandle(UPARAM(meta=(RowType="/Script/GenericCombatSystem.GCS_BulletDefinition")) FDataTableRowHandle NewHandle);
+
+	/**
+	 * Sets the bullet's unique ID.
+	 * 设置子弹的唯一ID。
+	 * @param NewId The new ID. 新ID。
+	 */
+	void SetBulletId(const FGuid& NewId);
+
+	/**
+	 * Gets the bullet's unique ID.
+	 * 获取子弹的唯一ID。
+	 * @return The bullet ID. 子弹ID。
+	 */
+	UFUNCTION(BlueprintCallable, BlueprintPure, Category="GCS|Bullet")
+	FGuid GetBulletId() const;
+
+	/**
+	 * Sets the parent bullet ID for bullet chains.
+	 * 设置子弹链的父子弹ID。
+	 * @param NewParentId The parent bullet ID. 父子弹ID。
+	 */
+	UFUNCTION(BlueprintCallable, BlueprintNativeEvent, Category="GCS|Bullet")
+	void SetParentBulletId(FGuid NewParentId);
+
+	/**
+	 * Gets the parent bullet ID.
+	 * 获取父子弹ID。
+	 * @return The parent bullet ID. 父子弹ID。
+	 */
+	UFUNCTION(BlueprintCallable, BlueprintPure, Category="GCS|Bullet")
+	FGuid GetParentBulletId() const;
+
+	/**
+	 * Launches the bullet.
+	 * 发射子弹。
+	 */
+	UFUNCTION(BlueprintCallable, BlueprintNativeEvent, Category="GCS|Bullet")
+	void LaunchBullet();
+
+	/**
+	 * Sets the hit result for the bullet.
+	 * 设置子弹的命中结果。
+	 * @param NewHitResult The hit result. 命中结果。
+	 */
+	UFUNCTION(BlueprintCallable, Category="GCS|Bullet", meta=(DisplayName="Set Bullet HitResult"))
+	void SetHitResult(const FHitResult& NewHitResult);
+
+	/**
+	 * Gets the latest hit result.
+	 * 获取最新的命中结果。
+	 * @return The hit result. 命中结果。
+	 */
+	UFUNCTION(BlueprintCallable, BlueprintPure, Category="GCS|Bullet", meta=(DisplayName="Get Bullet HitResult"))
+	const FHitResult& GetHitResult() const;
+
+	/**
+	 * Checks if the bullet has gameplay authority.
+	 * 检查子弹是否具有游戏权限。
+	 * @return True if the bullet has authority. 如果子弹具有权限返回true。
+	 */
+	UFUNCTION(BlueprintCallable, BlueprintPure, Category="GCS|Bullet")
+	bool HasGameplayAuthority() const;
+
+	/**
+	 * Called after network initialization.
+	 * 网络初始化后调用。
+	 */
+	virtual void PostNetInit() override;
+
+	/**
+	 * Called after receiving network data.
+	 * 接收网络数据后调用。
+	 */
+	virtual void PostNetReceive() override;
+
+	/**
+	 * Handles locally predicted bullet instances.
+	 * 处理本地预测的子弹实例。
+	 * @param PredictedBullet The predicted bullet instance. 预测的子弹实例。
+	 */
+	UFUNCTION(BlueprintCallable, BlueprintNativeEvent, Category="GCS|Bullet")
+	void FoundLocalPredictedBullet(AGCS_BulletInstance* PredictedBullet);
+
+	// Effect causer interface
+	/**
+	 * Gets the gameplay effect spec handle.
+	 * 获取游戏效果规格句柄。
+	 * @param OutHandle The effect spec handle (output). 效果规格句柄（输出）。
+	 * @return True if successful. 如果成功返回true。
+	 */
+	virtual bool GetEffectSpecHandle_Implementation(FGameplayEffectSpecHandle& OutHandle) override;
+
+	/**
+	 * Gets the gameplay effect container.
+	 * 获取游戏效果容器。
+	 * @return The effect container. 效果容器。
+	 */
+	virtual FGGA_GameplayEffectContainer GetEffectContainer_Implementation() const override;
+
+	/**
+	 * Gets the effect container level override.
+	 * 获取效果容器级别覆盖。
+	 * @return The level override. 级别覆盖。
+	 */
+	virtual int32 GetEffectContainerLevelOverride_Implementation() const override;
+
+	/**
+	 * Sets the effect container spec.
+	 * 设置效果容器规格。
+	 * @param InEffectContainerSpec The effect container spec. 效果容器规格。
+	 */
+	virtual void SetEffectContainerSpec_Implementation(const FGGA_GameplayEffectContainerSpec& InEffectContainerSpec) override;
+
+	/**
+	 * Gets the effect container spec.
+	 * 获取效果容器规格。
+	 * @return The effect container spec. 效果容器规格。
+	 */
+	virtual FGGA_GameplayEffectContainerSpec GetEffectContainerSpec_Implementation() const override;
+
+	/**
+	 * Gets the effect class.
+	 * 获取效果类。
+	 * @return The effect class. 效果类。
+	 */
+	virtual TSubclassOf<UGameplayEffect> GetEffectClass_Implementation() const override;
+
+	/**
+	 * Gets the effect level.
+	 * 获取效果级别。
+	 * @return The effect level. 效果级别。
+	 */
+	virtual int32 GetEffectLevel_Implementation() const override;
+
+	/**
+	 * Sets the effect spec.
+	 * 设置效果规格。
+	 * @param InEffectSpec The effect spec. 效果规格。
+	 */
+	virtual void SetEffectSpec_Implementation(FGameplayEffectSpecHandle& InEffectSpec) override;
+
+	/**
+	 * Gets the bullet's shape component.
+	 * 获取子弹的形状组件。
+	 * @return The shape component. 形状组件。
+	 */
+	UFUNCTION(BlueprintCallable, BlueprintPure, BlueprintNativeEvent, Category="GCS|Bullet")
+	UShapeComponent* GetBulletShape() const;
+	virtual UShapeComponent* GetBulletShape_Implementation() const;
+
+protected:
+	/**
+	 * Called when the game starts or when spawned.
+	 * 游戏开始或生成时调用。
+	 */
+	virtual void BeginPlay() override;
+
+	/**
+	 * Called when the game ends or the bullet is destroyed.
+	 * 游戏结束或子弹销毁时调用。
+	 * @param EndPlayReason The reason for ending. 结束原因。
+	 */
+	virtual void EndPlay(const EEndPlayReason::Type EndPlayReason) override;
+
+	/**
+	 * Called when the bullet is taken from the pool with a valid definition.
+	 * 子弹从池中取出且具有有效定义时调用。
+	 */
+	UFUNCTION(BlueprintCallable, BlueprintNativeEvent, Category="GCS|Bullet")
+	void OnBulletBeginPlay();
+
+	/**
+	 * Called when the bullet is returned to the pool and deactivated.
+	 * 子弹返回池中并停用时调用。
+	 */
+	UFUNCTION(BlueprintCallable, BlueprintNativeEvent, Category="GCS|Bullet")
+	void OnBulletEndPlay();
+
+	/**
+	 * Records the initial location and rotation of the bullet.
+	 * 记录子弹的初始位置和旋转。
+	 */
+	UFUNCTION(BlueprintCallable, Category="GCS|Bullet")
+	void SetupInitialLocationAndRotation();
+
+	/**
+	 * Refreshes the bullet's travel states.
+	 * 刷新子弹的移动状态。
+	 */
+	UFUNCTION(BlueprintCallable, Category="GCS|Bullet")
+	virtual void RefreshTravelStates();
+
+	/**
+	 * Checks if the hit result should be penetrated.
+	 * 检查命中结果是否应穿透。
+	 * @param InHitResult The hit result. 命中结果。
+	 * @return True if the hit should be penetrated. 如果命中应穿透返回true。
+	 */
+	UFUNCTION(BlueprintCallable, BlueprintPure, Category="GCS|Bullet")
+	virtual bool ShouldPenetrateHitResult(const FHitResult& InHitResult) const;
+
+	/**
+	 * Checks if a bullet chain should be generated.
+	 * 检查是否应生成子弹链。
+	 * @return True if a bullet chain should be generated. 如果应生成子弹链返回true。
+	 */
+	UFUNCTION(BlueprintCallable, BlueprintPure, BlueprintNativeEvent, Category="GCS|Bullet")
+	bool ShouldGenerateBullet();
+
+	/**
+	 * Handles bullet chain logic on hit.
+	 * 处理命中时的子弹链逻辑。
+	 */
+	UFUNCTION(BlueprintCallable, BlueprintNativeEvent, Category="GCS|Bullet")
+	void HandleBulletHitChains();
+
+	/**
+	 * Applies gameplay effects to the hit result.
+	 * 对命中结果应用游戏效果。
+	 * @param HitResult The hit result. 命中结果。
+	 */
+	UFUNCTION(BlueprintCallable, BlueprintNativeEvent, Category="GCS|Bullet")
+	void ApplyGameplayEffects(FHitResult HitResult);
+
+	/**
+	 * Called when the bullet ID is replicated.
+	 * 子弹ID复制时调用。
+	 * @param Prev The previous bullet ID. 之前的子弹ID。
+	 */
+	UFUNCTION()
+	virtual void OnRep_BulletId(FGuid Prev);
+
+	/**
+	 * Called when the bullet definition is replicated.
+	 * 子弹定义复制时调用。
+	 */
+	UFUNCTION()
+	void OnRep_BulletDefinition();
+
+	/**
+	 * Unique ID of the bullet.
+	 * 子弹的唯一ID。
+	 */
+	UPROPERTY(VisibleAnywhere, BlueprintReadOnly, ReplicatedUsing=OnRep_BulletId, Category="GCS|BulletState")
+	FGuid BulletId;
+
+	/**
+	 * Whether the bullet is locally predicted.
+	 * 子弹是否为本地预测。
+	 */
+	UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category="GCS|BulletState")
+	bool bIsLocalPredicting{false};
+
+	/**
+	 * Whether the bullet was spawned on the server.
+	 * 子弹是否在服务器上生成。
+	 */
+	UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category="GCS|BulletState")
+	bool bServerInitiated{false};
+
+	/**
+	 * Parent bullet ID for bullet chains.
+	 * 子弹链的父子弹ID。
+	 */
+	UPROPERTY(VisibleAnywhere, Category="GCS|BulletState")
+	FGuid ParentBulletId;
+
+	/**
+	 * The associated attack request.
+	 * 关联的攻击请求。
+	 */
+	UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category="GCS|BulletState")
+	TObjectPtr<const UGCS_AttackRequest_Bullet> Request;
+
+	/**
+	 * Handle to the bullet definition.
+	 * 子弹定义的句柄。
+	 */
+	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="GCS|Bullet", ReplicatedUsing=OnRep_BulletDefinition, meta=(ExposeOnSpawn))
+	FDataTableRowHandle DefinitionHandle;
+
+	/**
+	 * Loaded bullet definition.
+	 * 加载的子弹定义。
+	 */
+	UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category="GCS|BulletState")
+	FGCS_BulletDefinition Definition;
+
+	/**
+	 * The projectile movement component.
+	 * 子弹的运动组件。
+	 */
+	UPROPERTY(VisibleAnywhere, Category="GCS|Bullet")
+	TObjectPtr<UProjectileMovementComponent> ProjectileMovement;
+
+	/**
+	 * The gameplay effect spec carried by the bullet.
+	 * 子弹携带的游戏效果规格。
+	 */
+	UPROPERTY(VisibleAnywhere, Category="GCS|BulletState")
+	FGameplayEffectSpecHandle EffectSpecHandle;
+
+	/**
+	 * The gameplay effect container spec carried by the bullet.
+	 * 子弹携带的游戏效果容器规格。
+	 */
+	UPROPERTY(VisibleAnywhere, Category = "GCS|BulletState")
+	FGGA_GameplayEffectContainerSpec EffectContainerSpec;
+
+	/**
+	 * Index for bullet chains.
+	 * 子弹链的索引。
+	 */
+	UPROPERTY()
+	int32 ChainIndex{0};
+
+	/**
+	 * Initial location of the bullet.
+	 * 子弹的初始位置。
+	 */
+	UPROPERTY(BlueprintReadWrite, EditDefaultsOnly, Category="GCS|BulletState")
+	FVector InitialActorLocation;
+
+	/**
+	 * Initial rotation of the bullet.
+	 * 子弹的初始旋转。
+	 */
+	UPROPERTY(BlueprintReadWrite, EditDefaultsOnly, Category="GCS|BulletState")
+	FRotator InitialActorRotation;
+
+	/**
+	 * The latest hit result.
+	 * 最新的命中结果。
+	 */
+	UPROPERTY(VisibleAnywhere, Category="GCS|BulletState")
+	FHitResult LastHitResult;
+
+	/**
+	 * Distance traveled by the bullet.
+	 * 子弹的移动距离。
+	 */
+	UPROPERTY(BlueprintReadWrite, VisibleAnywhere, Category="GCS|BulletState")
+	double TraveledDistance{0.0f};
+
+public:
+	/**
+	 * Called every frame.
+	 * 每帧调用。
+	 * @param DeltaTime Time since last frame. 上一帧以来的时间。
+	 */
+	virtual void Tick(float DeltaTime) override;
+};
--- a/Plugins/GCS/Source/GenericCombatSystem/Public/Bullet/GCS_BulletStructLibrary.h
+++ b/Plugins/GCS/Source/GenericCombatSystem/Public/Bullet/GCS_BulletStructLibrary.h
@@ -0,0 +1,351 @@
+// Copyright 2025 https://yuewu.dev/en  All Rights Reserved.
+
+#pragma once
+
+#include "CoreMinimal.h"
+#include "GCS_CombatStructLibrary.h"
+#include "Runtime/Launch/Resources/Version.h"
+#if ENGINE_MINOR_VERSION < 5
+#include "InstancedStruct.h"
+#else
+#include "StructUtils/InstancedStruct.h"
+#endif
+#include "Collision/GCS_TraceStructLibrary.h"
+#include "UObject/Object.h"
+#include "GCS_BulletStructLibrary.generated.h"
+
+class UGCS_AttackRequest_Bullet;
+class UNiagaraSystem;
+class AGCS_BulletInstance;
+
+
+/**
+ * Base struct allow you to extend the bullet definition's fields using C++.
+ * 基础结构体，允许你通过C++拓展子弹定义的字段。
+ */
+USTRUCT(BlueprintType, meta=(Hidden))
+struct GENERICCOMBATSYSTEM_API FGCS_BulletDefinitionExtension
+{
+	GENERATED_BODY()
+};
+
+
+/**
+ * Data structure defining bullet properties and behavior.
+ * 定义子弹属性和行为的数据结构。
+ */
+USTRUCT(BlueprintType, meta=(DisplayName="GCS Bullet Definition"))
+struct GENERICCOMBATSYSTEM_API FGCS_BulletDefinition : public FTableRowBase
+{
+	GENERATED_BODY()
+
+	/**
+	 * The bullet actor class.
+	 * 子弹Actor类。
+	 */
+	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Common", meta=(AllowAbstract="false"))
+	TSoftClassPtr<AGCS_BulletInstance> BulletActorClass;
+
+	/**
+	 * Duration for which the bullet exists (-1 for infinite).
+	 * 子弹存在的持续时间（-1表示无限）。	
+	 */
+	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Common")
+	float Duration{3.0};
+
+	/**
+	 * Number of bullets fired at once.
+	 * 一次性发射的子弹数量。
+	 */
+	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Launch Configuration", meta=(ClampMin=1, UIMin=1))
+	int32 BulletCount{1};
+
+	/**
+	 * Yaw angle for bullet launch.
+	 * 子弹发射的水平角。
+	 */
+	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Launch Configuration")
+	float LaunchAngle{0.0f};
+
+	/**
+	 * Yaw angle interval between bullets.
+	 * 子弹之间的水平角间隔。
+	 */
+	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Launch Configuration")
+	float LaunchAngleInterval{10.0f};
+
+	/**
+	 * Pitch angle for bullet launch.
+	 * 子弹发射的仰角。
+	 */
+	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Launch Configuration")
+	float LaunchElevationAngle{0.0f};
+
+	/**
+	 * Distance at which bullet attenuation begins.
+	 * 子弹开始衰减的距离。
+	 */
+	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Movement", meta=(Units="cm"))
+	float AttenuationRange{800.0f};
+
+	/**
+	 * Gravity scale within the attenuation range.
+	 * 衰减范围内的重力系数。
+	 */
+	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Movement")
+	float GravityScaleInRange{1.0f};
+
+	/**
+	 * Gravity scale outside the attenuation range.
+	 * 衰减范围外的重力系数。
+	 */
+	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Movement")
+	float GravityScaleOutRage{1.0f};
+
+	/**
+	 * Initial hit radius for the bullet.
+	 * 子弹的初始命中半径。
+	 */
+	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Movement", meta=(Units="cm"))
+	float InitialHitRadius{20.0f};
+
+	/**
+	 * Final hit radius for the bullet (-1 to use initial radius).
+	 * 子弹的最终命中半径（-1使用初始半径）。
+	 */
+	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Movement", meta=(Units="cm"))
+	float FinalHitRadius{-1.0f};
+
+	/**
+	 * Initial speed of the bullet.
+	 * 子弹的初始速度。
+	 */
+	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Movement", meta=(Units="cm"))
+	float InitialSpeed{1500.0f};
+
+	/**
+	 * Minimum speed of the bullet.
+	 * 子弹的最小速度。
+	 */
+	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Movement", meta=(Units="cm"))
+	float MinSpeed{1500.0f};
+
+	/**
+	 * Maximum speed of the bullet.
+	 * 子弹的最大速度。
+	 */
+	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Movement", meta=(Units="cm"))
+	float MaxSpeed{1500.0f};
+
+	/**
+	 * Handle to the attack definition for the bullet.
+	 * 子弹的攻击定义句柄。
+	 */
+	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Attack", meta=(RowType="/Script/GenericCombatSystem.GCS_AttackDefinition"))
+	FDataTableRowHandle AttackDefinition;
+
+	/**
+	 * Trace definitions for hit detection.
+	 * 用于命中检测的碰撞检测定义。
+	 * @note Overrides trace definitions in the bullet instance class.
+	 * @注意 覆盖子弹实例类中的碰撞检测定义。
+	 */
+	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Trace")
+	TArray<FGCS_TraceDefinition> TraceDefinitions;
+
+	/**
+	 * Visual effect for the bullet projectile (Niagara).
+	 * 子弹的视觉效果（Niagara）。
+	 */
+	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="VFX")
+	TSoftObjectPtr<UNiagaraSystem> ProjectileFX;
+
+	/**
+	 * Visual effect for the bullet projectile (Cascade).
+	 * 子弹的视觉效果（Cascade）。
+	 */
+	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="VFX")
+	TSoftObjectPtr<UParticleSystem> ProjectileFX_Cascade;
+
+	/**
+	 * Visual effect for bullet impact (Niagara).
+	 * 子弹命中的视觉效果（Niagara）。
+	 */
+	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="VFX")
+	TSoftObjectPtr<UNiagaraSystem> ImpactFX;
+
+	/**
+	 * Visual effect for bullet impact (Cascade).
+	 * 子弹命中的视觉效果（Cascade）。
+	 */
+	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="VFX")
+	TSoftObjectPtr<UParticleSystem> ImpactFX_Cascade;
+
+	/**
+	 * Sound effect for bullet impact.
+	 * 子弹命中的音效。
+	 */
+	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="SFX")
+	TSoftObjectPtr<USoundBase> ImpactSFX;
+
+	/**
+	 * Sound effect attached to the bullet projectile.
+	 * 附着在子弹上的音效。
+	 */
+	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="SFX")
+	TSoftObjectPtr<USoundBase> ProjectileSFX;
+
+	/**
+	 * Sound effect played once when the bullet spawns.
+	 * 子弹生成时播放一次的音效。
+	 */
+	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="SFX")
+	TSoftObjectPtr<USoundBase> SpawnSFX;
+
+	/**
+	 * Whether the bullet penetrates characters/pawns.
+	 * 子弹是否穿透角色/Pawn。
+	 */
+	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Penetration")
+	bool bPenetrateCharacter{false};
+
+	/**
+	 * Whether the bullet penetrates map geometry.
+	 * 子弹是否穿透地图几何体。
+	 */
+	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Penetration")
+	bool bPenetrateMap{false};
+
+	/**
+	 * Handle to the bullet definition to spawn on hit/expiration.
+	 * 命中或失效时生成的子弹定义句柄。
+	 * @note Cannot be the same as this bullet.
+	 * @注意 不能与此子弹相同。
+	 */
+	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Hit Configuration", meta=(RowType="/Script/GenericCombatSystem.GCS_BulletDefinition"))
+	FDataTableRowHandle HitBulletDefinition;
+
+	/**
+	 * Condition for launching bullet chains.
+	 * 子弹链的发射条件。
+	 */
+	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Hit Configuration", meta=(Categories="GGF.Combat.Bullet.LaunchCond"))
+	FGameplayTag LaunchCondition{FGameplayTag::EmptyTag};
+
+	/**
+	 * Native Instanced struct for extending the bullet definition.
+	 * 实例化结构体用于扩充子弹定义的字段。
+	 * @attention For C++ users only. 仅针对C++用户。
+	 */
+	UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "Extension")
+	TInstancedStruct<FGCS_BulletDefinitionExtension> NativeExtension;
+
+	/**
+	 * Blueprint Instanced struct for extending the bullet definition.
+	 * 实例化结构体用于扩充子弹定义的字段。
+	 * @attention For blueprint users only. 仅针对蓝图用户。
+	 */
+	UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "Extension")
+	FInstancedStruct Extension;
+
+	/**
+	 * Custom user settings for extending the bullet definition.
+	 * 扩展子弹定义的自定义用户设置。
+	 */
+	UE_DEPRECATED(1.5, "Using extension field to add custom fields!")
+	UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "Deprecated", meta=(ForceInlineRow, BaseStruct = "/Script/GenericCombatSystem.GCS_UserSetting"))
+	TMap<FGameplayTag, FInstancedStruct> UserSettings;
+
+	/**
+	 * Shares the hit history to sub bullet.(prevent repeat hit for whole bullet chains.)
+	 */
+	// UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Hit Configuration",meta=(Categories="GGF.Combat.Bullet.LaunchCond"))
+	// bool bUseSharedHitList{true};
+
+	/**
+	 * The amount of time between a bullet hits something and when it explodes.
+	 */
+	// UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Hit Configuration", meta=(Units="s", ClampMin=0))
+	// float ExplosionDelay{0.0};
+
+	// Emitter will be added in next version.
+
+	// UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Emitter", meta=(RowType="/Script/GenericCombatSystem.GCS_BulletDefinition"))
+	// FDataTableRowHandle EmitterBulletDefinition;
+	//
+	// UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Emitter")
+	// float EmitterInitialWaitTime{0};
+	//
+	// UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Emitter")
+	// float EmitterMinShootInterval{0};
+	//
+	// UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Emitter")
+	// float EmitterMaxShootInterval{0};
+};
+
+
+/**
+ * Parameters for spawning bullets.
+ * 子弹生成参数。
+ */
+USTRUCT(BlueprintType)
+struct GENERICCOMBATSYSTEM_API FGCS_BulletSpawnParameters
+{
+	GENERATED_BODY()
+
+	/**
+	 * The owner of the bullet.
+	 * 子弹的拥有者。
+	 */
+	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="GCS")
+	TObjectPtr<AActor> Owner{nullptr};
+
+	/**
+	 * Handle to the bullet definition.
+	 * 子弹定义的句柄。
+	 */
+	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="GCS", meta=(RowType="/Script/GenericCombatSystem.GCS_BulletDefinition"))
+	FDataTableRowHandle DefinitionHandle;
+
+	/**
+	 * Transform for spawning the bullet.
+	 * 子弹生成时的变换。
+	 */
+	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="GCS")
+	FTransform SpawnTransform{FTransform::Identity};
+
+	/**
+	 * The associated attack request.
+	 * 关联的攻击请求。
+	 */
+	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="GCS")
+	TObjectPtr<const UGCS_AttackRequest_Bullet> Request{nullptr};
+
+	/**
+	 * Whether the bullet is locally predicted.
+	 * 子弹是否为本地预测。
+	 */
+	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="GCS")
+	bool bIsLocalPredicting{false};
+
+	/**
+	 * IDs for locally predicted bullets.
+	 * 本地预测子弹的ID。
+	 */
+	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="GCS", meta=(DisplayName="Local Predicting Bullet Ids"))
+	TArray<FGuid> OverrideBulletIds;
+
+	/**
+	 * ID of the parent bullet (for bullet chains).
+	 * 父子弹的ID（用于子弹链）。
+	 */
+	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="GCS")
+	FGuid ParentId;
+
+	/**
+	 * Returns a debug string representation.
+	 * 返回调试字符串表示。
+	 * @return The debug string. 调试字符串。
+	 */
+	FString ToDebugString() const;
+};
--- a/Plugins/GCS/Source/GenericCombatSystem/Public/Bullet/GCS_BulletSubsystem.h
+++ b/Plugins/GCS/Source/GenericCombatSystem/Public/Bullet/GCS_BulletSubsystem.h
@@ -0,0 +1,101 @@
+// Copyright 2025 https://yuewu.dev/en  All Rights Reserved.
+
+#pragma once
+
+#include "CoreMinimal.h"
+#include "GCS_BulletStructLibrary.h"
+#include "Subsystems/WorldSubsystem.h"
+#include "GCS_BulletSubsystem.generated.h"
+
+class UGCS_AttackRequest_Bullet;
+class AGCS_BulletInstance;
+
+
+/**
+ * Subsystem for managing bullet spawning and lifecycle.
+ * 管理子弹生成和生命周期的子系统。
+ */
+UCLASS()
+class GENERICCOMBATSYSTEM_API UGCS_BulletSubsystem : public UWorldSubsystem
+{
+	GENERATED_BODY()
+
+public:
+	static UGCS_BulletSubsystem* Get(const UWorld* World);
+
+	/**
+	 * Spawns bullets based on the provided parameters.
+	 * 根据提供的参数生成子弹。
+	 * @param SpawnParameters The spawn parameters. 生成参数。
+	 * @return The spawned bullet instances. 生成的子弹实例。
+	 */
+	UFUNCTION(BlueprintCallable, Category="GCS|Bullet")
+	virtual TArray<AGCS_BulletInstance*> SpawnBullets(const FGCS_BulletSpawnParameters& SpawnParameters);
+
+	/**
+	 * Gets the IDs of the provided bullet instances.
+	 * 获取提供的子弹实例的ID。
+	 * @param Instances The bullet instances. 子弹实例。
+	 * @return The IDs of the bullets. 子弹的ID。
+	 */
+	UFUNCTION(BlueprintCallable, BlueprintPure, Category="GCS|Bullet")
+	virtual TArray<FGuid> GetIdsFromBullets(TArray<AGCS_BulletInstance*> Instances);
+
+	/**
+	 * Gets or creates bullet instances based on parameters and definition.
+	 * 根据参数和定义获取或创建子弹实例。
+	 * @param SpawnParameters The spawn parameters. 生成参数。
+	 * @param Definition The bullet definition. 子弹定义。
+	 * @return The bullet instances. 子弹实例。
+	 */
+	TArray<AGCS_BulletInstance*> GetOrCreateBulletInstances(const FGCS_BulletSpawnParameters& SpawnParameters, const FGCS_BulletDefinition& Definition);
+
+	/**
+	 * Retrieves a bullet instance from the pool.
+	 * 从池中获取子弹实例。
+	 * @param BulletClass The class of the bullet. 子弹的类。
+	 * @return The bullet instance. 子弹实例。
+	 */
+	AGCS_BulletInstance* TakeBulletFromPool(TSubclassOf<AGCS_BulletInstance> BulletClass);
+
+	/**
+	 * Destroys a bullet by its ID.
+	 * 根据ID销毁子弹。
+	 * @param BulletId The bullet ID. 子弹ID。
+	 */
+	UFUNCTION(BlueprintCallable, Category="GCS|Bullet")
+	virtual void DestroyBullet(FGuid BulletId);
+
+	/**
+	 * Creates a single bullet instance.
+	 * 创建单个子弹实例。
+	 * @param SpawnParameters The spawn parameters. 生成参数。
+	 * @param Definition The bullet definition. 子弹定义。
+	 * @return The created bullet instance. 创建的子弹实例。
+	 */
+	AGCS_BulletInstance* CreateBulletInstance(const FGCS_BulletSpawnParameters& SpawnParameters, const FGCS_BulletDefinition& Definition);
+
+	/**
+	 * Loads a bullet definition from a handle.
+	 * 从句柄加载子弹定义。
+	 * @param Handle The bullet definition handle. 子弹定义句柄。
+	 * @param OutDefinition The loaded definition (output). 加载的定义（输出）。
+	 * @return True if the definition was loaded successfully. 如果定义加载成功返回true。
+	 */
+	UFUNCTION(BlueprintCallable, BlueprintPure=false, Category="GCS|Bullet", meta=(ExpandBoolAsExecs="ReturnValue"))
+	virtual bool LoadBulletDefinition(const FDataTableRowHandle& Handle, FGCS_BulletDefinition& OutDefinition);
+
+	/**
+	 * Active bullet instances mapped by their IDs.
+	 * 按ID映射的激活子弹实例。
+	 */
+	UPROPERTY()
+	TMap<FGuid, TObjectPtr<AGCS_BulletInstance>> BulletInstances;
+
+	/**
+	 * Pool of bullet instances for reuse.
+	 * 用于重用的子弹实例池。
+	 */
+	UPROPERTY()
+	TArray<TObjectPtr<AGCS_BulletInstance>> BulletPools;
+};
--- a/Plugins/GCS/Source/GenericCombatSystem/Public/Bullet/GCS_BulletSystemComponent.h
+++ b/Plugins/GCS/Source/GenericCombatSystem/Public/Bullet/GCS_BulletSystemComponent.h
@@ -0,0 +1,51 @@
+// Copyright 2025 https://yuewu.dev/en  All Rights Reserved.
+
+#pragma once
+
+#include "CoreMinimal.h"
+#include "GCS_BulletStructLibrary.h"
+#include "Components/ActorComponent.h"
+#include "GCS_BulletSystemComponent.generated.h"
+
+
+/**
+ * @note WIP
+ */
+UCLASS(Abstract, ClassGroup=(GCS), meta=(BlueprintSpawnableComponent))
+class GENERICCOMBATSYSTEM_API UGCS_BulletSystemComponent : public UActorComponent
+{
+	GENERATED_BODY()
+
+public:
+	// Sets default values for this component's properties
+	UGCS_BulletSystemComponent();
+
+protected:
+	// Called when the game starts
+	virtual void BeginPlay() override;
+
+public:
+	/**
+	 * Gets the bullet system component from an actor.
+	 * 从Actor获取子弹系统组件。
+	 * @param Actor The actor to query. 要查询的Actor。
+	 * @return The bullet system component. 子弹系统组件。
+	 */
+	UFUNCTION(BlueprintCallable, BlueprintPure, Category = "GCS|BulletSystem", Meta = (DefaultToSelf="Actor"))
+	static UGCS_BulletSystemComponent* GetBulletSystemComponent(const AActor* Actor);
+
+	/**
+	 * Finds the bullet 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|BulletSystem", Meta = (DefaultToSelf="Actor", ExpandBoolAsExecs="ReturnValue"))
+	static bool FindBulletSystemComponent(const AActor* Actor, UGCS_BulletSystemComponent*& Component);
+
+	UFUNCTION(BlueprintCallable, BlueprintPure, Category = "GCS|BulletSystem")
+	void SpawnBullet(const FGCS_BulletSpawnParameters& SpawnParameters);
+
+	// virtual TArray<AGCS_BulletInstance*> SpawnBulletInternal(const FGCS_BulletSpawnParameters& SpawnParameters);
+};
--- a/Plugins/GCS/Source/GenericCombatSystem/Public/Bullet/GCS_SphereBulletInstance.h
+++ b/Plugins/GCS/Source/GenericCombatSystem/Public/Bullet/GCS_SphereBulletInstance.h
@@ -0,0 +1,55 @@
+// Copyright 2025 https://yuewu.dev/en  All Rights Reserved.
+
+#pragma once
+
+#include "CoreMinimal.h"
+#include "GCS_BulletInstance.h"
+#include "GCS_SphereBulletInstance.generated.h"
+
+class USphereComponent;
+
+/**
+ * Bullet instance with a spherical collision shape.
+ * 具有球形碰撞形状的子弹实例。
+ */
+UCLASS(Abstract, Blueprintable)
+class GENERICCOMBATSYSTEM_API AGCS_SphereBulletInstance : public AGCS_BulletInstance
+{
+	GENERATED_BODY()
+
+public:
+	/**
+	 * Default constructor.
+	 * 默认构造函数。
+	 */
+	AGCS_SphereBulletInstance();
+
+	/**
+	 * Gets the bullet's shape component.
+	 * 获取子弹的形状组件。
+	 * @return The sphere component. 球形组件。
+	 */
+	virtual UShapeComponent* GetBulletShape_Implementation() const override;
+
+protected:
+	/**
+	 * Called when the game starts or when spawned.
+	 * 游戏开始或生成时调用。
+	 */
+	virtual void BeginPlay() override;
+
+	/**
+	 * The sphere component for collision detection.
+	 * 用于碰撞检测的球形组件。
+	 */
+	UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category="GCS")
+	TObjectPtr<USphereComponent> Sphere;
+
+public:
+	/**
+	 * Called every frame.
+	 * 每帧调用。
+	 * @param DeltaTime Time since last frame. 上一帧以来的时间。
+	 */
+	virtual void Tick(float DeltaTime) override;
+};