Gun Core is the custom gun functionality from Gamingbarn's Guns put into a standalone library.
This library allows for players to create their own full-fledged gun system without needing to program everything from scratch. While perfect for playing around, you are also more than welcome to publish datapacks or mods that use Gun Core as a library. In both cases, you are also free to include any Gun Core assets within your own project, so long as you provide credit. More information on what you can and cannot do can all be found in the license beneath.
Below are the most basic, fundamental stats for the custom guns. Each of the below stats are fairly self-explanatory and intuitive.
The Damage stat is how much damage the gun deals to the target upon impact. The damage is dealt in half-hearts. The damage value is not exactly how much damage the target will receive, however. If a target is wearing armor, the amount of damage dealt will change.
The only exception to this functionality is when the Damage Type of the gun is set to Explosion or Safe Explosion. In this case, the Damage stat is instead used as the explosion radius for the explosion that is spawned upon impact.
For example: a damage value of 3 will produce an explosion similar to that of a regular creeper.
The Range stat is how far, in blocks, the projectile can travel before despawning. It is important to avoid overly-high values for this stat. Problems may occur when the projectile enters unloaded chunks, which can occur when the range is above 300 (the maximum blocks visible on max render distance) or when a player with low render distance shoots any gun. This isn't an inherent issue, but is something important to keep in mind.
The Rate of Fire stat is how long (in ticks) the player must wait after shooting the gun before they can fire it again.
This stat functions exactly as expected, up to fire rates of 4-ticks or less. At this level, the gun may behave differently depending on the base item selected. Generally-speaking, this can be ignored, but it is worth knowing about.
The Recoil stat is how much the camera is moved upwards when the gun is shot. There are 15 different possible recoil values on a scale of 0-14, with 0 being the lowest and 14 being the highest.
The below table shows the recoil value and its corresponding tp command in Gun Core:
| Value | Tp Command |
|---|---|
| 1 | tp @@s ~ ~ ~ ~ ~-0.4 |
| 2 | tp @@s ~ ~ ~ ~ ~-0.7 |
| 3 | tp @@s ~ ~ ~ ~ ~-1 |
| 4 | tp @@s ~ ~ ~ ~ ~-2 |
| 5 | tp @@s ~ ~ ~ ~ ~-3 |
| 6 | tp @@s ~ ~ ~ ~ ~-4 |
| 7 | tp @@s ~ ~ ~ ~ ~-5 |
| 8 | tp @@s ~ ~ ~ ~ ~-6 |
| 9 | tp @@s ~ ~ ~ ~ ~-7 |
| 10 | tp @@s ~ ~ ~ ~ ~-8 |
| 11 | tp @@s ~ ~ ~ ~ ~-9 |
| 12 | tp @@s ~ ~ ~ ~ ~-10 |
| 13 | tp @@s ~ ~ ~ ~ ~-11 |
| 14 | tp @@s ~ ~ ~ ~ ~-12 |
Zoom Recoil is functionally identical to the normal Recoil stat. The only difference between the two is that Zoom Recoil is used when the player shoots the gun while zooming.
Zoom Strength is how much the camera is zoomed in when the player aims with their gun. The Zoom Strength stat is on a scale of 0-10, with 0 being the lowest and 10 being the highest.
Due to Minecraft limitations, there isn't a simple, easy way to change the FOV of the player. Due to this, the Gun Core zoom system functions by reducing the movement speed of the player. This method decreases the player's FOV, but also slows them down. Also, this stat has no affect users with the "FOV Effects" accessibility setting turned off.
Below is a table with each zoom value and how much it decreases movement speed by.
| Value | Movement Speed Modifier |
|---|---|
| 1 | -0.01 |
| 2 | -0.02 |
| 3 | -0.03 |
| 4 | -0.04 |
| 5 | -0.05 |
| 6 | -0.06 |
| 7 | -0.07 |
| 8 | -0.08 |
| 9 | -0.09 |
| 10 | -0.1 |
In Gun Core, there are two kinds of projectiles: Raycasts and Slowcasts. Slowcasts are hitscans; they immediately travel from the face of the player and hit their target. Slowcasts are physical projectiles that will take time to hit their target. Both Raycasts and Slowcasts use particles to display themselves. Particles must be turned on for the player to be able to see it.
| Value | Name | Particle Command | Effects |
|---|---|---|---|
| 1 | Bullet | particle minecraft:ash ^ ^ ^ 0 0 0 0 1 | Shoots through glass and breaks it |
| 2 | Light Bullet | particle minecraft:ash ^ ^ ^ 0 0 0 0 1 | Shoots through glass and breaks it |
| 3 | Pellets | minecraft:ash ^ ^ ^ 0.15 0.1 0.15 0 2 | Shoots through glass and breaks it |
| 4 | Laser | particle dust{color:[1.000,0.000,0.000],scale:1} ~ ~ ~ 0 0 0 0 1 | Shoots through glass without breaking; cannot pass through tinted glass |
| 5 | Large Laser | particle dust{color:[1.000,0.000,0.000],scale:3} ~ ~ ~ 0 0 0 0 1 | Shoots through glass without breaking; cannot pass through tinted glass |
| 6 | Fire | particle minecraft:small_flame ^ ^ ^ 0 0 0 0 1 | Unable to shoot through water |
| 7 | Blaze Fire | particle minecraft:small_flame ^ ^ ^ 0 0 0 0 1 | Spawns fire along path; unable to shoot through water |
| 10 | Green Ray | particle minecraft:totem_of_undying ^ ^ ^ 0 0 0 0 1 | No special effects |
| 11 | Blue Ray | particle minecraft:dolphin ^ ^ ^ 0 0 0 0 10 | No special effects |
| 12 | Pink Ray | particle minecraft:cherry_leaves ^ ^ ^ 0 0 0 0 1 | Travels in strong downward curve |
| 13 | Red Ray | particle falling_lava ~ ~ ~ 0 0 0 1 0 | No special effects |
| 14 | White Ray | particle minecraft:end_rod ^ ^ ^ 0 0 0 0 1 | No special effects |
| 15 | Green Laser | particle dust{color:[0.302,0.922,0.302],scale:1} ^ ^ ^ 0 0 0 0 1 | Shoots through glass without breaking; cannot pass through tinted glass |
| 16 | Blue Laser | particle dust{color:[0.294,0.420,0.922],scale:1} ~ ~ ~ 0 0 0 0 1 | Shoots through glass without breaking; cannot pass through tinted glass |
| 17 | Yellow Laser | particle dust{color:[0.918,0.941,0.263],scale:1} ~ ~ ~ 0 0 0 0 1 | Shoots through glass without breaking; cannot pass through tinted glass |
| 18 | Orange Laser | particle dust{color:[0.941,0.557,0.263],scale:1} ~ ~ ~ 0 0 0 0 1 | Shoots through glass without breaking; cannot pass through tinted glass |
| 19 | Cyan Laser | particle dust{color:[0.612,1.000,0.961],scale:1} ~ ~ ~ 0 0 0 0 1 | Shoots through glass without breaking; cannot pass through tinted glass |
| Value | Name | Particle Command | Effects |
|---|---|---|---|
| 101 | Rocket | particle minecraft:cloud ^ ^ ^ 0.02 0.02 0.02 0.01 1 | No special effects |
| 102 | Grenade | particle minecraft:crit ^ ^ ^ 0.02 0.02 0.02 0.04 1 force | Travels in moderate downward curve |
| 103 | Fireball | particle minecraft:lava ^ ^ ^ 0.02 0.02 0.02 0 1 | Travels in moderate downward curve |
| 104 | Physical Bullet | particle minecraft:ash ^ ^ ^ 0 0 0 0 2 | Shoots through glass and breaks it |
| Pink Ray | Large Laser | particle minecraft:cherry_leaves ^ ^ ^ 0.04 0.04 0.04 0.04 1 | Travels in strong downward curve |
The Projectile Speed stat is only used for the slowcast-based projectiles. The stat changes how many steps per-tick the projectile takes. For reference, each step is worth 0.2 blocks. This means a value of 5 would make the projectile travel 1 block per tick, which means the projectile would travel 20 blocks a second. It is recommended to experiment with this value until it feels appropriate.
There are two categories of Damage Types: regular and explosive. Regular damage types differ from each other in two main ways: the death message sent in chat and their armor penetration ability.
The death message difference is self-explanatory, but the armor penetration factor is more complex.
Armor penetration is calculated using the below equation:
$$ f(x) = d \left( 1 - \frac{x}{x+v} \right) $$
... where \( d \) is the original damage of the gun, \( x \) is the armor of the target, \( v \) is the reduction factor, and \( f(x) \) is the resulting damage (before applying Minecraft's armor damage reduction). Minecraft Wiki - Armor Damage Reduction
The higher the \( d \) value, the higher the armor penetration power of the gun.
| Value | Name | Death Message | Armor Penetration |
|---|---|---|---|
| 1 | Bullet Standard | "%1$s ate lead from %2$s's %3$s" | \( d \) = 50 |
| 2 | Bullet Light | "%1$s was riddled with holes by %2$s using %3$s" | \( d \) = 15 |
| 3 | Bullet Heavy | "%1$s was blown away by %2$s's %3$s" | \( d \) = 80 |
| 4 | Standard Laser | "%1$s was incinerated by %2$s using %3$s" | \( d \) = 45 |
| 5 | Strong Laser | "%1$s was completely disintegrated by %2$s's %3$s" | \( d \) = 75 |
| 6 | Fire | "%1$s was torched by %2$s using %3$s" | Completely ignores armor |
| 7 | Ray | "%1$s was deleted from %2$s using the %3$s" | Only subject to vanilla armor protection |
Explosive damage types produce an explosion upon impact, where the explosion radius of the impact explosion is determined by the Damage stat. As mentioned on the Basic Stats tab, a Damage value of 3 would produce an explosion similar to a creeper's.
| Value | Name | Effects |
|---|---|---|
| 8 | Explosion | Spawns explosion |
| 9 | Safe Explosion | Spawns explosion that doesn't break blocks |
Ammunition is defined with two gun stats: ammo_base and ammo_item_tag. The Ammo Base stat is the base Minecraft item of the ammo item. It is recommended to use an unobtainable block or item, such as a command block or jigsaw, as to not interfere with vanilla gameplay. The Ammo Item Tag is the name of an byte element present in the minecraft:custom_data component: "minecraft:custom_data": {"gbg_assault_rifle_magazine": 1}
The Ammo Item Tag is also appears in the description of the gun in order to tell the user what ammunition they need to use with that gun. Because of this, it is recommended to make your Ammo Item Tag share a similar name with the Ammo Item.
The Reload Type stat affects how ammo items are consumed when the player reloads their gun.
There are five reload types currently implemented in Gun Core.
| Value | Name | Functionality |
|---|---|---|
| 1 | Magazine | Consumes one ammo item; fills up gun completely |
| 2 | Shell | Consumes one ammo item; restores one shot |
| 3 | Partial 25 | Consumes one ammo item; restores 25% of gun's total capacity |
| 4 | Partial 50 | Consumes one ammo item; restores 50% of gun's total capacity |
| 5 | Partial 75 | Consumes one ammo item; restores 75% of gun's total capacity |
| 6 | Bullets | Consumes one ammo item for each shot missing from the gun; fills up gun completely |
The Reload Speed stat is the duration (in ticks) that the player must wait
after initiating a reload before they can shoot or reload any gun.
The current progress in the reload is visible in an indicator bar
that appears above the player's hotbar.
If this slot is already being used by another mod/datapack,
it can be disabled in the GBG config menu:
/function config:gbg
This stat is very simple: it is how many times the player can shoot their gun before needing to reload. Any integer value is allowed. However, if you want your gun to not need to ever reload, it is recommended to instead make the gun Ammoless.
An ammoless gun is, at the most basic level, a gun with the Max Ammo stat set to 0 and the Current Ammo stat set to 1. This functionally makes the gun have no ammo, and display the max ammo as an infinity symbol in the gun's description.
Ammoless guns can exclude many of the stats mentioned above, as they are simply not needed, nor even used.
Obviously, one of the most important parts of any given gun is the model and sounds. While most guns will use custom models and custom sounds, you are more than capable of using vanilla sounds and vanilla models. This method allows for the creation of resource pack-less guns, while not everyone's first choice, they're really handy for testing.
There are two stats in the custom data component that refer to the model of the gun. The idle_model stat is the model of the gun while not zooming, and the zoom_model stat is the model of the gun while zooming/aiming.
As the name of these stats would imply: shoot_sound is the sound played when the gun is shot and reload_sound is the sound played when the gun is reloaded. The Shoot Sound is always played with an audible range roughly equivalent to the range of the gun. The Reload Sound is always played with an audible range roughly equal to sixteen blocks.
The shoot_sound_pitch and reload_sound_pitch stats, as the name would imply, change the pitch of these sounds when played. This is mainly helpful for making guns without a resource pack, as it allows more precise control over the vanilla sounds.
These two stats are completely optional; the gun will function perfectly fine without them. If the stats aren't present, a value of 1.0 is assumed for both.
This is a simple boolean stat that applies an attack speed modifier when the player zooms. The purpose of this modifier is to remove the up-and-down bobbing animation that is played when the player shoots a gun. Ordinarily, this animation is wanted, however, it may become a nuisance with automatic guns, as their model will bounce around too much to be visible.
If this stat is enabled, the zoom model of the gun will need to be tweaked.
As mentioned prior, the GBG config menu
contains some details pertaining to guns:
/function config:gbg
The player trigger command GBG config menu also
contains some configurable values for custom guns:
/trigger gbg_config
Beyond this, there are no special commands in Gun Core. If you want more commands, you will need to create them yourself :)