A comprehensive, physically-accurate ballistics simulation system for Unity that provides realistic trajectories, ricochets, penetration mechanics, and advanced ballistic effects for games requiring authentic projectile behavior.

• Physically Accurate: Implements real-world ballistics physics including gravity, air resistance, drag models (G1, G2, G5, G6, G7, G8), and environmental effects.
• High Performance: Built on a custom lightweight Entity Component System (ECS) architecture with Unity Jobs and Burst compilation for optimal performance, capable of handling hundreds of simultaneous projectiles.
• Realistic Ricochets: Physically-based bullet deflection with angle-dependent probability and energy retention based on material properties.
• Advanced Penetration Mechanics: Energy-based projectile penetration through materials with realistic entry/exit behavior and stuck projectile handling.
• Comprehensive Material System: Extensive surface interaction properties with material-specific ballistic characteristics for different surfaces.
• Advanced Effects: Coriolis effect, spin drift, weather simulation, and atmospheric conditions.
• Visual Feedback: Built-in tracer system and comprehensive debug visualization tools.
• Extensive Weapons Database: 380+ real-world weapons with authentic ballistic data including pistols, rifles, shotguns, machine guns, and sniper rifles.
• Educational FPS Demo: Complete SimpleFPS demo system showcasing all features with clean, documented code.

What Can Be Used For  

✅ Realistic Ballistics Simulation: Accurate trajectories with proper physics for FPS, military, hunting, …
✅ Material Penetration: Realistic projectile behavior through different materials (wood, metal, concrete, etc).
✅ Ricochet Effects: Physically-based bullet deflection off surfaces .
✅ Long-Range Shooting: Precision ballistics for sniper games with environmental factors.
✅ Performance-Critical Games: Optimized for handling thousands of simultaneous projectiles.

What Is NOT  

❌ FPS Controller: While it includes a SimpleFPS system, it’s designed for ballistics simulation, not as a FPS character controller.
❌ Visual Effects System: Focuses on physics simulation rather than muzzle flashes, explosions, or other visual effects.
❌ Weapon Animation System: Doesn’t handle weapon animations, reloading animations, or complex weapon mechanics.
❌ Audio System: Doesn’t provide comprehensive audio management beyond basic demo sounds.
❌ Networking Solution: Designed for single-player simulations, not multiplayer networking.
❌ Energy Weapons or Propelled Projectiles: Designed for ballistic projectiles only, doesn’t support laser weapons, plasma guns, or self-propelled projectiles like rockets and missiles.

Installation  

Requirements:

• Unity 6000.0 LTS or newer.

Installation:

1. Download and import the True Ballistics asset from the Unity Asset Store into your Unity project.
2. No additional setup is required. The asset is ready to use out of the box!

How to Use  

The BallisticsManager component is the central hub of the ballistics system. It manages the lightweight ECS, handles projectile spawning, and coordinates all ballistic systems.

Create an empty GameObject and add the BallisticsManager component (Fronkon Games → True Ballistics → Ballistics Manager)

Add systems  

Systems are modules that take care of a task. You can add as many as you want in Systems, this way you will only use the ones you need.

They are ScriptableObjects and therefore files. You can create them from the Project window (Fronkon Games → True Ballistics → Systems)

All the systems included are discussed in more detail below. The minimum recommended systems are:

• Physics System: without this system the projectiles would not move.
• Lifecycle System: is in charge of recycling projectiles. Without this system the projectiles would never be destroyed and when reaching the maximum number (5000 by default), no new ones would be created.
• Collision System: the one in charge of reporting collisions with projectiles.

Once these three systems are added, you can fire a projectile in this way:

// Get the manager instance
BallisticsManager manager = FindFirstObjectByType<BallisticsManager>();

// Spawn a projectile
int projectileEntity = manager.SpawnProjectile(
    weaponData,          // WeaponData ScriptableObject
    transform.position,  // Spawn position
    transform.rotation,  // Spawn rotation
    1.0f,                // Dispersion multiplier
    true,                // Can jam
    1.0f                 // Velocity multiplier
);

// Spawn pellets (for shotguns)
List<int> pellets = manager.SpawnPellets(
    weaponData,          // WeaponData ScriptableObject
    shellData,           // ShellData ScriptableObject
    transform.position,  // Spawn position
    transform.rotation   // Spawn rotation
);

weaponData is another ScriptableObject (a file) with all the relevant data of a weapon model. You have more than 380 in the FronkonGames/TrueBallistics/Data/Weapons folder.

In the case of shotguns, in addition to the corresponding weaponData, you must add shellData, the type of cartridge you want to use. You can find several in FronkonGames/TrueBallistics/Data/Ammo.

You can create new weapons (and shells) from the Project window (Fronkon Games → True Ballistics → Weapon Data / Fronkon Games → True Ballistics → Shell Data).

Systems  

True Ballistics uses a custom lightweight ECS architecture optimized for ballistics simulation:

• Entities: Simple integer IDs representing projectiles (max 5000 concurrent).
• Components: Data structures (PhysicsComponent, DragComponent, etc).
• Systems: Logic processors that operate on entities with specific components.

Physics System  

Handles core ballistics physics including gravity, drag, and atmospheric effects. Without this system the projectiles would not move.

Features:

• Configurable gravity vector (supports other planets).
• Air density simulation with altitude effects.
• Multiple drag models (G1, G2, G5, G6, G7, G8).
• Wind effects and atmospheric conditions.
• Burst-compiled jobs for performance.

Configuration:

• Gravity: Gravity vector (default: Earth’s 9.81 m/s²).
  • Moon: 1.62 m/s².
  • Mars: 3.71 m/s².
  • Jupiter: 24.79 m/s².
  • Saturn: 10.44 m/s².
  • Uranus: 8.87 m/s².
  • Neptune: 11.15 m/s².
  • Pluto: 0.62 m/s².
  • Sun: 274.0 m/s².
  • Venus: 8.87 m/s².
  • Mercury: 3.70 m/s².
  • Io: 1.796 m/s².
  • Europa: 1.315 m/s².
  • Ganymede: 1.428 m/s².
  • Callisto: 1.235 m/s².
• Air Density: Air density in kg/m³ (default value is 1.225 kg/m³ at sea level).
  • 0.001225 kg/m³ at 10,000 meters.
  • 0.0001225 kg/m³ at 20,000 meters.
  • 0.00001225 kg/m³ at 30,000 meters.
  • 0.000001225 kg/m³ at 40,000 meters.
  • 0.0000001225 kg/m³ at 50,000 meters.
• Speed Of Sound: Speed of sound for Mach calculations (default value is 343 m/s at sea level).
  • 295 m/s at 10,000 meters.
  • 235 m/s at 20,000 meters.
  • 196 m/s at 30,000 meters.
  • 167 m/s at 40,000 meters.
  • 145 m/s at 50,000 meters.
• Max Speed: Maximum projectile velocity in m/s (default value is 299,792,458 m/s, the speed of light in vacuum).

If you add Debug System to the system list, you will be able to see the trajectories of the projectiles in the Scene window.

The trajectory of the projectile will have these colors:

In general, impacts in Green or Gray are not lethal.

Lifecycle System  

Manages projectile lifecycle with configurable termination rules. It is essential to add this system, since it is in charge of recycling projectiles. Without this system, when the maximum number of projectiles is reached (5000 by default), no more can be created.

If any of the following (active) rules are met, the projectile is deactivated.

Max Lifetime Rule  

Deactivates the projectile if its lifetime has exceeded a certain limit.

Min Speed Percentage Rule  

Deactivates the projectile if its speed is below a certain percentage.

Min Bounds Rule  

Deactivates the projectile if its coordinates are less than a certain limit.

Max Bounds Rule  

Deactivates the projectile if its coordinates are greater than a certain limit.

Stationary Rule  

Deactivates the projectile if it has been stationary for a certain amount of time.

Max Distance Rule  

Deactivates the projectile if it has traveled a certain linear distance from its point of origin.

One Collision Rule  

Deactivates the projectile after its first collision.

If you use the Ricochet System, a bouncing projectile does not count for this rule.

Ricochet Rule  

Deactivates the projectile if a ricochet occurred with an angle lower than a certain limit.

Ricochet Failed Rule  

If true, projectiles are deactivated upon any impact that does not result in a ricochet. This overrides One Collision Rule if both are true.

Collision System  

Efficient collision detection with adaptive algorithms. Remember that for a projectile to collide with an object on the stage, this object must have some kind of Collider.

Features:

• Raycast for high-speed projectiles.
• Batched SphereCasts for regular projectiles.
• Configurable layer masks.
• Automatic material detection.

Configuration:

• Layer Mask: Collision layers.
• High Speed Threshold: Percentage of the speed of light (default 10%) at which RayCast is used instead of SphereCast (the projectile is considered instantaneous).

Once added to the systems, you can subscribe to the OnProjectileHit events to receive information on each impact.

// Cache all colliders on this object and its children for efficient hit detection
colliders = this.GetComponentsInChildren<Collider>();

// Get the manager instance
BallisticsManager manager = FindFirstObjectByType<BallisticsManager>();

// Subscribe to projectile hit event (don't forget to unsubscribe)
ballisticsManager.OnProjectileHit += OnProjectileHitHandler;

...

private void OnProjectileHitHandler(CollisionInfo info)
{
  // Skip processing if collision info is invalid
  if (info.collider == null)
    return;

  // Check if the hit collider belongs to this object (or any of its children)
  foreach (Collider c in colliders)
  {
    if (c != null && info.collider == c)
    {
      // Doing something
      break;
    }
  }
}

Check these classes in FronkonGames/TrueBallistics/Demos/Scripts for more examples:

• Coin: A coin that oscillates and disappears upon impact.
• DestroyOnHit: The object is destroyed on impact.
• NonKinematicOnHit: Changes a Kinematic object to Non Kinematic on impact.

If you add Debug System to the system list, you will be able to see the impacts of the projectiles (a circle with a diagonal cross) in the Scene window.

Objects with Colliders and physics (RigidBody) do not receive any physical impulse when hitting a projectile (it is not the goal of this library). However you can consult the RigidBodyManager class to see an example of how to do it.

Neither create bullet marks or particles at the point of impact, although you can see how this is done in the demo in the HolesManager and SparksManager classes. Both solutions are quite rudimentary (enough for the purposes of the demo) so I do not recommend using them in production environments.

Ricochet System  

Realistic ricochet simulation based on impact angle and material properties.

Features:

• Probability-based ricochet calculation.
• Physically-based velocity changes.
• Material-specific restitution.
• Energy retention modeling.

Once added to the systems, you can subscribe to the OnProjectileRicochet events to receive information on each ricochet. If you use Collision System, an OnProjectileHit event will also be emitted.

If you add Debug System to the system list, you will be able to see the ricochets (a square with an arrow indicating rebound) in the Scene window.

Penetration System  

Advanced penetration mechanics with energy-based calculations and materials.

Features:

• Entry/exit point calculation.
• Energy consumption modeling.
• Path deflection on entry.
• Stuck projectile handling.

Configuration:

• Layer Mask: Layers considered for penetration raycasts.
• Energy Scale: Scaling factor applied to material strength when computing required energy. Lower than 1.0 will make the projectile more likely to penetrate.
• Max Entry Deflection Angle: Maximum angle in degrees by which a projectile’s path can be deflected upon entering a surface, based on incidence angle.

This system (and actually Collision and Ricochet) uses Ballistic Material for its calculations. If you do not assign any material to the objects, it will use Default Material from Ballistic Manager (see above). If you do not assign any, the ‘Concrete’ material will be used.

In the FronkonGames/TrueBallistics/Data/Materials folder you have a few materials already defined. You can also create your own (they are ScriptableObjects) from the Project window and using the menu Fronkon Games → True Ballistics → Material Data.

Configuration:

• Description: Description of the material.
• Min Angle For Ricochet Prob: Angle (degrees) from surface normal. Impacts at angles greater than this (grazing angles) have increasing ricochet probability.
• Guaranteed Ricochet Angle: Angle (degrees) from surface normal. Impacts at angles greater than this (very grazing angles) will always ricochet if probability is met.
• Ricochet Probability Curve: Curve defining ricochet probability (Y-axis, 0-1) based on impact angle with surface normal (X-axis, 0-90 degrees). Higher angles = more grazing.
• Restitution Normal: Coefficient of restitution for the velocity component normal to the surface (0 = no bounce, 1 = perfect bounce).
• Restitution Tangent: Coefficient of restitution for the velocity component tangential to the surface (0 = sticks, 1 = no friction).
• Energy Retention Factor: Overall percentage of kinetic energy retained after ricochet (0 = all lost, 1 = all retained). Applied AFTER restitution effects if both are used conceptually.
• Density: Density of the material in kg/m^3. Used for penetration calculations.
• Yield Strength: Yield strength of the material in MPa. Higher values resist penetration.

Add the Ballistic Material component to the objects you want to specify a material. Remember that they must be at the same level as the collider that detects the impact.

In Ballistic Material you can activate Use Material Cache to improve performance, but note that if you do so, you will not be able to change at runtime the material of the objects.

Three events related to projectile penetration are use:

• OnProjectilePenetrationEnter: When a projectile penetration starts (enters an object).
• OnProjectilePenetrationExit: When a projectile exits an object after penetration.
• OnProjectilePenetrationStuck: When a projectile gets stuck inside an object.

If you add Debug System to the system list, you will be able to see the the entry point (a circle with a vertical cross), the trajectory (in cyan color) and the exit point (a circle with a vertical cross).

If the projectile gets stuck inside the object, you will see its trajectory (in magenta) and the point where the projectile is (magenta circle with vertical cross).

Some considerations:

• Objects with a width of less than 1mm will be ignored.
• On objects 10 meters or more wide, penetration will always fail.

Tracer System  

GPU-accelerated visual tracer rendering.

Features:

• Compute shader-based geometry generation.
• Per-weapon-type configuration.
• Brightness based on velocity.
• Separate head/tail materials.

Weather System  

Environmental effects simulation using ICAO Standard Atmosphere.

Features:

• Altitude-based air density.
• Temperature effects.
• Wind simulation.
• Precipitation effects.

Configuration:

• altitude: Altitude in meters.
• temperature: Temperature in Celsius.
• wind: Wind vector in m/s.
• precipitation: Precipitation intensity (0-1).

Coriolis System  

Coriolis effect simulation for long-range ballistics.

Features:

• Configurable planetary parameters.
• Latitude-based calculations.
• Realistic deflection patterns.

Configuration:

• planetAngularVelocity: Planet rotation rate.
• latitude: Observer latitude.

Spin Drift System  

Spin-induced projectile drift for long-range simulation.

Features:

• Magnus effect calculation.
• Twist rate considerations.
• Barrel length effects.

Configuration:

• driftFactor: Overall drift scaling.

Debug System  

Comprehensive debug visualization (Editor only).

Features:

• Trajectory visualization with speed coloring
• Force vector display
• Impact point markers
• Ricochet and penetration visualization
• Configurable retention time

Customs Systems  

Creating a custom system involves inheriting from SystemBase and implementing the required methods:

[CreateAssetMenu(fileName = "CustomSystem", menuName = "My Game/Custom System")]
public class CustomSystem : SystemBase
{
  // Execution order (lower = earlier)
  public override int ExecutionOrder => 1500;
    
  // System initialization
  public override void Initialize(BallisticsManager manager)
  {
      base.Initialize(manager);
      // Setup system resources
  }
    
  // Called before physics update
  public override void PreTick(float deltaTime)
  {
      if (!active) return;
      // Pre-physics logic
  }
    
  // Main system update
  public override void Tick(float deltaTime)
  {
      if (!active) return;
      // Main system logic
  }
    
  // Called after physics update
  public override void PostTick(float deltaTime)
  {
      if (!active) return;
      // Post-physics logic
  }
    
  // System cleanup
  public override void DeInitialize()
  {
      // Cleanup resources
      base.DeInitialize();
  }
}

Example: Simple Gravity Well System

[CreateAssetMenu(fileName = "GravityWellSystem", menuName = "My Game/Gravity Well System")]
public class GravityWellSystem : SystemBase
{
  [Header("Gravity Well Settings")]
  public Transform gravityWellCenter;
  public float gravityWellStrength = 10f;
  public float gravityWellRadius = 50f;
  public override int ExecutionOrder => SystemExecution.Physics + 50; // After PhysicsSystem
  public override void PostTick(float deltaTime)
  {
    if (!active || gravityWellCenter == null) return;
    
    // Get component arrays
    var physicsComponents = manager.GetComponentArray<PhysicsComponent>();
    
    // Process all entities with physics components
    for (int i = 0; i < BallisticsManager.MaxEntities; i++)
    {
      if (!manager.entities[i]) continue;
      
      ref var physics = ref physicsComponents[i];
      
      // Calculate distance to gravity well
      Vector3 toWell = gravityWellCenter.position - physics.position;
      float distance = toWell.magnitude;
      
      // Apply gravity well force if within radius
      if (distance < gravityWellRadius && distance > 0.1f)
      {
        float force = gravityWellStrength / (distance * distance);
        Vector3 gravityForce = toWell.normalized * force * physics.mass;
          
        // Apply force
        physics.velocity += gravityForce * deltaTime / physics.mass;
      }
    }
  }
}

Simple FPS  

SimpleFPS is an educational first-person controller demo that showcases True Ballistics integration. It’s designed for learning and prototyping, not production use.

Purpose  

• Educational: Demonstrates best practices for ballistics integration
• Prototyping: Rapid testing of weapon configurations
• Reference: Clean, documented code for learning
• Decoupled: Event-driven architecture for easy modification

Architecture  

• Event-Driven: Uses SimpleFPSEvents for decoupled communication
• Auto-Wired: SimpleFPSDependencyContainer automatically subscribes methods
• Modular: Each component handles a specific responsibility

Key Components  

• SimpleFPSInput: Keyboard/mouse input handling
• SimpleFPSMovement: Character movement with physics
• SimpleFPSCamera: Mouse look with pitch/yaw
• SimpleFPSWeapon: Weapon handling and ballistics integration
• SimpleFPSInventory: Weapon switching and ammo management
• SimpleFPSAudio: Centralized audio management
• SimpleFPSPlayer: Physics and collision handling

Features  

• Movement: Walking, sprinting, jumping, crouching
• Camera: Smooth mouse look with configurable sensitivity
• Weapons: 7-slot weapon system with realistic ballistics
• Audio: Footsteps, weapon sounds, and environmental audio
• Effects: Head bob, weapon sway, and recoil
• Ballistics: Full integration with True Ballistics system

Usage Guidelines  

✅ Use for: Learning, prototyping, testing weapon configurations

❌ Don’t use for: Production games, complex gameplay systems

Support  

Do you have any problem or any suggestions? Send me an email to fronkongames@gmail.com and I’ll be happy to help you.

Remember that if you want to inform me of an error, it would help me if you sent to me the log file.