Documentation: Guns - zaeonNineZero/Flans-Mod-Plus-Plus GitHub Wiki
Guns are weapons that load and consume ammo to shoot damaging projectiles. Flan’s Mod guns are highly configurable, and are usually 3D modeled items with animations for firing and reloading.
Gun items can be added and configured using .txt files in the “guns” directory of your Flan’s Mod content pack. The file itself sets up the gun’s ID name and description, compatible ammo, and firing behavior, as well as basic translation/rotation animations when firing. The 3D model of the gun itself must be written as a .java file and compiled into a .class file; the gun’s texture and icon must be square .png images.
Naming and description:
| Config Line | Description | Syntax | Default |
|---|---|---|---|
| Name | The unlocalized name that appears in gunboxes. Without it, gunboxes containing the item may crash when trying to display the name. You may include spaces in this section. | Name itemName | n/a (may cause crashes!) |
| ShortName (required) | The ingame ID name of the item, which will appear ingame as flansmod:ItemName. | ShortName itemIDName | n/a |
| Description | The description tag that appears on the item’s tooltip. You may include spaces in this section, and use “_” to create line breaks. | Description itemDescription | (blank) |
Visuals:
| Config Line | Description | Syntax | Default |
|---|---|---|---|
| Icon | The path of the item’s icon image, starting in assets/flansmod/textures/items. If the image is in a subfolder, you must designate the icon path as “Subfolder/Icon”. | Icon image | n/a |
| Model | The path of the item’s model class file, starting in com/flansmod/client/models. The model path must be written as “Pack.Gun”. | Model package.model | n/a (displays item icon instead) |
| Texture | The path of the item’s texture image, starting in assets/flansmod/skins. If the image is in a subfolder, you must designate the texture path as “Subfolder/Texture”. | Texture image | n/a) |
| ModelScale | The rescaling factor of the gun model. Useful for rescaling large, high-detail models down to a more usable size | ModelScale # | 1.0 |
| ItemUseAction | By default, held guns will force the player’s model to use the bow-drawing animation for other players, or when in third-person mode. If this config line is set to “none”, this behavior will be suppressed. | ItemUseAction bow/none | bow |
Model rendering offsets:
| Config Line | Description | Syntax | Default |
|---|---|---|---|
| ScopedYOffset | The Y-axis offset of the model in first-person view, when a scope attachment is equipped. Positive is upward, negative is downward. Note that this applies to model regardless of aiming or not | ScopedYOffset # | 0.0 |
| UnscopedYOffset | The Y-axis offset of the model, when there is no scope attachment equipped. | UnscopedYOffset # | 0.0 |
| UnscopedRotation | The rotation in degrees of the model when no scope is equipped. This is very useful for lining up the iron sights of a gun when just translating the model won’t line them up with the crosshair. | UnscopedRotation # | 0.0 |
| XOffset | The X-axis offset of the model. Positive moves the model away from the camera, negative moves it closer. | XOffset # | 0.0 |
| ZOffset | The Z-axis offset of the model. Positive moves the model to the right, negative moves it to the left. Note that this offset may result in misaligned iron sights! | ZOffset # | 0.0 |
| SightsYShiftUnscoped | Unscoped Y-axis offset when aiming down the sights. | SightsYShiftUnscoped # | 0.0 |
| SightsYShiftScoped | Scoped Y-axis offset when aiming down the sights. | SightsYShiftScoped # | 0.0 |
| SightsXShift | X-axis offset when aiming down the sights. | SightsYShiftUnscoped # | 0.0 |
| SightsXScopedOffset | An additional X-axis offset applied to SightsXShift when a scope is attached. | SightsYShiftUnscoped # | 0.0 |
| HipZShift | Z-axis offset when NOT aiming down the sights. Allows you to move the gun’s z-axis location when held without affecting the alignment of the sights. | HipZShift # | 0.0 |
Attachments:
| Config Line | Description | Syntax | Default |
|---|---|---|---|
| AllowAttachments | The list of attachments this gun can support. You can add as many attachment shortnames as needed, but they must all be separated using spaces. Note that attachments may only be added if the gun has the slot for that particular attachment type. | AllowAttachments attach_Suppressor attach_ACOG etc | (blank) |
| AllowAllAttachments | If true, overrides AllowAttachments to allow any attachment to be added to a gun. Useful for debugging, but often results in misaligned sight attachments if using sights from other content packs. | AllowAllAttachments True/False | False |
| AllowBarrelAttachments | If true, opens the barrel attachment slot for adding attachments. | AllowBarrelAttachments True/False | False |
| AllowScopeAttachments | If true, opens the scope attachment slot for adding attachments. | AllowScopeAttachments True/False | False |
| AllowGripAttachments | If true, opens the grip attachment slot for adding attachments. | AllowGripAttachments True/False | False |
| AllowStockAttachments | If true, opens the stock attachment slot for adding attachments. | AllowStockAttachments True/False | False |
| NumGenericAttachmentSlots | How many generic attachment slots should be opened for the gun. 0 means not generic attachment slots. | NumGenericAttachmentSlots # | 0 |
| ScopeAttachmentOffset | The x, y, and z offsets of scope attachments, allowing for quick fine-tuning of the location of attachments. | ScopeAttachmentOffset # # # | 0.0 0.0 0.0 |
| BarrelAttachmentOffset | The x, y, and z offsets of barrel attachments, allowing for quick fine-tuning of the location of attachments. | BarrelAttachmentOffset # # # | 0.0 0.0 0.0 |
| GripAttachmentOffset | The x, y, and z offsets of grip attachments, allowing for quick fine-tuning of the location of attachments. | GripAttachmentOffset # # # | 0.0 0.0 0.0 |
| StockAttachmentOffset | The x, y, and z offsets of stock attachments, allowing for quick fine-tuning of the location of attachments. | StockAttachmentOffset # # # | 0.0 0.0 0.0 |
Paintjobs:
| Config Line | Description | Syntax | Default |
|---|---|---|---|
| Paintjob | Adds a new Paintjob to the gun; you may repeat this line for as up to 8 paintjobs. You must add the icon name and texture name of the file. You may optionally add dyes that are needed as well, in a sequence of “dyeColor numberOfDyes”, with as many dyes as you wish. Dye colors include “black”, “red”, “green”, “brown”, “blue”, “purple”, “cyan”, “silver”, “gray”, “pink”, “lime”, “yellow”, “lightBlue”, “magenta”, “orange”, “white”. | Paintjob iconPath texturePath dyeColor # | n/a |
| NamedPaintjob | Nearly identical to Paintjob, but with an additional input for a displayable name for the Paintjob. Use “_” to add spaces to the name. | NamedPaintjob iconPath texturePath paintjobName dyeColor # | n/a |
| DefaultPaintjobName | The name of the gun’s default Paintjob. Use “_” to add spaces to the name. | DefaultPaintjobName paintjobName | n/a |
| ShowPaintjobName | Whether to show the name of the Paintjob in the description of the gun item. Unnamed Paintjobs will not be shown. | ShowPaintjobName True/False | True |
Ammo and Reloading:
| Config Line | Description | Syntax | Default |
|---|---|---|---|
| Ammo | Adds a bulletType or grenadeType item as valid ammo for the gun to shoot’ you can add multiple ammo types by repeating this line. Note that loading grenades will cause the grenade to override Accuracy and BulletSpeed. | Ammo itemIDName | n/a |
| ReloadTime | How long (in ticks) the gun will be unusable for when reloading. This must be an integer. | ReloadTime # | n/a |
| ReloadDelay | How long (in ticks) the gun cannot be reloaded using R once empty. This must be an integer. | ReloadDelay # | 10 |
| LoadIntoGun | How many ammo items the gun can load at once. This is useful for making revolvers and shotguns | LoadIntoGun # | 1 |
| CanForceReload | Whether the reload key (R by default) can be used to force the gun to reload. If false, the gun may only be reloaded using right clicks. | CanForceReload True/False | True |
Camera Recoil:
| Config Line | Description | Syntax | Default |
|---|---|---|---|
| Recoil | The amount of vertical camera recoil, in degrees, from giving the gun. Camera recoil settles quickly after shooting, but generally settles a bit quicker for low-recoil guns. For reference, pistols usually have 1-2 recoil, low caliber rifles usually have 3-5 recoil, and shotguns usually have 10+ recoil. | Recoil # | 0.0 |
| RandomRecoilRange | The range of randomized vertical recoil to add on top of normal recoil. Higher values result in high variability, and higher average recoil. | RandomRecoilRange # | 0.0 |
| RandomRecoilYawRange | The level of randomized horizontal camera recoil from firing the gun. This pushes the camera left and right briefly when firing, and settles down soon after. | RandomRecoilYawRange # | 0.0 |
| DecreaseRecoil | How much vertical recoil is decreased when sneaking. By default this subtracts from the gun’s base recoil, but can be set to act as a divider instead. | DecreaseRecoil # | 0.0 |
| UseDecreaseRecoilDivider | Sets DecreaseRecoil to function as a divider, similar to DecreaseRecoilYaw. | UseDecreaseRecoilDivider True/False | False |
| DecreaseRecoilYaw | How much horizontal recoil is decreased when sneaking. This is always a divider. | DecreaseRecoilYaw # | 1.0 |
Animation Controls:
| Config Line | Description | Syntax | Default |
|---|---|---|---|
| RecoilAnimXForce | How much backward kick the gun model has when firing. Alternatively, set this to negative to make the model lurch forward when firing. | RecoilAnimXForce # | 0.5 |
| RecoilAnimYForce | The upward/downward kick factor in the gun’s model recoil. Positive is upward, negative is downward. Pair with RecoilAnimRotation to move the model’s rotation center forward or backward. | RecoilAnimYForce # | 0.0 |
| RecoilAnimRotation | The angular kick factor in the gun’s model recoil, in degrees. Positive will rotate the gun upward. | RecoilAnimRotation # | 0.0 |
| PumpAnimXShift | How much the gun should move backward/forward when the pump animation is running. | PumpAnimXShift # | 0.7 |
| PumpAnimYShift | How much the gun should move upward/downward when the pump animation is running. | PumpAnimZShift # | -0.5 |
| PumpAnimZShift | How much the gun should move right/left when the pump animation is running. | PumpAnimZShift # | 0.0 |
| PumpAnimPitch | How much the gun should pitch upward/downward, in degrees, when the pump animation is running. | PumpAnimPitch # | 4.0 |
| PumpAnimYaw | How much the gun should turn left/right, in degrees, when the pump animation is running. | PumpAnimPitch # | 0.5 |
| PumpAnimTilt | How much the gun should tilt right/left, in degrees, when the pump animation is running. | PumpAnimPitch # | 3.0 |
| BoltAnimTilt | How much the pump model of the gun should rotate. Useful for making rotating bolts, but needs BoltCenterOffset to use properly. | BoltAnimTilt # | 0.0 |
| BoltRotateSpeed | How faster the pump model of the gun should rotate. Higher values mean that the pump reaches its maximum angle quicker. | BoltRotateSpeed # | 1.0 |
| BoltCenterOffset | The Y-axis offset of the pump’s rotation point. Use this to align the rotation point with the bolt model so that it rotates smoothly. | BoltCenterOffset# | 0.0 |
| SprintAnimationType | The preset sprint animation that should be used when sprinting. One of “Raise”,”Lower”,”Pistol”,”Rifle”,”Holster”,”Heavy”, or “None”. If CanShootWhileSprinting is set to True, the sprint animation will be unused. | SprintAnimationType animationType | Simple |
Projectile Characteristics:
| Config Line | Description | Syntax | Default |
|---|---|---|---|
| Damage | How much damage bullets fired from the gun should do. Decimal values work as well. This value gets multiplied by the damage value set in the bullet file. | Damage # | 0.0 |
| NumBullets | How many projectiles are fired from the gun. Note that. | NumBullets # | 1 |
| AllowNumBulletsByBulletType | If set the true, and the loaded bullet has the NumBullets line set, uses the bullet’s NumBullets for determining projectile count per shot. | AllowNumBulletsByBulletType True/False | False |
| BulletSpeed | How fast bullets fired from the gun travel. | BulletSpeed # | 3.0 |
| AllowBulletSpeedByBulletType | If set the true, and the loaded bullet has the BulletSpeed line set, uses the bullet’s BulletSpeed for determining bullet speed. | AllowBulletSpeedByBulletType True/False | False |
| Accuracy/Spread | How much spread the bullets have when fired from the gun. | Accuracy # | 0.0 |
| SpreadMultiplierHip | Multiplier for how much more/less spread bullets have when firing without aiming. For best results, choose either this or SpreadMultiplierAiming; if using this one, set it to anything greater than 1. | SpreadMultiplierHip # | 1.0 |
| SpreadMultiplierAiming | Multiplier for how much more/less spread bullets have when firing while aiming. For best results, choose either this or SpreadMultiplierHip; if using this one, set it to anything between 0 and 1. | SpreadMultiplierAiming # | 1.0 |
| SpreadMultiplierSprinting | Multiplier for how much additional spread bullets have when firing while sprinting. CanShootWhileSprinting must be True for this to have any effect. | SpreadMultiplierHip # | 1.0 |
| AllowSpreadByBullet | If set the true, and the loaded bullet has the Spread line set, uses the bullet’s Spread for determining bullet spread. | AllowSpreadByBullet True | False |
| IgnoreArmorProbability | The probability for bullets fired from this gun to bypass armor’s damage reduction. Use IgnoreArmorDamageFactor to determine how much of armor’s damage reduction gets ignored. Setting this to 0 will disable armor penetration, while setting this to 1 will make all shots bypass armor. | IgnoreArmorProbability # | 0.0 |
| IgnoreArmorDamageFactor | How much of armor’s damage reduction is ignored when a bullet is able to pierce armor. Setting this to 1 will result in the bullet bypassing all armor damage reduction; setting this to 0 will effectively disable armor penetration. | IgnoreArmorDamageFactor# | 0.0 |
Bullet Knockback:
| Config Line | Description | Syntax | Default |
|---|---|---|---|
| DoKnockback | If set to false, bullets will do absolutely no knockback. | DoKnockback True/False | True |
| ModifyKnockback | When true, this modifies bullet knockback to mostly eliminate the upward knockback from being hit, and allows KnockbackDampening to take effect. | ModifyKnockback True/False | True |
| KnockbackDampening | Determines how much bullet knockback should be reduced; higher values result in less overall knockback. Setting this to 0 will leave horizontal knockback unchanged, but vertical knockback will still be eliminated. If set to lower than 0, horizontal knockback will increase. | KnockbackDampening # | 2.0 |
| UseBulletKnockback | If this is set to true, any knockback variable set in the bullet’s config file will be used in place of those set in the gun’s file. | UseBulletKnockback True/False | False |
Firing:
| Config Line | Description | Syntax | Default |
|---|---|---|---|
| ShootDelay | The amount of ticks between shots. Setting this to 1 will result in one shot every tick, or 20 bullets per second; setting this to 20 will result in one shot every second. | ShootDelay # | 4 |
| Mode | The mode of fire the gun. Valid options include SemiAuto (One shot per click), FullAuto (Repeating shots when the mouse button is held), Burst (A set number of bullets fired in sequence per click), and Minigun (Gun must wind up before automatic shooting). You can add more than one fire mode to this line to add alternative fire modes, which can be switched to using the Gun Mode key. | Mode primaryFireMode additionalFireMode(s) | FullAuto |
| NumBurstRounds | The number of rounds fired per burst. Only used if the gun’s current fire mode is Burst mode | NumBurstRounds # | 3 |
| MinigunStartSpeed | The rotation speed of a minigun’s barrels that is required before a gun in Minigun mode can shoot. Note that this is NOT in ticks after first pressing the right mouse button- it is a nonlinear increase. | MinigunStartSpeed # | 15 |
| DropItemOnShoot | An item to be dropped whenever the gun shoots. This occurs regardless of what bulletType is loaded into the gun. | DropItemOnShoot itemName | (none) |
| ConsumeGunOnUse | If true, the gun item will be consumed when it is fired. Useful for disposable rocket launchers, such as Panzerfausts | ConsumeGunOnUse True/False | False |
| CanShootUnderwater | Whether the gun can be fired while underwater. (Currently broken) | CanShootUnderwater True/False | True |
Sounds:
| Config Line | Description | Syntax | Default |
|---|---|---|---|
| ShootSound | The sound that plays when firing the gun. | ShootSound soundFile | n/a |
| GunSoundRange | How far away the gunshot can be heard. This value is reduced when a weapon is suppressed/silenced. | GunSoundRange # | 50 |
| CustomSilencedSound | Normally, when a weapon has a suppressor/silencer equipped, the base gunshot sound is sped up and has a shorter range. |
However, if this is set to true, a custom suppressed gunfire sound can be assigned and used.|CustomSilencedSound soundFile|false|
| ShootSoundSilenced | The firing sound to play when a suppressor/silencer is equipped, if CustomSilencedSound is true. | ShootSoundSilencedsoundFile | n/a |
| DistortSound | Setting this to false will disable randomized gunfire sound pitch. Recommended for pump-action and bolt-action guns. | DistortSound True/False | True |
| ReloadSound | The sound that plays when a gun starts reloading. | ReloadSound soundFile | n/a |
| ReloadSoundRange | How far away a reloading gun can be heard. | GunSoundRange # | 50 |
| IdleSound | A looping sound that ambiently plays when the gun is held. | IdleSound soundFile | n/a |
| IdleSoundLength | How often the idle sound should repeat, in ticks. | IdleSoundLength # | n/a |
| WarmupSound | A looping sound that plays when a minigun’s barrels start spinning. | WarmupSound soundFile | n/a |
| WarmupSoundLength | How often the warmup sound should repeat, in ticks. | WarmupSoundLength # | n/a |
| SpinSound | A looping sound that plays when a minigun’s barrels are actively spinning. | SpinSound soundFile | n/a |
| SpinSoundLength | How often the warmup sound should repeat, in ticks. | WarmupSoundLength # | n/a |
| CooldownSound | A non-looping sound that plays when a minigun is winding down. | CooldownSound soundFile | n/a |
Sights:
| Config Line | Description | Syntax | Default |
|---|---|---|---|
| Scope | The GUI overlay to use when the gun is aimed. Note that using an overlay will cause the model to disappear while scoped in. Scope attachments will override this setting, but it is useful for guns that have a scope by default. | Scope guiFile | n/a |
| ZoomLevel | How much zoom should be applied when a GUI overlay is active. Mouse sensitivity will decrease while zoomed in to help with fine aiming. Note that this is a multiplier- do not set to 0! | ZoomLevel # | 1.0 |
| FOVZoomLevel | How much FOV zoom should be applied when aiming. Unlike ZoomLevel, this won’t hide the gun model while aiming, making it useful for iron sights or red dot/holographic sights. Mouse sensitivity will still decrease while aiming to help with fine aiming. These effects stack with ZoomLevel as well. Note: this variable is also a multiplier. | FOVZoomLevel # | 1.5 |
Melee:
| Config Line | Description | Syntax | Default |
|---|---|---|---|
| SecondaryFunction | This controls the secondary action of the gun. By default, it’s set to “Zoom”, but it can be set to “Melee” to force a vanilla Minecraft melee attack on left click. | SecondaryFunction function | Zoom |
| MeleeDamage | How much damage melee attacks- both vanilla and custom melee- do to targets. Does not apply when aiming down sights. Note that this takes the form of an Attack Damage attribute, so setting this to 0 will still result in melee attacks doing 1 HP. | MeleeDamage | 1 |
| SwingWeaponOnShoot | If SecondaryFunction is set to Melee, this option will force the gun to be swing when fired. | SwingWeaponOnShoot True/False | False |
| UseCustomMelee | Enables custom melee swinging and hit detection if set to true. | UseCustomMelee True/False | False |
| UseCustomMeleeWhenShoot | This option allows a gun with a custom melee animation to play its animation when shooting. | UseCustomMeleeWhenShoot True/False | False |
| MeleeTime | The delay, in ticks, between custom melee attacks. | MeleeTime # | 1 |
| MeleeDamagePoint | The point on the gun model that inflicts melee damage when hitting entities. This point will rotate and translate with the model. | MeleeDamagePoint # # # | n/a |
| AddNode | Adds a node to the custom melee animation, with each node being an ingame tick. Node entries are formatted as: x, y, z, pitch, yaw, roll. | AddNode # # # # # # | n/a |
Misc:
| Config Line | Description | Syntax | Default |
|---|---|---|---|
| UsableByPlayers | Whether the gun can be used by players | UsableByPlayers True/False | True |
| UsableByMechas | Whether the gun can be used by Mechas | UsableByMechas True/False | True |
| MoveSpeedModifier | Modifies how fast the player can move. | MoveSpeedModifier # | 1.0 (No change) |
| KnockbackReduction | Adds a knockback resistance attribute to the gun. Note that this does not actually reduce incoming knockback, but instead adds a chance for knockback to be ignored. | KnockbackReduction # | 0.0 |
| OneHanded | If set to true, the gun can be dual-wielded with other compatible guns. | OneHanded True/False | False |