Configuration
Welcome to TeleportEffects Wiki!
In this section we will look over every option provided by the config.yml file
and how to properly use them.
Before continuing, I will have to actually describe how the plugin works and how the various particle effects are created.
Do note though, that the majority of these parameters are "stats for nerds", meaning that the plugin will work without the need of configuring or editing these values.
For many people, duration, teleport-effect, particle-type-stage1,
particle-type-stage2, particle-type-stage3, particle-type-stage4 and teleporting-messages
will be more than enough to customize the user experience.
Now that we have that out of the way, let's begin!
Every teleport is composed of four stages of particles spawning.
Each one of them is characterized by some of the parameters of the config.yml
and changing these, will change the stages themselves.
Let's look over on how they are affected and from what.
I tried my best to create useful visual representations, but as you can see, my Paint skills are not up to standards.
I hope you can understand at least something, but if you do not, try changing every value singularly and see how it affects the stages.
The Stage1 is the first stage that appears. This stage lasts for 1/3 of the total duration,
so, by default, 1 seconds.
As you can see, many options interest this stage:
-
particle-type-stage1: the type of the particle (in this example
GLOW); -
points: the number of points to spawn (in this example
2); -
initial-offset: the offset from which start spawning the particles (in this example
90); -
rotation-angle: the speed at which the particles should rotate with each iteration (in this example
20). Basically, if a particle starts from90°, in its next iteration it will be at110°; - height-increment: the distance in blocks between the particles of one iteration and the next one;
-
initial-distance: the initial distance from which start spawning particles (in this example
0.5blocks); -
final-distance: the final distance at which the particles should arrive (in this example
0.1blocks).
Summing up, X points will be equally divided along a circle that will be translated by initial-offset degrees starting from the position of the player eyes and of radius initial-distance. Then, every tick (duration between an iteration and another), those particles will be rotated by rotation-angle, their height will be +height-increment blocks from their previous value, and they will be closer to the player. After 1/3 duration seconds, the particles will have reached final-distance, they will stop spawning and Stage2 will begin.
Stage2 will be the followup to Stage1, starting off right from where the first stage finished.
This stage lasts for 2/3 of the total duration,
so, by default, 2 seconds.
This stage uses fewer parameters to function, but they are equally important:
-
particle-type-stage2: the type of the particle (in this example
GLOW); -
points: the number of points to spawn (in this example
2); -
initial-offset: the offset from which start spawning the particles (in this example
90); - height-increment: the distance in blocks between the particles of one iteration and the next one;
-
distance: the distance from the player at which the particles will be spawned (in this example
0.1blocks).
So, this stage takes directly from Stage1 the last position of the particles and from there it starts spawning particles both above and below that level, at height-increment blocks of distance from the previous iteration. All the other options are inherited and continued from the first stage, but do note that in this case final-distance will actually be the initial and final distance from the player.
While the previous two stages are sequential, the third stage happens simultaneously as the Stage2.
This means that it starts after 1/3 of the total duration, and it has the same duration as the second stage.
However, Stage3 spawns particles not around the player, as previously seen, but at the teleport destination.
Let's look over the options that affect the particles of this stage:
-
particle-type-stage1: the type of the particle (in this example
SMOKE_NORMAL); -
distance-angle: the equivalent to Stage1 points, this value represents the distance in degrees between one particle and another (in this example
90). Of course, incrementing the angle will decrement the number of particles (for example90°corresponds to360° / 90° = 4points); - height-decrement: the distance in blocks between the particles of one iteration and the next one;
-
initial-distance: the initial distance from which start spawning particles (in this example
0.6blocks); -
final-distance: the final distance at which the particles should arrive (in this example
0.01blocks).
In conclusion, the Stage3 starts spawning particles 2.5 blocks higher than the final destination in a circular radius.
It will spawn 360° / distance-angle points at a radius of initial-distance blocks.
Then, these particles will descent by height-decrement blocks every tick (duration between an iteration and another) until they reach the final-distance distance in blocks from the destination location.
At that point, Stage4 will commence.
Stage4 is the last and less important stage. It is directly linked to Stage3 ending, but it happens after the teleport happened (so past the duration seconds).
NOTE: in this example, Stage4 parameters are exaggerated to better show their use.
-
particle-type-stage2: the type of the particle (in this example
END_ROD); -
distance-angle: the equivalent to Stage1 points, this value represents the distance in degrees between one particle and another (in this example
90). Of course, incrementing the angle will decrement the number of particles (for example90°corresponds to360° / 90° = 4points); - delta-distance: the distance from one particle and another, calculated using the following formula:
([to.initial-distance] - [to.final-distance]) / (to.stage4-duration) / 0.05
-
initial-distance: the distance from the destination point at which the particles will be spawned (in this example
0.01blocks); -
stage4-duration: the duration after which the stage4 should be stopped (in this example
1.0).
So, Stage4 particles will be spawned at the player's feet in a circular radius, similar to Stage3 particles, using the same numbers of points as the previous stage. They will move in a straight line until stage4-duration seconds will have passed, then they will be removed.
The following are all the parameters of the config.yml file each given a description and its default value. If you did not already, I encourage you to read above to understand how to use these options at their best.
How much the teleport should require in seconds. After %duration% seconds have passed, if the player has not moved, they will be teleported.
The effect that should be applied to the player during the teleportation. You can check out the Spigot official docs for a list of available effects, but do keep in mind that not all of these will work on earlier versions.
whitelisted-teleport-causes (Default Value: [CHORUS_FRUIT, DISMOUNT, END_GATEWAY, END_PORTAL, ENDER_PEARL, MOUNT, NETHER_PORTAL, SPECTATE, UNKNOWN])
If you are a plugin developer this is going to be easy for you, but in synthesis the plugin intercepts every teleport and temporarily blocks it (cancels it) to start its effects. Since there are many entities that cause a teleport in Minecraft, this kind of behaviour created bugs and problems of all kind. Therefore, this option has been created. I advise you to not change anything in here, unless you have previous experience with TeleportCauses and know what you are doing.
Since version 3.0, TeleportEffects offers a whole new way of sending messages to the player. When a teleport occurs, four types of messages are now available to be sent: messages, titles, boss-bar and action-bar
These are strictly string messages that are sent to the player in chat.
If you set the every-second option to true, they will be sent every second during the teleport.
To disable one (or both) of them, just leave them blank ("").
This section allows to send titles and/or subtitles to the player.
If you set the every-second option to true, they will be sent every second during the teleport.
To disable one (or both) of them, just leave them blank ("").
When this option is enabled, during a teleport a player will receive a BossBar that acts as a countdown for the teleport.
If a player moves, they will receive another BossBar (specified in teleport-cancelled) with the duration specified in teleport-cancelled.duration.
You can customize these BossBars as you like, but do keep in mind that in 1.8
colors,
styles and
flags will NOT be available.
To disable one (or both) of them, just set the title to blank ("").
Sends a "progress" ActionBar to the player during the teleport.
Basically, the ActionBar acts like a progress bar (or countdown if reverse is set to true) coordinated with the teleport times.
You can specify any length you want and change both the progress-on and progress-off characters,
as well as the progress-cancelled for when the player moves before the teleport.
To disable, you can just set the length to 0 or all the progresses as blank ("");
In this section you can specify which sounds should be played in certain moments of the teleport.
Note that the sounds provided in Bukkit Sounds
are NOT cross-compatible among versions, therefore you will need to find the correct sound for the version you are working with!
The particle effect to be played at Stage1. You can check out the Spigot official docs for a list of available particles, but do keep in mind that not all of these will work on earlier versions (if you are on 1.13 or earlier you will need to use this page).
The particle effect to be played at Stage2. You can check out the Spigot official docs for a list of available particles, but do keep in mind that not all of these will work on earlier versions (if you are on 1.13 or earlier you will need to use this page).
The amount of points to spawn during Stage1.
The initial offset from which start the particles rotation and ascension expressed in degrees. Do keep in mind that 0 means in front of the player.
The speed at which the particles should rotate with each iteration expressed in degrees.
The distance between the particles of one iteration and another in blocks. A low value is advised to prevent particles from skyrocketing into air.
The distance in blocks from which the particles should start to appear.
The distance in blocks at which the particles should arrive before disappearing.
If this option is set to false, previous particles will be respawned in each iteration of Stage1, allowing to create cylinders or walls "of particles".
If this option is set to false, previous particles will be respawned in each iteration of Stage2, allowing to create cylinders or walls "of particles".
The particle effect to be played at Stage3. You can check out the Spigot official docs for a list of available particles, but do keep in mind that not all of these will work on earlier versions (if you are on 1.13 or earlier you will need to use this page).
The particle effect to be played at Stage4. You can check out the Spigot official docs for a list of available particles, but do keep in mind that not all of these will work on earlier versions (if you are on 1.13 or earlier you will need to use this page).
The distance between one particle and another expressed in degrees. Higher values mean lower particles.
The distance between the particles of one iteration and another in blocks. A low value is advised to prevent particles from going too deep underground.
The distance in blocks from which the particles should start to appear.
The distance in blocks at which the particles should arrive before disappearing.
The duration of Stage4 expressed in seconds.