ThaneGuns

This is a spigot plugin (currently for 1.12.2) that adds guns to Minecraft. I was intrigued by a few different minigames a couple servers and communities have made adding them to the game (The most notably being Hypixel's CvC and Mineplex's Minestrike). This is my personal attempt to do the same.
Keep in mind, this plugin has a dependency. You can download Protocol Lib here.

Update Catalog
Functionality
Unlike the gamemodes I listed above, these guns use an accuracy circle. Through numbers input by the user, it is determined how far astray from the cursor bullets may be. This circle is then multiplied in size based on the players movement speed. This is based on their absolute speed in meters per second, regardless of direction, flight, vehicle, or potion effect. Because of this effect, the slower you are, the more accurate you become, with perfect stillness being near perfect accuracy.

Resource Pack
For a more immersive experience, the use of a resource pack is recommended. I have a bare minimum one available here. Sounds are straight from CS:GO.
DISCLAIMER: I am incredibly inexperienced when it comes to the creation of resource packs. As such, the gun sounds are uncomfortably loud at default sound settings. I highly recommend adjusting the "Voice" sound setting to 3% - 7% (This controls the sound values for gunshots and grenade explosions), and the "Noteblocks" sound setting to 20% - 30% (This controls the sounds values for reloading and other assistant sound effects). If anyone who has given enough time to read through this has an interest in aiding in the production of more textures, models, or sound effect, I fully welcome the help because I really dislike doing texture work. Feel free to send anything to my discord at Thane#2938, help is very much appreciated.

Set up
When using this plugin, the idea is not to use the defaults I provide, but instead to edit or create new ones. After one run, you will be able to find a few files in your plugins folder, under ThaneGuns.

guns.yml
Within this file, you'll find the names of each gun, case sensitive. When making your own gun, This is what controls the name of the item.
skin - required
This value can consist of two values, an item and a durability, or just an item. The item and durability value are seperated by a colon. This is the item the gun will use, but it will not override the item. Instead, it takes advantage of the "unbreakable" tag for items, so be wery when combinding with other plugins that may listen for unbreakable items.
close shot sound - required
The sound the gun makes when nearby the shooter. Input either a default sound, or one found in a resourcepack's "sound.json", formatted as "sound.specific.etc"
far shot sound - required
The sound the gun makes when at a distance from the shooter. Input a sound in the same format as the close sound effect.
reload start sound / reload stop sound OR reload sound
The sound the gun makes when you begin and end reloading. Alternatively, if you simply set "reload sound", it will make a sound effect divided equally across the reload time by the clip size.
reload time - required
The amount of time it takes for the gun to reload in ticks (one twentieths of a second); must be at least 1.
clip size - required
The amount of bullets the gun is filled with after a reload; Must be a value between 1 and 120.
ticks between shots - required
The amount of time it takes between each bullet is shot; Must be at least 1.
damage per bullet - required
Damage in half hearts each bullet does to an entity.
accuracy - required
Base accuracy of the player when standing still; 0 is perfect accuracy.
volatility
Multiplier of accuracy used times the player's speed; Must be above 0.
bullets per shot
This is the number of bullets spawned within the accuracy circle every time you shoot; Must be above 1.
range
The distance which bullets are able to go and do damage to enemies; This is measured in seven tenths of a block for hitbox detection reasons.
max zoom
The maximum amount the gun can zoom to; Can be set to 2, 4, or 8.
multi-target shooting
a true or false statement that designates if the bullets shot by this gun are able to penetrate through multiple targets. This does not include entities excluded from the list of targeted enemies.
particle
This sets which particle the gun uses when shooting. A complete list of usable particles can be found here.
particle range
This is the space within the bullet's path that the particle should spawn. The first value is where it starts, the second where it should end. Either value can be set to anything between 1 and the range, as long as the first is lower than the second.
particle frequency
This is how frequently the particle is spawned. The lower the number, the more often; Must be at least 1.

effects.yml
near miss
The sound effect played when a bullet comes close to hitting you as a target.
sniper zoom sound
The sound effect played when zooming in or out with a gun capable of zooming.
grenade throw
The sound effect played when you throw a grenade.
grenade bounce
The sound effect played when a grenade bounces.
grenade pinpull
The sound effect played when you pull the pin of a grenade out.
damageable entities
A list of entities that can be damaged by bullets. Alternatively, simply make the list one unit long and set the input to "all" to make it possible to damage every entity. Make sure its a mob, but you can use any of the following values.

Commands
A list of commands added to the game through this plugin.
/gun
This command lists all the currently available guns. This list updates automantically whenever you press "save" on guns.yml. Type out /gun <name of your gun, including spaces> to get the gun. It is not case sensitive. This is currently the only way to get the available guns.
/grenade
This command lists all available grenades. Use like /gun.
/pack
Provides a link to the current resource pack.
/reffect
Reloads the effects.yml options.
/rgun
Reloads the guns.yml.
/rgrenade
Reloads the grenades.yml.

Addons
Now, let's say you want even more customization for this plugin. Well, have no fear, because I have allowed for addon plugin support as of version 1.1. In this update and those following, you will be able to either install or create another plugin that lists ThaneGuns as a dependency line in the plugin.yml, like so:

Code (YAML):

depend : [ThaneGuns ]

In order to modify and use the methods required to get your guns and grenades intertwined with my own, make sure you have the required repositories and dependencies. I have the maven style below:

HTML:

<repository>
    <id>jitpack.io </id>
    <url>https://jitpack.io </url>
</repository>

HTML:

<dependency>
    <groupId>com.github.GreatThane </groupId>
    <artifactId>ThaneGuns </artifactId>
    <version>1.1 </version>
</dependency>

Now, there are a few main methods that will give you the most effect. First, is the static setGun method. This is used to either set or override the gun object correlated to a given name (which is used with the "/gun" command.):

Code (Java):

Gun. setGun ( String name, Gun gun )

Assuming you do not already have a specific Gun object you want to use as an override, you can create a new one with this method:

Code (Java):

Gun gun = new Gun ( String name, Material material, short durability, int bulletsPerShot, int reloadTime, int clipSize, int ticksBetweenShots, float damage, float accuracy, float volatility, int range, String closeSound, String farSound, String reloadStartSound, String reloadEndSound, boolean bulletLoading, int zoom, Particle particle, Map. Entry < Integer, Integer > particleRange, int frequency, boolean multishot, ShotRunnable shot )

Now, I'm aware that this is quite long, so I'll break down each parameter one by one.
Name
Simply the name that will be set to the gun's item while it is in an inventory. This does not necessarily have to be the same string as input with the setGun method.
Material
An enum for which item ID the gun will be using.
Durability
A short used to indicate which specific durability value the gun should use. This is primarily to take advantage of the 1.9 resource pack changes.
Bullets Per Shot
A number for how many bullets will be shot out when the gun fires. If you have a custom ShotRunnable, you can safely ignore this parameter and set it to 1. Everything after this point is identical to the yml instructions, so follow directions above. With an exception to:
shot
This is a custom interface with this plugin, which functionally works like a regular java runnable. However, you will have access to the Gun object and the Player shooting.

Code (Java):

(gun, player ) -> { // do some cool shooty stuff. }

Now, lets say you want to use / modify an already existing Gun object, simply call:

Code (Java):

Gun. types. get ( "string name for the gun of question, case sensitive" ) ;

Not enough customization? If you'd like, you can even make your own class extending the Gun object and @Override the methods in question, and put that into the setGun method.

A few other noteworthy static methods would be

Code (Java):

if (Gun. isGun (ItemStack stack ) )

Which returns a boolean of if the given ItemStack is a gun object. There is also

Code (Java):

Gun gun = Gun. getGun (ItemStack stack ) ;

Which converts an ItemStack to a Gun object, returning null if the given itemstack is not a Gun.

ow, with the 1.1 update there is now the ability for custom grenades. There are two objects to be concerned with when it comes to grenades, GrenadeItem and Grenade. GrenadeItem is how it is stored in the player's inventory, and Grenade is the object concerned with when the grenade has been thrown. This functionally works very similarly to the Gun object, with methods such as:

Code (Java):

Grenade. setGrenade ( String name, GrenadeItem grenade ) ;

Code (Java):

Grenade. setExplosion ( String name, GrenadeRunnable runnable ) ;

Code (Java):

if (GrenadeItem. isGrenade (ItemStack stack ) ) { }

Code (Java):

GrenadeItem grenade = GrenadeItem. getGrenade (ItemStack stack ) ;

Now, GrenadeRunnable works almost identically to ShotRunnable, with access to the Grenade.

Code (Java):

(grenade ) -> { // do cool explody stuff. }