Wrappers For Developers

This section is dedicated to developers. If you are looking for the server admins' page, click here

Many of the fields referenced on this page might be or require platform-specific values. Check the glossary

All the objects described in this section are part of the base module, which is totally independent of any platform. If you want to store or load data on files, you will need to import the serializer module and use WrappersYAGLParser#addAllParsers() JUST ONCE before starting any IO operation. Any reference to bukkit requires the bukkit module imported.

Table of contents
Enchantment
PotionEffect
Sound
Particle

Enchantment

The Enchantment class allows creating a wrapper for an enchantment. These will NOT be checked, so any invalid name can be specified (and should be treated with caution). Check the relative server admins section to understand the default values of the constructors.

Example:

Enchantment enchantment = new Enchantment("sharpness", 3);  

To convert from and to Bukkit, you can use functions from WrappersAdapter:

• enchantToWEnchant(Enchantment, int): allows converting a Bukkit enchantment and a level to a YAGL Enchantment;
• wEnchantToEnchant(Enchantment): allows converting a YAGL enchantment by returning a tuple with the corresponding Bukkit enchantment and the level.

PotionEffect

The PotionEffect class allows creating a wrapper for a potion effect. These will NOT be checked, so any invalid name can be specified (and should be treated with caution). Check the relative server admins section to understand the default values of the constructors.

Example:

PotionEffect potionEffect = new PotionEffect("strength", 2, 2, false, true);

To convert from and to Bukkit, you can use functions from WrappersAdapter:

• potionEffectToWPotionEffect(PotionEffect): allows converting a Bukkit PotionEffect to a YAGL PotionEffect;
• wPotionEffectToPotionEffect(PotionEffect): allows converting a YAGL PotionEffect to a Bukkit PotionEffect;

Sound

The Sound class allows creating a wrapper for a sound. These will NOT be checked, so any invalid name can be specified (and should be treated with caution). Check the relative server admins section to understand the default values of the constructors.

Example:

Sound sound = new Sound("entity_cat_ambient", 1.0f, 2.0f, "ambient");

You cannot directly convert a YAGL Sound to Bukkit, but you can play it for players. To do so, you can use functions from WrappersAdapter:

• playSound(Player, Location, Sound): plays the specified sound for the player at the given location;
• playCustomSound(Player, Location, Sound): contrary to its normal variant, this function allows playing a sound for the player WITHOUT checking it first. This means that, if the sound is invalid, no exception will be thrown.

Particle

Particles cannot be directly created, but instead they can be chosen from ParticleType (Minecraft 1.13+). To create one, a ParticleType#createParticle() method is provided.

WARNING: for older versions of Minecraft, check out the effects section.

There are many functions to convert YAGL Particle to Bukkit in WrappersAdapter:

• wParticleToParticle(Particle): converts the given YAGL particle to a tuple containing the corresponding Bukkit particle and its particle option (if specified, see below for more);
• spawnParticle(Player, Particle, Location, int, double, double, double): spawns the given YAGL particle for the specified player at the given location with the given parameters (count and offset). There is also a counterpart with no offsets required;
• spawnParticle(Player, Particle, double, double, double, int, double, double, double): constructs a new Location from the player current world and the given x, y, z values. Then, it invokes the previous function;
• spawnParticle(Player, World, Location, int, double, double, double): like its Player counterpart, but for the whole world;
• spawnParticle(Player, World, double, double, double, int, double, double, double): like its Player counterpart, but for the whole world.

Special types of particles

The majority of the types will not allow an option to be passed to the ParticleType#createParticle(ParticleOption) method. However, some can have optional parameters passed that will change their default behaviour. To do so, a ParticleOption class is provided with many implementations.

Here is a full list of particles allowing options with examples:

• REDSTONE, requires a DustParticleOption with two parameters:
  • the Color of the particle, either with Color#fromARGB(String) or by one of the default values: WHITE, SILVER, GRAY, BLACK, RED, MAROON, YELLOW, OLIVE, GREEN, AQUA, TEAL, BLUE, NAVY, FUCHSIA, PURPLE, ORANGE;
  • the size of the particle as a float.

Particle particle = ParticleType.REDSTONE.createParticle(new DustParticleOption(Color.fromARGB("#FFFF00AA"), 2.0f));

• ITEM_CRACK, requires a ItemParticleOption with an Item from the item module to be passed. For more specific documentation, check the official documentation.

Particle particle = ParticleType.ITEM_CRACK.create(new ItemParticleOption(item));

• BLOCK_CRACK, requires a BlockDataOption, specifying either the material and the nbt, or both in the format <material>[<nbt>]:

Particle particle = ParticleType.BLOCK_CRACK.createParticle(new BlockDataOption("oak_log[axis=y]"));

• BLOCK_DUST, requires a BlockDataOption, specifying either the material and the nbt, or both in the format <material>[<nbt>]:

Particle particle = ParticleType.BLOCK_DUST.createParticle(new BlockDataOption("oak_log[axis=y]"));

• FALLING_DUST, requires a BlockDataOption, specifying either the material and the nbt, or both in the format <material>[<nbt>]:

Particle particle = ParticleType.FALLING_DUST.createParticle(new BlockDataOption("oak_log[axis=y]"));

• DUST_COLOR_TRANSITION, requires a DustTransitionParticleOption with two parameters:
  • the starting Color of the particle, either with Color#fromARGB(String) or by one of the default values: WHITE, SILVER, GRAY, BLACK, RED, MAROON, YELLOW, OLIVE, GREEN, AQUA, TEAL, BLUE, NAVY, FUCHSIA, PURPLE, ORANGE;
  • the ending Color;
  • the size of the particle as a float.

Particle particle = ParticleType.DUST_COLOR_TRANSITION.createParticle(new DustTransitionParticleOption(Color.RED, Color.BLUE, 12f));

• SCULK_CHARGE, requires a PrimitiveParticleOption with a float as argument:

Particle particle = ParticleType.SCULK_CHARGE.createParticle(new PrimitiveParticleOption<>(3.0f));

• SHRIEK, requires a PrimitiveParticleOption with an integer as argument:

Particle particle = ParticleType.SHRIEK.createParticle(new PrimitiveParticleOption<>(3));

• VIBRATION, requires a Vibration object. There is no official ParticleOption nor parser for this particle. This decision was taken because of the little use case that this particle has, but in the future this might change.

Particle particle = ParticleType.VIBRATION.createParticle(new PrimitiveParticleOption<>(vibration));

Effect

WARNING: the following section contains some deprecated features for Minecraft versions prior to 1.13.

In older versions of Minecraft, particles were handled differently, and they were named effects. Although some effects remained during the course of the years, many were dropped in favor of particles.

The class from which they can be created is LegacyParticleType which, despite its name, it contains effects present in both Minecraft 1.8 and 1.20+.

Similarly to its Particle counterpart, to create one, a LegacyParticleType#createParticle() method is provided.

The functions to spawn such effects are similar to the ones previously seen in Particle, but they are named with Effect instead of Particle. For example: spawnParticle(Player, Particle, Location, int, double, double, double) becomes spawnEffect(Player, Particle, Location).

Special types of effects

As seen for particles, also effects can have specific options.

Here is a full list of effects allowing options with examples:

• SMOKE, allows specifying the direction of the smoke. Any value is accepted, but, based on the platform in use, these can be wrong;

Particle particle = ParticleType.SMOKE.createParticle(new PrimitiveParticleOption<>("NORTH"));

• POTION_BREAK, requires a PotionParticleOption with a Potion passed. These will NOT be checked, so any invalid name can be specified (and should be treated with caution).

Particle particle = ParticleType.POTION_BREAK.createParticle(new PotionParticleOption(new Potion("strength", 2, true, false)));

• VILLAGER_PLANT_GROW, allows specifying the number of particles;

Particle particle = ParticleType.VILLAGER_PLANT_GROW.createParticle(new PrimitiveParticleOption<>(15));

• ITEM_BREAK, allows specifying the material (id) of the item;

Particle particle = ParticleType.ITEM_BREAK.createParticle(new PrimitiveParticleOption<>("DIAMOND_SWORD"));

• TILE_BREAK, requires a MaterialDataOption, specifying either the material and its data in byte, or both in the format <material>[<data>]. WARNING: this option is deprecated for Minecraft 1.13+.

Particle particle = ParticleType.TILE_BREAK.createParticle(new MaterialDataOption("oak_log[1]"));

• TILE_DUST, requires a MaterialDataOption, specifying either the material and its data in byte, or both in the format <material>[<data>] WARNING: this option is deprecated for Minecraft 1.13+.

Particle particle = ParticleType.TILE_DUST.createParticle(new MaterialDataOption("oak_log[1]"));

• COMPOSTER_FILL_ATTEMPT, allows specifying if the attempt was successful or not.

Particle particle = ParticleType.COMPOSTER_FILL_ATTEMPT.createParticle(new PrimitiveParticleOption<>(true));

• BONE_MEAL_USE, allows specifying the number of particles.

Particle particle = ParticleType.BONE_MEAL_USE.createParticle(new PrimitiveParticleOption<>(7));

• ELECTRIC_SPARK, allows specifying the axis of the particle. This can either be X, Y or Z.

Particle particle = ParticleType.ELECTRIC_SPARK.createParticle(new PrimitiveParticleOption<>("X"));

• INSTANT_POTION_BREAK, requires a ColorParticleOption with a Color, either with Color#fromARGB(String) or by one of the default values: WHITE, SILVER, GRAY, BLACK, RED, MAROON, YELLOW, OLIVE, GREEN, AQUA, TEAL, BLUE, NAVY, FUCHSIA, PURPLE, ORANGE.

Particle particle = ParticleType.INSTANT_POTION_BREAK.createParticle(new ColorParticleOption(Color.PURPLE));