Sustained Recoil

Sustained Recoil allows you implement a more detailed firing animation, specifically designed for automatic guns.

The premise is that as the player keeps holding the trigger, the gun will slowly travel back, and angle more and more.

Here’s what it looks like in a gun JSON:

{
	"name": "packname_gunname",
	"type": "Gun",
	"maxAmmoCapacity": 30,
	"compatibleAmmo": [
		"ammocreative",
		"ammo556"
	],
	"damage": 5,
	"fireSound": "gunsoundfilename",
	"fireModes": [
		"AUTOMATIC"
	],
	"rpm": 700,
	"gunRecoilInitialAmplitude": 0.2,
	"shakeRecoilAmplitude": 0.35,
	"shakeRecoilSpeed": 2,
	"viewRecoilAmplitude": 1.2,
    "sustainedRecoil": {
        "posZCap": 0.16,
        "posZIncrement": 0.06,
        "pitchIncrement": 0,
        "posYIncrement": 0
    },
	"phasedReloads": [
	],
	"effects": [
	],
	"drawAnimations": [
	]
}

Good practice to put it near the top, along with the other stuff like attachments and recoil, so it’s easy to find.

Let’s look at the code in isolation:

"sustainedRecoil": {
    "posZCap": 0.16,
    "posZIncrement": 0.06,
    "pitchIncrement": 0,
    "posYIncrement": 0
  }

To control the overtime motion of the gun as the player holds the trigger, there are a few elements like z-axis movement, x-axis angling (pitch), and more.

In the above example, we have:

"posZCap" controlling the maximum distance the gun travels in the z axis. Here, it’s set to cap at distance 0.16.

"posZIncrement" controlling how far the gun travels per shot until it reaches the z cap. Here, the gun travels at 0.06 per shot.

"pitchIncrement" controlling how much the gun pitches (rotates on the x axis) per shot. Here, the pitch increment is set to 0, so the gun never angles as it shoots.

"posYIncrement" controlling how much the gun travels on the y axis (up/down) per shot. Here, the y increment is set to 0 so the gun never moves up or down as it shoots.

A more complete example would look like this:

"sustainedRecoil": {
    "posZCap": (insertvalue),
    "posZIncrement": (insertvalue),
    "pitchIncrement": (insertvalue),
    "posYIncrement": (insertvalue),
    "pitchCap": (insertvalue),
    "posYCap": (insertvalue)
  }

You can control the z axis increment, z axis cap, pitch cap, pitch increment, y axis cap, and y axis increment.

When you control the pitch, it’s possible you may also want to control the y axis to make it look more visually appealing—that’s why the option exists.

Alternatively, if you want the gun just to go back, and not pitch at all, you can set y increment to zero:

"sustainedRecoil": {
    "posZCap": 0.16,
    "posZIncrement": 0.06,
    "pitchIncrement": 0,
    "posYIncrement": 0
  }

Each of these values has a default. If you write:

"sustainedRecoil": {
  }

---then the gun will use all the default values for z cap, z increment, pitch, etc..

If you don’t have sustainedRecoil in your gun at all, the gun will not use the sustained recoil feature whatsoever.

If you write:

"sustainedRecoil": {
    "posZCap": 0.16,
    "posZIncrement": 0.06
  }

---then the gun will assign custom values for z cap and z increment, and use defaults for pitch cap and others, since you didn’t write those in.

There’s one last value:

"decayTime"

It looks like this:

"sustainedRecoil": {
    "posZCap": 0.16,
    "posZIncrement": 0.06,
    "decayTime": 1000
  }

Decay time controls how fast the gun resets to idle/neutral after the player stops holding the trigger. In the example above, it’s set to 1000 milliseconds. Like all other values, if it’s missing, the gun will use the default value.