+ * Listeners with lower priority are called first + * will listeners with higher priority are called last. + *
+ * Listeners are called in following order: + * {@link #LOWEST} -> {@link #LOW} -> {@link #NORMAL} -> {@link #HIGH} -> {@link #HIGHEST} -> {@link #MONITOR} */ public enum EventPriority { /** - * Event call is of very low importance and should be ran first, to allow + * Event call is of very low importance and should be run first, to allow * other plugins to further customise the outcome */ LOWEST(0), @@ -15,7 +21,7 @@ public enum EventPriority { */ LOW(1), /** - * Event call is neither important nor unimportant, and may be ran + * Event call is neither important nor unimportant, and may be run * normally */ NORMAL(2), diff --git a/paper-api/src/main/java/org/bukkit/event/block/BlockDamageAbortEvent.java b/paper-api/src/main/java/org/bukkit/event/block/BlockDamageAbortEvent.java index 7d49b8621..edc204b50 100644 --- a/paper-api/src/main/java/org/bukkit/event/block/BlockDamageAbortEvent.java +++ b/paper-api/src/main/java/org/bukkit/event/block/BlockDamageAbortEvent.java @@ -8,6 +8,7 @@ import org.jetbrains.annotations.NotNull; /** * Called when a player stops damaging a Block. + * @see BlockDamageEvent */ public class BlockDamageAbortEvent extends BlockEvent { diff --git a/paper-api/src/main/java/org/bukkit/event/block/BlockDamageEvent.java b/paper-api/src/main/java/org/bukkit/event/block/BlockDamageEvent.java index f70871e1a..cd04a0bd9 100644 --- a/paper-api/src/main/java/org/bukkit/event/block/BlockDamageEvent.java +++ b/paper-api/src/main/java/org/bukkit/event/block/BlockDamageEvent.java @@ -11,6 +11,7 @@ import org.jetbrains.annotations.NotNull; * Called when a block is damaged by a player. *
* If a Block Damage event is cancelled, the block will not be damaged. + * @see BlockDamageAbortEvent */ public class BlockDamageEvent extends BlockEvent implements Cancellable { private static final HandlerList handlers = new HandlerList(); diff --git a/paper-api/src/main/java/org/bukkit/event/entity/EntityToggleGlideEvent.java b/paper-api/src/main/java/org/bukkit/event/entity/EntityToggleGlideEvent.java index 1478cdbb4..de24f3f61 100644 --- a/paper-api/src/main/java/org/bukkit/event/entity/EntityToggleGlideEvent.java +++ b/paper-api/src/main/java/org/bukkit/event/entity/EntityToggleGlideEvent.java @@ -35,6 +35,12 @@ public class EntityToggleGlideEvent extends EntityEvent implements Cancellable { this.cancel = cancel; } + /** + * Returns true if the entity is now gliding or + * false if the entity stops gliding. + * + * @return new gliding state + */ public boolean isGliding() { return isGliding; } diff --git a/paper-api/src/main/java/org/bukkit/event/entity/EntityToggleSwimEvent.java b/paper-api/src/main/java/org/bukkit/event/entity/EntityToggleSwimEvent.java index 7b3fc4cad..e1123295b 100644 --- a/paper-api/src/main/java/org/bukkit/event/entity/EntityToggleSwimEvent.java +++ b/paper-api/src/main/java/org/bukkit/event/entity/EntityToggleSwimEvent.java @@ -29,6 +29,12 @@ public class EntityToggleSwimEvent extends EntityEvent implements Cancellable { this.cancel = cancel; } + /** + * Returns true if the entity is now swims or + * false if the entity stops swimming. + * + * @return new swimming state + */ public boolean isSwimming() { return isSwimming; } diff --git a/paper-api/src/main/java/org/bukkit/event/player/PlayerKickEvent.java b/paper-api/src/main/java/org/bukkit/event/player/PlayerKickEvent.java index 14c337f15..2f6ca4233 100644 --- a/paper-api/src/main/java/org/bukkit/event/player/PlayerKickEvent.java +++ b/paper-api/src/main/java/org/bukkit/event/player/PlayerKickEvent.java @@ -12,7 +12,7 @@ public class PlayerKickEvent extends PlayerEvent implements Cancellable { private static final HandlerList handlers = new HandlerList(); private String leaveMessage; private String kickReason; - private Boolean cancel; + private boolean cancel; public PlayerKickEvent(@NotNull final Player playerKicked, @NotNull final String kickReason, @NotNull final String leaveMessage) { super(playerKicked); diff --git a/paper-api/src/main/java/org/bukkit/event/world/ChunkLoadEvent.java b/paper-api/src/main/java/org/bukkit/event/world/ChunkLoadEvent.java index ae8ef3392..7873d387f 100644 --- a/paper-api/src/main/java/org/bukkit/event/world/ChunkLoadEvent.java +++ b/paper-api/src/main/java/org/bukkit/event/world/ChunkLoadEvent.java @@ -2,6 +2,7 @@ package org.bukkit.event.world; import org.bukkit.Chunk; import org.bukkit.event.HandlerList; +import org.bukkit.generator.BlockPopulator; import org.jetbrains.annotations.NotNull; /** @@ -19,7 +20,8 @@ public class ChunkLoadEvent extends ChunkEvent { /** * Gets if this chunk was newly created or not. *
- * Note that if this chunk is new, it will not be populated at this time. + * Note: Do not use this to generated blocks in a newly generated chunk. + * Use a {@link BlockPopulator} instead. * * @return true if the chunk is new, otherwise false */ diff --git a/paper-api/src/main/java/org/bukkit/event/world/ChunkPopulateEvent.java b/paper-api/src/main/java/org/bukkit/event/world/ChunkPopulateEvent.java index 46d91403c..7b323c057 100644 --- a/paper-api/src/main/java/org/bukkit/event/world/ChunkPopulateEvent.java +++ b/paper-api/src/main/java/org/bukkit/event/world/ChunkPopulateEvent.java @@ -6,10 +6,10 @@ import org.bukkit.generator.BlockPopulator; import org.jetbrains.annotations.NotNull; /** - * Thrown when a new chunk has finished being populated. + * Thrown when a newly generated chunk has finished being populated. *
- * If your intent is to populate the chunk using this event, please see {@link - * BlockPopulator} + * Note: Do not use this to generated blocks in a newly generated chunk. + * Use a {@link BlockPopulator} instead. */ public class ChunkPopulateEvent extends ChunkEvent { private static final HandlerList handlers = new HandlerList(); diff --git a/paper-api/src/main/java/org/bukkit/event/world/WorldInitEvent.java b/paper-api/src/main/java/org/bukkit/event/world/WorldInitEvent.java index 8b521deda..2cb1ed0cc 100644 --- a/paper-api/src/main/java/org/bukkit/event/world/WorldInitEvent.java +++ b/paper-api/src/main/java/org/bukkit/event/world/WorldInitEvent.java @@ -5,7 +5,10 @@ import org.bukkit.event.HandlerList; import org.jetbrains.annotations.NotNull; /** - * Called when a World is initializing + * Called when a World is initializing. + *
+ * To get every world it is recommended to add following to the plugin.yml. + *
load: STARTUP*/ public class WorldInitEvent extends WorldEvent { private static final HandlerList handlers = new HandlerList(); diff --git a/paper-api/src/main/java/org/bukkit/generator/BlockPopulator.java b/paper-api/src/main/java/org/bukkit/generator/BlockPopulator.java index ea3efd92c..4704ea919 100644 --- a/paper-api/src/main/java/org/bukkit/generator/BlockPopulator.java +++ b/paper-api/src/main/java/org/bukkit/generator/BlockPopulator.java @@ -3,6 +3,7 @@ package org.bukkit.generator; import java.util.Random; import org.bukkit.Chunk; import org.bukkit.World; +import org.bukkit.event.world.WorldInitEvent; import org.jetbrains.annotations.NotNull; /** @@ -10,6 +11,13 @@ import org.jetbrains.annotations.NotNull; *
* For example, generating glowstone inside the nether or generating dungeons * full of treasure + *
+ * A BlockPopulator can be used in combination with a custom {@link ChunkGenerator} + * by returning it in the method {@link ChunkGenerator#getDefaultPopulators(World)} + * or by adding it manually to the worlds populator list returned by {@link World#getPopulators()}. + *
+ * When adding a BlockPopulator manually to a world it is recommended to do so during + * the {@link WorldInitEvent}. */ public abstract class BlockPopulator { @@ -54,10 +62,10 @@ public abstract class BlockPopulator { * * @param worldInfo The world info of the world to generate in * @param random The random generator to use - * @param x The X-coordinate of the chunk - * @param z The Z-coordinate of the chunk + * @param chunkX The X-coordinate of the chunk + * @param chunkZ The Z-coordinate of the chunk * @param limitedRegion The chunk region to populate */ - public void populate(@NotNull WorldInfo worldInfo, @NotNull Random random, int x, int z, @NotNull LimitedRegion limitedRegion) { + public void populate(@NotNull WorldInfo worldInfo, @NotNull Random random, int chunkX, int chunkZ, @NotNull LimitedRegion limitedRegion) { } } diff --git a/paper-api/src/main/java/org/bukkit/generator/ChunkGenerator.java b/paper-api/src/main/java/org/bukkit/generator/ChunkGenerator.java index d14d3851a..4c9a64ace 100644 --- a/paper-api/src/main/java/org/bukkit/generator/ChunkGenerator.java +++ b/paper-api/src/main/java/org/bukkit/generator/ChunkGenerator.java @@ -73,11 +73,11 @@ public abstract class ChunkGenerator { * * @param worldInfo The world info of the world this chunk will be used for * @param random The random generator to use - * @param x The X-coordinate of the chunk - * @param z The Z-coordinate of the chunk + * @param chunkX The X-coordinate of the chunk + * @param chunkZ The Z-coordinate of the chunk * @param chunkData To modify */ - public void generateNoise(@NotNull WorldInfo worldInfo, @NotNull Random random, int x, int z, @NotNull ChunkData chunkData) { + public void generateNoise(@NotNull WorldInfo worldInfo, @NotNull Random random, int chunkX, int chunkZ, @NotNull ChunkData chunkData) { } /** @@ -100,11 +100,11 @@ public abstract class ChunkGenerator { * * @param worldInfo The world info of the world this chunk will be used for * @param random The random generator to use - * @param x The X-coordinate of the chunk - * @param z The Z-coordinate of the chunk + * @param chunkX The X-coordinate of the chunk + * @param chunkZ The Z-coordinate of the chunk * @param chunkData To modify */ - public void generateSurface(@NotNull WorldInfo worldInfo, @NotNull Random random, int x, int z, @NotNull ChunkData chunkData) { + public void generateSurface(@NotNull WorldInfo worldInfo, @NotNull Random random, int chunkX, int chunkZ, @NotNull ChunkData chunkData) { } /** @@ -127,11 +127,11 @@ public abstract class ChunkGenerator { * * @param worldInfo The world info of the world this chunk will be used for * @param random The random generator to use - * @param x The X-coordinate of the chunk - * @param z The Z-coordinate of the chunk + * @param chunkX The X-coordinate of the chunk + * @param chunkZ The Z-coordinate of the chunk * @param chunkData To modify */ - public void generateBedrock(@NotNull WorldInfo worldInfo, @NotNull Random random, int x, int z, @NotNull ChunkData chunkData) { + public void generateBedrock(@NotNull WorldInfo worldInfo, @NotNull Random random, int chunkX, int chunkZ, @NotNull ChunkData chunkData) { } /** @@ -154,11 +154,11 @@ public abstract class ChunkGenerator { * * @param worldInfo The world info of the world this chunk will be used for * @param random The random generator to use - * @param x The X-coordinate of the chunk - * @param z The Z-coordinate of the chunk + * @param chunkX The X-coordinate of the chunk + * @param chunkZ The Z-coordinate of the chunk * @param chunkData To modify */ - public void generateCaves(@NotNull WorldInfo worldInfo, @NotNull Random random, int x, int z, @NotNull ChunkData chunkData) { + public void generateCaves(@NotNull WorldInfo worldInfo, @NotNull Random random, int chunkX, int chunkZ, @NotNull ChunkData chunkData) { } /** @@ -289,12 +289,12 @@ public abstract class ChunkGenerator { * generator * @return ChunkData containing the types for each block created by this * generator - * @deprecated The generation is now split up + * @deprecated The generation is now split up and the new methods should be used, see {@link ChunkGenerator} */ @NotNull @Deprecated public ChunkData generateChunkData(@NotNull World world, @NotNull Random random, int x, int z, @NotNull BiomeGrid biome) { - throw new UnsupportedOperationException("Custom generator " + getClass().getName() + " is missing required method generateChunkData"); + throw new UnsupportedOperationException("Not implemented, no longer needed"); } /**