Easy Weapons Documentation




About

Easy Weapons is a flexible, easy to use weapon system for Unity designed to allow for customization. It supports three main weapon types: Raycast, Projectile, and Beam. It comes with various other features including homing missiles, explosions, camera shake effects, and several sample weapons to get you started. Included also is a demo scene that can serve as an example usage. This pack also contains another pack, Easy Camera Shake, for camera shake effects used in explosions. Version 3 introduces a number of new features including a bullet hole pooling system and support for Shooter AI by Gateway Games.

It’s recommended that you first take a look at the provided demo scene. This includes a first person character setup with several pre-made weapons. Take a look at the weapons and play with the settings to see how things work. A complete first person character prefab is provided in the Prefabs/Controllers folder. Individual weapon prefabs can be found in Prefabs/Weapons.

In order for the weapon system and controller to work, you may need to make sure that the input settings are properly set up. Here is a screenshot of the minimum input controls that must be set up.

Some of these input controls are set up in a new Unity scene by default, and some are not. Fire2 and Fire3 are not used by the weapon system by default, and are therefore unnecessary. You may also need to add a “Cancel” input depending on which version of Unity you’re running and which version of Easy Weapons you have.

When using the weapon system demo, you can switch weapons by either scrolling the mouse wheel or by pressing buttons 1-9.


Documentation

Setting Up a Weapon

  1. Create a weapon GameObject. You might consider using one of the provided prefabs as a starting point. It’s recommended that you create an empty GameObject and then add your weapon model as a child object at the same position.
  2. Now add the Weapon component to your weapon GameObject. You can do this by simply dragging-and-dropping the Weapon.cs script from the scripts folder onto the inspector while your weapon GameObject is selected.
  3. The first and most important setting is the Weapon Type. Easy Weapons currently allows for 3 basic weapon types: Raycast – Weapons fire shots without physical bullets, causing instant damage and effects. This type allows for full control over weapon accuracy and power. Projectile – Weapons instantiate a specified projectile (for example a missile or rocket.) The projectile then handles speed, damage, and more. This is controlled through the projectile script, which you can use to make your own projectiles. Also included in the projectile script is a seeker missile setting, which causes projectiles to automatically seek GameObjects with a specified tag. This is useful for creating projectiles like homing missiles. Beam – Weapons create a continuous beam that calculates damage, force, etc. on every frame, instead of only once instantly. This weapon type uses line renderers for the visual beam.
  4. All weapons (GameObjects with the Weapon script attached) should be children of a parent GameObject with the WeaponSystem script attached. The WeaponSystem component handles weapon switching through number keys as well as mouse scrolling. All of the weapons that they player is able to switch to and from should be held in the Weapons array on the WeaponSystem component. Starting Weapon Index specifies the index of the weapon you want the player to start out with (starting with 0.) The WeaponSystem requires the input manager to be setup for buttons “Weapon 1” through “Weapon 9” for number keys 1-9. It also uses “Mouse ScrollWheel” input to switch weapons by scrolling up or down.

3rd Party Plugin Support

Shooter AI – Enable Support for Shooter AI by Gateway Games

Bloody Mess Support

In addition to enabling the Bloody Mess Support checkbox, you’ll need to un-comment various sections of code to fully activate Bloody Mess compatibility. The code blocks to be un-commented can be found at the following places:
- Weapon.cs, lines 633 and 971
- Projectile.cs, line 138
- Explosion.cs, line 58

General

Player’s Weapon – Whether or not this weapon is controlled by the player
Auto Type – Full makes a continuous spray of fire, Semi fires once per button press on the fire button
Weapon Model – This is the GameObject that has the actual weapon mesh. It will be the GameObject that kicks back if recoil is enabled.
Raycasting Point – This is a Transform that is used to determine the position from which the rays should be cast. If you want the weapon to fire from the center of the screen, make sure this Transform is centered with the camera.

Power

Power – This is used to determine the damage that will be applied to GameObects with a Health component.
Force Multiplier – This value is used to change how much force is applied to rigidbodies that are shot by this weapon
Range – The furthest distance this weapon can fire
Rate Of Fire – The number of rounds per second this weapon can fire.
Delay Before Fire – The time (seconds) before the weapon is fired. This acts as a delay between trigger (input button if controlled by player) and fire.
Burst Rate – The number of shots fired in each burst (if desired)
Burst Pause – The amount of time between bursts of fire. Set to 0 for no burst.

Ammunition

Infinite Ammo – If set to true, this weapon will not run out of ammo.
Ammo Capacity – The maximum number of rounds that can be loaded in this weapon at a time
Reload Time – The amount of time (in seconds) that it takes to reload this weapon
Reload Automatically – Whether or not the weapon should reload automatically when it runs out of ammo. If disabled, the user can reload with the “Reload” input button.
Show Current Ammo – If enabled, the current number of rounds will be displayed in the GUI. (Uses Unity’s legacy OnGUI)
Shots Per Round – The number of “bullets” (rays) that are fired on each round. This is useful for shotgun-like weapons. Power is applied individually for each shot on each round.

Accuracy

Accuracy – How accurate this weapon is, on a scale of 0-100
Accuracy Drop Per Shot – The amount by which the accuracy drops after each shot. This also affects the dynamic GUI crosshairs.
Accuracy Recover Rate – The rate at which the accuracy of the weapon goes back from the current accuracy (after a shot) to the original accuracy

Recoil

Recoil – If enabled, this weapon will have recoil. This means it will “kick” back based on specified values.
Recoil Move Min – The minimum amount for this weapon to move backwards for recoil.
Recoil Move Max – The maximum amount for this weapon to move backwards for recoil.
Recoil Rotation Min – The minimum amount for this weapon to rotate on the X axis for recoil.
Recoil Rotation Max – The maximum amount for this weapon to rotate on the X axis for recoil.
Recoil Recovery Rate – The rate at which the gun model moves from its position after recoil to its original position.

Effects

Spit Shells – If true, this weapon will instantiate shell props and apply force to them.
Shell – The Shell prop prefab to be instantiated
Shell Spit Force – The force to be applied to the shell prop
Force Variant – The amount by which the shell spit force may randomly vary
X Torque – The amount by which the shell should spin on the X axis
Y Torque – The amount by which the shell should spin on the Y axis
Torque Variant – The amount by which the shell torque may randomly vary
Shell Spit Point – The shell will be instantiated at the position of this Transform.
Muzzle Effects – If enabled, muzzle flash prefab(s) will be instantiated.
Muzzle FX Spawn Point – Muzzle flash effect prefabs will be instantiated at the position of this Transform. This should typically be at the end of the muzzle of the weapon model.
Muzzle FX Prefabs – Click “Add” to add a new prefab slot. Click “Remove” to remove one. Drag-and-drop prefabs into the prefab slot to assign a muzzle flash effect.
Hit Effects – If true, hit effects prefabs will be instantiated at the point that was hit by this weapon when it is fired.
Hit FX Prefabs – Click “Add” to add a new prefab slot. Click “Remove” to remove one. Drag-and-drop prefabs into the prefab slot to assign a hit effect prefab.

Bullet Holes

The new bullet hole system introduced in Version 3 uses pooling instead of instantiating individual bullet holes for each shot. You’ll need a GameObject in your scene with a bullet hole component that has the individual bullet holes as child GameObjects. You will eventually make several of these if you want different bullet holes to appear on different surfaces. Name this GameObject something unique, as you’ll be referencing the name later.

The Best way to understand the way the bullet hole system works is to take a look at the included demo scene.

Bullet Holes – If true, bullet hole prefabs will be instantiated where the weapon has hit.
Determined By – This is how the weapon system determines which bullet holes should be instantiated on which GameObjects. You can make bullet holes determined by tags, materials, or physic materials. Click “Add” to create a new bullet hole group. Click “Remove” to remove one. Each tag, material, or physic material can correspond to one or more bullet hole pool(s). To assign a bullet hole pool, type the pool GameObject’s name in the scene. The system uses names to identify bullet hole pool groups instead of object references so that you can retain bullet hole references in prefabs from scene to scene. If you assign multiple bullet hole pool GameObjects to the same tag, material, or physic material, then one of them will be chosen at random for each shot. When a weapon is fired, the system goes through the references assigned in the inspector to determine an appropriate bullet hole pool. When the bullet hole pool is selected, one of the bullet holes is chosen from a cycle determined in the BulletHolePool script.

The “Default” bullet hole pools define the bullet holes that will be used when you shoot something that doesn’t match any of the other criteria. For example, if you assign bullet holes only for the “Concrete” and “Wood” tags, and the player shoots something with the “Metal” tag, one of the default bullet holes will be used. Version 3 also introduces “Exception” surfaces, which allow you to define certain kinds of objects which will never receive bullet holes. So if you want all GameObjects in your scene to use a certain bullet hole pool when the are shot except for ones with a “Wood” tag, you could assign the bullet hole pool in the “Default” section, while adding the “Wood” tag to the “Exceptions” section.

In the screenshot above, anything that doesn’t match the 6 tags in the first section will receive bullet holes from either “default_pool_1″ or “default_pool_2″. The exception is any GameObject with the tag “Enemy”, which will receive no bullet holes.

Note that when you create your bullet hole pool GameObjects, you must remember to add a BulletHolePool component and assign the corresponding bullet holes to the list in the inspector.

Crosshairs

Show Crosshairs – If enabled, GUI crosshairs will be shown in the middle of the screen.
Crosshair Texture – The texture used to draw the GUI crosshairs. This can be a solid color image.
Crosshair Length – The length of each crosshair bar
Crosshair Width – The width of each crosshair bar
Start Crosshair Size – The starting space between each crosshair bar. This space is changed dynamically as a weapon is being fired and the accuracy changes.

Audio

Fire Sound – The sound that is played when the weapon is fired
Reload Sound – The sound that is played when the weapon is reloading
Out of Ammo Sound – The sound that is played when a weapon tries to fire but is out of ammo

Note – Your weapons should have an Audio Source component attached to play sounds. However, if you don’t already have one, the weapon script will automatically add one at runtime.

Additional Projectile Settings

Projectile – This is the actual prefab that will be instantiated (like a rocket, missile, mortar, or grenade.)
Projectile Spawn Point – The projectile prefab will be instantiated at the position of this Transform.

Additional Beam Settings

Reflect – Whether or not the beam should reflect off of surfaces. If enabled, the beam will “bounce” off of other GameObjects in the scene.
Reflection Material – The material that the beam should reflect off of. If you don’t select a material, the beam will reflect off all surfaces.
Max Reflections – The maximum number of reflections, or “bounces” that can occur for this beam. If this is set to 10 for example, the beam will reflecting off of surfaces after the 10th “bounce.” It should be noted that a larger maximum number of reflections can negatively impact performance since this directly affects the number of raycasts being made.
Beam Effect Name – This is the name of the GameObjects that will be instantiated for the visual beam effect. It is not necessary to change this, its purpose is just to offer an extra level of customizability. This will not change the way anything works in the Beam System.
Max Heat – The amount of time this weapon can “beam” before it overheats. This is similar to ammo in Raycast and Projectile systems.
Infinite – If true, the beam will never overheat. This is similar to Infinite Ammo. This causes Max Heat to be ignored.
Material – The material that will be used for the visual beam effect. When you create your own beam material, you should use a particle shader.
Color – The color tint of the visual beam effect
Start Width – The width of the beam at the starting point (the tip of the weapon)
End Width – The width of the beam at the end point (where the beam hits something)
Power – The amount of damage applied by this beam. Remember that unlike Projectile and Raycast systems, this is applied on every frame, so this value will be very small.
Force Multiplier – This value alters the amount of force applied to rigidbodies that are hit by this weapon.
Range – The maximum range of the beam Show Current Heat – If enabled, the current heat of the beam will be displayed in the GUI. Similar to Show Current Ammo for Raycast and Projectile systems.

Explosions

Shooter AI Support – Enables support for Shooter AI by Gateway Games
Explosion Force – The force to be applied to nearby rigidbodies
Explosion Radius – The radius (distance) of the explosion
Shake Camera – If enabled, the explosion will shake nearby cameras
Camera Shake Violence – The amount by which to shake nearby cameras
Cause Damage – If enabled, the explosion will apply damage to nearby GameObjects with Health components
Damage – The amount of damage to apply to nearby GameObjects with the Heatlh component

Note: It’s recommended that you add a TimedObjectDestroyer or similar component to your explosion. This is so that after the explosion effects are done, unused explosion GameObjects are removed from the scene.

Bullet Holes

Bullet Hole Mesh – The actual mesh (child GameObject) of the bullet hole prefab
Use Pooling – Use the bullet hole pooling system
Lifetime – The total time before this bullet hole is completely removed from the scene
Start Fade Time – The amount of time before this bullet hole starts to fade out
Fade Rate – The rate at which the bullet hole fades out each frame.

Creating Bullet Hole Prefabs:

  1. Add a new empty GameObject in the scene.
  2. At the same position, add a plane mesh.
  3. Make the plane mesh a child GameObject of the empty GameObject.
  4. Give the plane mesh a material with your bullet hole texture. A particle shader is recommended.
  5. Move the plane mesh (child) just barely above the parent empty GameObject. This is so the mesh is visible when it’s instantiated at the position where a weapon hits something.
  6. Drag-and-drop the empty (parent) GameObject into the project panel and name it, to create a prefab. This prefab can be instantiated by the Weapon script.

Health

Version 3 allows you to use your own Health scripts with Easy Weapons. Just add a method called ChangeHealth that receives a float as a parameter – the amount by which the health should be changed. In most cases, this will be negative since the health gets damaged by the weapons. ChangeHealth() is called in the default Health script through a message from the Weapon and Explosion scripts.

Can Die – Whether or not this character can die when it runs out of health
Starting Health – The amount of health with which this GameObject starts
Max Health – The maximum health this GameObject can have
Replace When Dead – If enabled, this GameObject will be replaced with another GameObject when it dies. This is useful for things like shattering or breaking effects.
Dead Replacement – This is the GameObject that will be instantiated as a replacement when the health GameObject dies.
Make Explosion – If enabled, an explosion prefab will be instantiated on death
Explosion – The explosion prefab to be instantiated on death
Is Player – Whether or not this health is the player character
Death Cam – The camera to be activated when the character dies