Ballistic System | Technical Documentation

Thank you for taking the time to check out my Ballistic System plugin. On this page you’ll find a breakdown of each of the Blueprints contained within the project, how they’re intended to be used, and how you can integrate them into your own game.

For a practical example of the Ballistic System in action, check out its implementation into my Shooter Sandbox project. It includes a full shooting range with a number of weapons and surfaces of varying thicknesses to shoot at/through.

Adding the Ballistic System Plugin to your project

To add the Ballistic System to your project you will need to copy it into your project’s plugins folder, which is located in the root project directory. If this is your project’s first plugin you may need to create this folder yourself.

[YourProject]\Plugins\BallisticSystem

When you open your project for the first time after adding the plugin it will prompt you to rebuild the module. This is expected behavior and shouldn’t take long as the Ballistic System uses minimal C++.

What’s inside the plugin

You’ll know the Ballistic System has been added to your project correctly when you can see the following assets in your Content Browser. You will need to have ‘Show Plugin Content’ enabled in the Browser’s settings to see them.

Core

BP_BallisticSystem_AC	The main component of the Ballistic System plugin, intended to be added to any Actor that fires projectiles (either hitscan or simulated).
BP_Projectile	An Actor that simulates its own movement through space over time.
BPFL_BallisticSystem	A common library of functions used by both the Ballistic System and Projectile Blueprints.
BPI_BallisticSystem	A Blueprint Interface that facilitates communication between the Ballistic System and the Actor instigating the shot.

Data

PDA_Cartridge	Mesh, spread, and projectile data for a fired cartridge.
PDA_Projectile	All data that pertains to a projectile, including hit scan/projectile selection and external/terminal ballistics values.
PDA_Surface	Ricochet and penetration constants for a specific surface.
SSurface	A struct that contains a relationship between a Physical Material and Surface Data Asset.
PDA_ImpactEffect	Contains decal, sound, and vfx data for when a Projectile impacts a Surface.
SImpact	All the data the system needs to process an impact, both visually and mechanically.
SImpactMessage	All data that needs to be sent over the network on impact.
SImpactEffects	A collection of ImpactEffect references, one for each possible outcome of an impact (fragment, ricochet etc.)

Demo Content

Ballistic Drag Curves	A series of curves (G1, G5, G6, and G7) based on real-world ballistic models used to calculate drag.
Ricochet Curves	Example curves used to calculate ricochet probability/outcome based on the angle of impact.
Penetration Curves	Example curves used to calculate penetration probability/outcome based on the angle of impact.
Demo Data	Examples of the Cartridge, Projectile, Surface, and Impact Effect data assets to get you started.
Demo Art Content	A collection of Materials, Sounds, and Static Meshes that make the Ballistic System easier to demo right out of the box.

Adding Gameplay Tags via C++

It’s always been my goal for all components of the Shooter Sandbox to be fully exposed to Blueprint and to have minimal C++ code. Unfortunately, adding Gameplay Tags from a plugin is something that can only be done in a C++ class. This is what you’re compiling when you first add the plugin to your project.

The class, BallisticSystemTags, adds a selection of gameplay tags that are used by the system to return the result of various actions in a human-readable way.

Using the Ballistic System

To add the Ballistic System to your character or weapon you’ll need to first add the Ballistic System Actor Component.

You’ll also need to add the BPI_BallisticSystem Blueprint Interface to the same Actor, and ensure that the function GetProjectileOrigin is correctly pointing to the location and direction from which you’d like projectiles to be fired.

There are a few other functions contained within BPI_BallisticSystem that are not strictly necessary but do open up the plugin for easier extension:

• GetBallisticSystemComponent: Allows other Actors to reference the system and fire projectiles without a casting chain.
• GetPatternDeviation: An additional layer of trajectory deviation in case you have a separate recoil system (like the Shooter Sandbox does).
• DealDamageToActor: This allows the owner of the Ballistic System to directly instigate damage dealing (and other effects) to another Actor.

Once this is done, all you need to do to start firing projectiles is to get a reference to the Ballistic System and trigger the Shoot function.

Configuration

Although the Ballistic System is heavily data-driven, and there are a lot of settings, the plugin includes examples of each of the expected data assets. I hope this allows you to hit the ground running and get into playing with different types of weapon as soon as possible.

Cartridge Settings

Mesh	A static mesh that represents the cartridge in the world.
Spread	A amount of random deviation applied to each projectile in the cartridge (perfect for shotguns!)
Projectiles	An array of projectiles contained within the cartridge. Many weapons will only have one but you can add as many as you like.

Projectile Settings

Core

Projectile Class	The projectile’s Blueprint class. Consider extending BP_Projectile to add your own logic!
Mesh	A static mesh that represents the projectile in the world.
Hitscan Distance	The distance at which the system does a hitscan check before spawning a BP_Projectile Actor. If nothing is hit the projectile will spawn at the far end of the hit test. If the bullet impacts within this distance a BP_Projectile may never be spawned.
Projectile Lifespan	The lifespan of any spawned projectile. Keep this as low as possible to increase performance.
Projectile Tick Interval	How often the BP_Projectile Actor updates its position. Smaller values will create a more accurate simulation at the expense of performance.
Minimum Velocity Before Kill	The velocity below which the BP_Projectile Actor will destroy itself.

External Ballistics

Mass	The projectile’s mass. Used for physics simulation and to calculate damage.
Gravity Scale	Multiplies the effect of gravity on the projectile during external ballistics calculation.
Muzzle Velocity	The projectile’s starting speed.
Ballistic Coefficient	Used by the Drag Function during external ballistics calculation. You can read more about it here.
Drag Function	A float curve that determines the drag model used to calculate air resistance.

Terminal Ballistics

Damage Curve	Defines how much damage this projectile does based on its velocity.
Ricochet Sound	The sound that plays when a ricochet occurs.
Maximum Ricochets	How many times the projectile can deflect off a surface before it fragments.
Penetration Modifier	A multiplier on the projectile’s ability to punch through a surface.
Maximum Perforations	How many times the projectile can penetrate a surface before it fragments.
Impact Effects	Declares the projectile’s response to different surface types.

Surface Data

Core

Ricochet Probability	A float curve that determines the probability of a ricochet based on impact angle.
Ricochet Deviation	A float curve that determines random trajectory deviation during a ricochet based on impact angle.
Ricochet Velocity	A float curve that determines the change in velocity during a ricochet based on impact angle.
Penetration Probability	A float curve that determines the probability of a penetration based on impact angle.
Penetration Deviation	A float curve that determines random trajectory deviation when a projectile penetrates the surface based on impact angle.
Penetration Surface Velocity	The loss in velocity when a projectile initially penetrates the surface.
Penetration Internal Velocity	The loss in velocity per centimeter as a projectile passes through the object.
Penetration Energy Threshold	The amount of kinetic energy a projectile needs to penetrate the surface.
Authoritative Effects	If true any impact effects generated by this surface will be spawned on the server and then replicated, rather than playing on the owning client first.

Impact Effect

Decal	The decal Material applied to the hit location
Decal Size	The size of the hit decal
Particle System	The Niagara one-shot that is spawned on impact
Sound	The sound that plays on impact

Frequently Asked Questions

How does this work in multiplayer?

The Ballistic System has been designed with multiplayer in mind and is fully replicated. When the system fires a shot it will happen both locally for client-side cosmetic purposes and on the server to calculate damage. The server then replicates the result of the impact to all clients.

The bAuthoritativeEffects flag inside PDA_SurfaceData can be checked to ensure all impact effects come from the server first. This is particularly useful if you want specific impacts to be authoritative, like blood spray to indicate damage.

Can the Ballistic System be applied to non-character Actors?

Absolutely! Any Actor can have a Ballistic System Actor Component attached, and as long as the accompanying BPI_BallisticSystem functions are filled in to define the initial trajectory it’ll be able to fire projectiles.

Why doesn’t your Ballistic System have X feature?

I am really proud of this first iteration of the Ballistic System, but I also acknowledge that it could also be taken a lot further. If you’re looking for something that the Ballistic System doesn’t currently achieve, please reach out. I’m keen to make the plugin as useful as possible!

Some ideas that have been thrown around for version 2.0 include:

• Wind dynamically having an effect on bullet trajectory
• Coriolis force, and other factors relevant to shooting at (very) long distances.
• Support for clips and magazines