Skip to content

Projectiles

Jump to bottom
Vaan1310 edited this page Jan 19, 2026 · 2 revisions

Let's say you made your own cannons, or you like the default ones already, now it is time to add the custom projectile with fancy behaviour and appearance.

There are two files that handle the projectile:

Cannon Projectile Definition

All the projectiles are defined in the /projectiles folder and have a .yml format, the file name is also called the projectileID.

This file contains all the data utilize by cannons specifically.

Let's use the cobblestone.yml file as a reference

general:
  #the name of the projectile displayed in game
  projectileName: cannonball

  #a short description of the projectile
  description: "A cheap and simple cannonball."
  #the name of the item to load this projectile
  itemName: cobblestone

  #the item which is associated with the projectile.
  #items can be assigned to many different projectiles which are used with different cannons
  #example: one cannon can be loaded with stone but will fire an armor piercing round, while a different cannon
  #can be loaded with stone and it will fire an explosive projectile (minimum is minecraft:material. Named items minecraft:material;displayName;lore1;lore2:....)
  #https://www.digminecraft.com/lists/item_id_list_pc.php
  loadingItem: 'minecraft:cobblestone'

cannonball:
  #the type of the projectile entity
  #ARROW, EGG, FIREBALL, SMALL_FIREBALL, SNOWBALL, THROWN_EXP_BOTTLE, SPLASH_POTION, WITHER_SKULL
  # can also be one of custom type defined in the Base Projectile Definition
  entityType: SNOWBALL

  #set to true if you want to have a burning projectile
  isOnFire: false

  #the velocity of the projectile.
  velocity: 3

  #how many blocks the projectile will penetrate before it explodes. If it hits something impenetrable (e.g. obsidian) it will explode instantly.
  penetration: 1

  #whether the .projectile destroys blocks it penetrates. If false it will explode if it hits something impenetrable.
  doesPenetrationDamage: true

  #how many seconds after firing the projectile will detonate if it does not hit anything
  timefuse: 0.0

  #the delay in seconds between two fired cannonball in the automatic firing mode. Highest firing frequency is 20 shots per second - 0.05s
  automaticFiringDelay: 1.0

  #a cannon can fire several times with a single projectile - like a magazine in a automatic firearm
  automaticFiringMagazineSize: 1

  #how many projectiles are fired with a single shoot
  numberOfBullets: 1

  #the higher this is, the more inaccurate the projectile. This multiplies the "spreadOfCannon" property of the cannon it is fired from
  spreadMultiplier: 1.0

  #ignored the set number of blocks for sentries and will target entities behind walls
  sentryIgnoredBlocks: 0

  #different properties of the projectile. If you don't want any of these properties then just leave this all blank.
  #possible properties are: superbreaker, incendiary, human_cannonball, teleport, observer
  properties:
    #this property sets the impact area on fire. range is determined by the explosion power property
    - incendiary

smokeTrail:
  #the projectile has a smoke trail which makes it easier to spot
  enabled: true

  #distance between two smoke clouds
  distance: 10

  #material the smoke is made of
  material: 'minecraft:cobweb'

  #how long the smoke will stay in seconds
  duration: 5.0

  particles:
    # whether to use particles for the smoke trail instead of a block
    enabled: false
    # name of the particle to use - see https://hub.spigotmc.org/javadocs/spigot/org/bukkit/Particle.html for a list
    type: SMOKE_NORMAL
    # how many particles to spawn
    count: 1
    # the x, y and z offset of the particles
    x_offset: 0
    y_offset: 0
    z_offset: 0
    # how fast the particle travels to its offset position
    speed: 1

explosion:
  #the explosion power of the cannonball when it hits; this number determines the explosions range in blocks.
  #for comparison, the explosion power of a creeper is 3. anything above 50 will cause lag on smaller servers
  explosionPower: 2.0
  
  #explosion power depends on velocity (see kinetic energy)
  explosionPowerDependsOnVelocity: true

  #whether the explosion will destroy blocks
  doesExplosionDamage: true

  #the explosion power is set to zero if the explosion is underwater (superbreaker will still do damage)
  doesUnderwaterExplosion: false

  #if the projectile hits the player additional damage is done. Damage is in half hearts and the player has 20 half hearts in vanilla minecraft.
  directHitDamage: 100

  #if the player is next to an explosion he will receive additional damage
  playerDamageRange: 5

  #the damage which the player receives when he is near an explosion. Damage is in half hearts and the player has 20 half hearts in vanilla minecraft.
  playerDamage: 10

  #the range of the potion effects specified below
  potionRange: 5

  #how long the effects will last. If the potion duration is <= 0 it will be disabled
  potionDuration: 7

  #how powerful the effect is, the higher this is the more powerful the effect. If set to 1 it has potion effect type II, if 0 potion effect type I
  potionAmplifier: 1

  #which potion effects are used. a list of effects supported by bukkit can be found here-
  #http://jd.bukkit.org/rb/apidocs/org/bukkit/potion/PotionEffectType.html
  potionEffects:
   - harm
   - slow

  #marks the impact with blocks (default: glowstone)
  impactIndicator: true

#spawns additional delayed explosions around the explosion
clusterExplosion:

  #true it on or off
  enabled: false

  #explosion can also be in blocks and not only in air
  explosionInBlocks: false

  #how many explosions will be spawned
  amount: 10

  #after which time the explosion will be triggered [s]
  minDelay: 0.5

  #how long the explosion will last [s]
  maxDelay: 5.0

  #in which sphere radius this explosion will occur
  radius: 5.0

  #explosion power
  power: 4.0

#spawn blocks, entities or/and new projectiles on impact
spawnOnExplosion:
  #enable this feature
  enabled: false

  #the radius where blocks will be placed. If the radius is too small there might be no air gap to spawn a block.
  blockRadius: 2.0

  #the radius where entities will be placed. If the radius is too small there might be no air gap to spawn a block.
  entityRadius: 2.0

  #the velocity of blocks/entities are slinged away from the impact
  velocity: 0.5

  #the blocks which will be placed. does not seem to support more tha one block type at a time.
  #spawn an block with (minecraft:material minAmount-maxAmount)
  block:
    #this is a cobweb to slow the enemy
    - 'minecraft:cobweb 1-3'

  #spawn entity with the name. (Formatting 'NAME min-max')
  #https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/entity/EntityType.html
  entity:
    #- 'LINGERING_POTION 20-50 {Potion:long_poison}'
    #- 'ZOMBIE 1-4'
    #- 'AREA_EFFECT_CLOUD 1-3 {Color:16711680, Duration:100, Radius:3, Potion:poison}'
    #- 'TIPPED_ARROW 30-50 {Potion:poison}'

  #spawns a new projectiles after the explosion of this projectile with the given name (file name)
  #spawning the same projectile more than once results in a endless loop
  #the number of spawned projectile depends on 'numberOfBullets' of the spawned projectile
  # DO NO PUT THE SAME PROJECTILE AS THIS ONE, IT WILL SPAWN THEM RECURSIVELY UNTIL YOUR SERVER DIES
  projectiles:

spawnFireworks:
  #if true fireworks will be spawned on projectile explosion
  enabled: false

  #if the firework flickers or not
  flicker: false

  #if the firework has a trail
  trail: true

  #effect type of the fireworks: BALL, BALL_LARGE, BURST, CREEPER, STAR,
  type: BALL

  #main colors (RGB in hex notation)
  #if there are no color, than there will be no fireworks
  colors:

  #fade colors in RGB hex notation
  fadeColors:
    #white
    - 'FFFFFF'

messages:
  #if this projectile can send a message of the impact location.
  hasImpactMessage: true

sounds:
  #You can enter new sounds in the following way 'NAME:VOLUME:PITCH'. Like 'IRON_GOLEM_WALK:1:0.5'
  #NAME: You can use minecraft sounds (block.anvil.hit), custom resource sound packs, or bukkit sound names (https://hub.spigotmc.org/javadocs/spigot/org/bukkit/Sound.html)
  #VOLUME: How far you will hear this sound
  #PITCH: How fast it is played. (0.5-2)
  #USE 'none:1:1' to disable this sound

  #loading sound of projectile
  loading: 'ENTITY_IRON_GOLEM_ATTACK:5:0.5'

  #impact sound
  impact: 'ENTITY_GENERIC_EXPLODE:10:0.5'

  #impact sound if the area is protected by an plugin (ProjectileImpactEvent was cancelled)
  impactProtected: 'ENTITY_GENERIC_EXPLODE:10:0.5'

  #impact on water surface
  impactWater: 'ENTITY_GENERIC_SPLASH:10:0.3'

loadPermission:
  #the permissions required for a player to use this projectile. There can be several permissions to load a projectile
  - cannons.projectile.default

Base Projectile Definition

You are going to need this if you want to make modifications to the way the projectile looks, or some minecraft behaviour, mainly custom model data and their physics (gravity, acceleration, drag).

Format

"<my_server_name>:<my_server_projectile>": # also called base projectile definition key
   entity: <entityType> https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/entity/EntityType.html

   # these fields are used to change how the projectiles behave,
   # however options different from default values can behave in a "sluggish" way
   # if not set, they will use the default values of the entity
   constantAcceleration: <double?> # can be null, for projectile like snowballs it is 0 in vanilla mc
   gravity: <double>
   drag: <double>
   waterDrag: <double>

   glowing: <true|false>

   onFire: <true|false default=false>
   charged: <true|false default=false> # works only for wither skulls, makes it charged
   critical: <true|false> # false works for arrows and tridents, makes them leave a visible tray

   # available for all entities that are Attributable, generally all living entities have this
   attributes:
      <attribute_key>: <double>

   # for throwable projectiles, such as snowballs, and item displays, edits the item to display stuff
   material: <material> https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Material.html
   customModelData: <integer> (Old format)

Examples

Trident that never slows down (you should have timed explosion for such projectiles)

"vaan_test_server:stab_stab":
  entity: "TRIDENT"
  
  gravity: 0.0
  drag: 1.0
  waterDrag: 1.8

  glowing: true

  critical: true

BIG cod, living entities won't have an AI, and on death they will explode

"winterfellmc:massive_cod":
  entity: "COD"
  # for weird entities without a proper gravity, drag and waterDrag, they will follow the same behaviour as snowball
  attributes:
     scale: 4.0

Clone this wiki locally