Enhanced Projectile

Enhanced Projectile is a data-driven Unreal Engine projectile framework built around StateTree behavior, reusable projectile definitions, Blueprint-friendly spawn helpers, pooling, prediction validation, and editor-side simulation tools.

It is intended for gameplay teams that need more than a one-off ProjectileMovementComponent: homing shots, bouncing grenades, piercing bolts, scatter fragments, delayed detonation, source/target context, surface-specific responses, and repeatable previews all live in one plugin.

Highlights

• StateTree-first projectile behavior with a ready task catalog for movement, homing, impact waiting, health, detonation, chained spawns, context reads, and cleanup.
• UEnhancedProjectileDefinition data assets that centralize class, StateTree, movement, collision, lifetime, surface response, FX, spawn profiles, network, prediction, and pooling settings.
• AEnhancedProjectileBase actor with collision, movement, StateTree, context, damage/effect/surface adapters, health, impact policy, debug snapshots, and pooling lifecycle hooks.
• Blueprint and C++ spawn helpers for direct transforms, components, owner weapon sockets, target actors, spreads, radial bursts, and definition-authored spawn profiles.
• Runtime context payloads that carry owner, weapon, source socket, target, gameplay tags, floats, ints, vectors, names, and objects into Blueprint and StateTree logic.
• Pooling support through UEnhancedProjectilePoolSubsystem and per-spawn or per-definition pool settings.
• Client prediction validation support through UEnhancedProjectilePredictionComponent.
• Editor simulator under Window > Enhanced Projectile Simulator plus a commandlet for repeatable projectile scenario checks.
• 20 sample projectile definitions, Blueprints, and StateTrees in Content/Samples.

Requirements

• Unreal Engine 5.7 or a compatible Unreal Engine 5.x build with the same StateTree APIs.
• A C++ Unreal project. Blueprint-only projects can use the plugin after adding any C++ class or converting to a C++ project.
• Git LFS for sample .uasset files.
• Enabled Unreal plugins: StateTree, GameplayStateTree, PropertyBindingUtils, Iris, and Niagara. The plugin descriptor enables these dependencies for the plugin.

Installation

Clone or copy this repository into your project's plugin folder:

cd YourProject/Plugins
git clone https://github.com/HanYe0817/UE5-EnhancedProjectile.git EnhancedProjectile
cd EnhancedProjectile
git lfs pull

Then:

1. Regenerate project files.
2. Build your game target from Visual Studio, Rider, or Unreal Build Tool.
3. Open the editor and confirm Edit > Plugins > Gameplay > Enhanced Projectile is enabled.
4. Enable Show Plugin Content in the Content Browser to inspect EnhancedProjectile Content/Samples.

For a deeper setup path, see Docs/INSTALLATION.md.

Quick Start

1. Create or duplicate a projectile Blueprint based on AEnhancedProjectileBase.
2. Create a UEnhancedProjectileDefinition data asset.
3. Set DefaultProjectileClass, StateTreeAsset, movement values, collision radius, impact policy, optional FX, and optional spawn profiles.
4. Create a StateTree using UEnhancedProjectileStateTreeSchema.
5. Add tasks such as SetVelocity, WaitImpactOrDistance, PlayFX, SpawnProjectileBurst, and DestroyProjectile.
6. Spawn from Blueprint with nodes under Enhanced Projectile|Spawn, for example Spawn Enhanced Projectile From Component.

Minimal C++ spawn example:

#include "EnhancedProjectileDefinition.h"
#include "EnhancedProjectileLibrary.h"

FGameplayTagContainer SourceTags;
FGameplayTagContainer PayloadTags;

FEnhancedProjectileSpawnContext Context =
	UEnhancedProjectileLibrary::MakeProjectileSpawnContextFromOwnerWeapon(
		OwnerCharacter,
		WeaponActor,
		TEXT("Muzzle"),
		TargetActor,
		SourceTags,
		PayloadTags);

UEnhancedProjectileLibrary::SetProjectileContextTargetLocation(Context, AimLocation);

FEnhancedProjectileSpawnOptions Options;
Options.bStartStateTree = true;
Options.bForceArmAfterSpawn = true;
Options.bUseProjectilePool = true;
Options.PoolName = TEXT("PrimaryProjectiles");

AEnhancedProjectileBase* Projectile =
	UEnhancedProjectileLibrary::SpawnEnhancedProjectileFromOwnerWeapon(
		this,
		ProjectileDefinition,
		OwnerCharacter,
		WeaponActor,
		TEXT("Muzzle"),
		TargetActor,
		Context,
		Options);

See Docs/QUICK_START.md for the full Blueprint and C++ walkthrough.

Sample Projectiles

The plugin ships with sample definitions, StateTrees, and projectile Blueprints for common patterns:

Straight, WeaponSocketStraight, FastTrace, GravityArc, HomingSeeker, LockOnSwarm, LockOnSwarmMissile, BouncyGrenade, StickyDelayedCharge, ImpactDetonator, AirburstCluster, AirburstBomblet, ScatterArrow, ScatterShard, RecallPulseEmitter, RecallPulseShard, ReturnToSource, ShieldPenetrator, OwnerStatScaled, and ChargedShot.

Detailed notes are in Docs/SAMPLES.md.

Documentation Map

• Installation: project setup, Git LFS, engine/plugin dependency notes, packaging.
• Quick Start: first projectile, Blueprint spawn flow, C++ spawn flow.
• API Reference: main classes, structs, Blueprint nodes, events, adapters.
• StateTree Tasks: task catalog and behavior authoring patterns.
• Samples: included sample assets and what each demonstrates.
• Simulator: editor simulator and commandlet workflow.
• Networking and Pooling: authority, context replication, prediction validation, and pool usage.
• Troubleshooting: common compile, asset, runtime, and networking issues.
• Release Checklist: checklist for future public releases.
• HTML guide deck: slide-style guide included from the source plugin.

Repository Layout

EnhancedProjectile.uplugin
Source/
  EnhancedProjectile/        Runtime module
  EnhancedProjectileEditor/  Editor simulator and commandlet module
Content/Samples/             Sample Blueprints, definitions, and StateTrees
Resources/                   Editor icon
Docs/                        Public usage guides

Versioning

The current public baseline is 1.0.0. Future releases should follow semantic versioning:

• Patch: documentation, small fixes, compatible task behavior fixes.
• Minor: new tasks, sample definitions, non-breaking API additions.
• Major: breaking API, asset, or StateTree schema changes.

Contributing

Issues, examples, fixes, documentation improvements, and new task ideas are welcome. Please read CONTRIBUTING.md before opening a pull request.

License

Enhanced Projectile is available under the MIT License.