Turrets Tutorial: Upgrades

Upgrades Attributes

Upgrades will define the attributes the turret will have at certain level. You can add as many upgrades you want.

Attribute Name	Description
speed	Speed of the turret in seconds. speed: 3
range	Max distance of the turret in blocks. range: 16
min_damage max_damage	Minimum and maximum damage of the turret per shoot. These values are used when the Target is set to ENEMIES. min_damage: 1.5 max_damage: 2
min_heal max_heal	Minimum and maximum heal of the turret per shoot. These values are used when the Target is set to ALLIES. min_heal: 1 max_heal: 3
health	Health of the turret. Players can damage turrets using Bows. Turrets can also be damaged by explosions. If you want the turret to be invulnerable to any damage, remove this attribute. health: 100
splash_radius	This attribute will allow the turret to cause damage to nearby entities at the impact location. The radius is set in blocks. splash_radius: 2.5
max_targets	How many shoots a Turret can make at the same time. Defaults to 1. max_targets: 2
accuracy	What is the probability of the turret shooting the entity. The accuracy is represented by a percentage. A 100% percentage indicates that the turret will hit the entity everytime. If you set this to a lower value, the turret will miss some shoots. For turrets with PARABOLIC shoot type, this attribute will only affect the shoot itself but it doesn't mean the shoot will miss the entity and make no damage. If you want the turret to always hit entities, remove this attribute. accuracy: 85
critical_hit	Option to allow the turret to do a critical shoot, making more damage. Info HERE.
entity_damage_ reduction	This is a formula that will be applied everytime a player or entity gets damaged by a turret, and will reduce the damage taken by checking the entity armor. More info HERE. entity_damage_reduction: "%armor%*0.03+%protection_environmental_level%*0.02"
shield_reduction	This will check if the player is blocking with a shield and reduce the final damage. If you set it to 0.8, it means the damage will be reduced in a 80%. Use values between 0 and 1. This reduction is applied after already applying entity_damage_reduction if used. shield_reduction: 0.9
max_ammo	The ammunition limit for this turret upgrade. You must use a multiple of 576 (576, 1152, 1728, etc... Each inventory row will have 576 ammo items). max_ammo: 2880
money_cost	The cost to upgrade the turret to this level. (Requires Vault) money_cost: 3000
item_cost	The cost in items to upgrade the turret to this level. More info HERE.
custom_upgrade_item	An item replacement for the turret inventory upgrade item just for this level. You must use the same properties as te upgrade item: custom_upgrade_item: id: <id> name: <name> lore: - <lore>
custom_block_item	An item replacement for the turret block item just for this level. You must use the same properties as the custom_upgrade_item option.
actions	Actions to be executed for the hit entity. More info HERE.

upgrades:
    1:
      speed: 3
      range: 11
      min_damage: 1
      max_damage: 2
      splash_radius: 1.5
      accuracy: 60
      health: 50
      money_cost: 0
    2:
      speed: 2.5
      range: 13
      min_damage: 8
      max_damage: 15
      splash_radius: 2.5
      accuracy: 80
      health: 70
      money_cost: 1000

Actions

Turret upgrades can have an extra property called actions. Actions have some properties in common:

Option	Description
duration: 7	Duration of this action in seconds.
probability: 60	Probability (%) of executing this action on every hit.

Potion Effect

This action will apply a potion effect to the hit entity.

# In this example you can see that the second upgrade of this turret
# will have a 60% probability to apply SLOW effect level 1 for 7
# seconds to the hit entity.
2:
      speed: 2.5
      range: 13
      min_damage: 8
      max_damage: 15
      splash_radius: 2.5
      health: 70
      money_cost: 1000
      actions:
        action1:
          # Use the following format: 
          # "potion_effect: <potion_effect>;<level>" You can find all
          # potion effects here: 
          # https://hub.spigotmc.org/javadocs/spigot/org/bukkit/potion/PotionEffectType.html
          type: "potion_effect: SLOW;1"
          duration: 7
          probability: 60

Set on fire

This action will set the hit entity on fire.

actions:
  action1:
    # You just need to set the type to "set_on_fire"
    type: "set_on_fire"
    duration: 5
    probability: 20

Freeze

This action will freeze the entity. Only works on 1.17+.

actions:
  action1:
    # You just need to set the type to "set_on_fire"
    type: "freeze"
    duration: 20
    probability: 10

Knockback

This action will push the entity on hit with a certain value.

actions:
  action1:
    # Use the following format:
    # "knockback: <power>"
    # This action doesn't require a duration.
    type: "knockback: 0.5"
    probability: 100

Entity Damage Reduction

Most of the time you will want turrets to do damage according to the player current armor. If you want so, then you have to add the entity_damage_reduction option which is a formula. Read below to understand the behavior of this option.

# The turret normal damage is between 1 and 1.5.
# Imagine the player has 20 armor points provided by a full netherite armor
# without enchantments. This means, the entity damage reduction for this
# case will be: 20 * 0.03 + 0 * 0.03 = 0.6
# <20> representing the armor points and <0> meaning the armor doesn't have
# the projectile protection enchantment.
# The <0.6> final value means that the player will reduce the turret damage
# by a 60%. If the turret damages 1.2, the player will receive 0.48 damage.

# Now, what if the player has full netherite armor but all parts of this
# armor have the Projectile Protection Enchantment at level 4?
# The %protection_projectile_level% in this case will be
# 4+4+4+4 = 16 (since we are adding the level of all armor parts).
# Now the formula will be:
# 20 * 0.03 + 16 * 0.03 = 0.6 + 0.48 = 1.08
# This indicates that the damage will be reduced in a 108%. Since that's not
# possible, the damage is reduced by a 100% meaning the player doesn't
# take damage.
upgrades:
    1:
      speed: 0.75
      range: 10
      min_damage: 1
      max_damage: 1.5
      health: 50 
      entity_damage_reduction: "%armor%*0.03+%protection_projectile_level%*0.03"
      money_cost: 0

If you don't want damage reduction you can just remove this option.

You can change the formula as you want, just be careful and remember that the value must be greater or equal than 0. Below you can find possible variables to use.

Variable	Description
%armor%	Armor points of the player.
%armor_toughness%	Armor toughness points of the player.
%protection_projectile_level%	Sum of the PROTECTION_PROJECTILE enchantment level of all armor parts.
%protection_environmental_level%	Sum of the PROTECTION_ENVIRONMENTAL enchantment level of all armor parts.
%protection_explosions_level%	Sum of the PROTECTION_EXPLOSIONS enchantment level of all armor parts.
%protection_fire_level%	Sum of the PROTECTION_FIRE enchantment level of all armor parts.

Item Cost

Instead of using Vault and an economy plugin to upgrade turrets, you can do it by adding an item cost, so players will need to pay the upgrade using their items.

Option	Description
id: DIAMOND	Material of the required item. You can find all materiales on these links: Latest versions: https://hub.spigotmc.org/javadocs/spigot/org/bukkit/Material.html 1.8: https://helpch.at/docs/1.8/org/bukkit/Material.html
amount: 5	Required amount of this item.
name: "Epic Diamond"	Name of the required item. Don't use color format.
lore: -"Example lore"	Lore of the required item. Don't use color format.
message_displayname: "&eDiamond"	Name of the item to display in the upgrade item.

# In this example you can see that x5 Diamonds and x10 Iron Ingots are
# necessary to upgrade this turret to level 2.
2:
      speed: 5
      range: 6
      min_heal: 3
      max_heal: 5
      max_targets: 3
      health: 70
      item_cost:
        item1:
          id: DIAMOND
          message_displayname: "&eDiamond"
          amount: 5
        item2:
          id: IRON_INGOT
          message_displayname: "&eIron Ingot"
          amount: 10

Critical Hit

Option to allow the turret to do a critical shoot, making more damage/healing more.

3:
      speed: 0.25
      range: 14
      min_damage: 2
      max_damage: 3
      health: 100
      money_cost: 3000
      critical_hit:
        # Chance in % of this critical hit
        chance: 60
        
        # Damage when doing a critical hit instead
        min_damage: 4
        max_damage: 8
        
        # Heal when doing a critical hit instead. Of course, use
        # these values instead only when the turret heals allies.
        min_heal: 2
        max_heal: 4