diff --git a/docs/paper/dev/README.md b/docs/paper/dev/README.md index f75f79230..fdafd5fef 100644 --- a/docs/paper/dev/README.md +++ b/docs/paper/dev/README.md @@ -4,7 +4,7 @@ import { useCurrentSidebarCategory } from "@docusaurus/theme-common"; # Development Guide Welcome to the Paper Development Guide! This guide includes information and tutorials for developers -to create and expand on Paper plugins. +on how to create and expand on Paper plugins. --- diff --git a/docs/paper/dev/event-api/custom-events.md b/docs/paper/dev/event-api/custom-events.md index 6a2162b8f..95da34f3c 100644 --- a/docs/paper/dev/event-api/custom-events.md +++ b/docs/paper/dev/event-api/custom-events.md @@ -5,11 +5,12 @@ slug: /dev/custom-events # Custom Events Creating custom events is a great way to add functionality to your plugin. -This will allow for other people to listen for your custom events and add functionality to your plugin. +This will allow other plugins to listen to your custom events and add functionality to your plugin. ## Creating a custom event -To create a custom event, you need to create a class that extends `Event`. Each event has a `HandlerList` that contains all the listeners that are listening for that event. +To create a custom event, you need to create a class that extends `Event`. Each event requires a `HandlerList` that will contain all the listeners that are listening to that event. The only exception to this requirement is when you have an event class that cannot be fired, but serves as a parent for other events instead. +An example of this is the BlockPistonEvent, which cannot be listened to directly. This list is used to call the listeners when the event is called. @@ -78,7 +79,7 @@ public class ExamplePlugin extends JavaPlugin { // ... public void callCoolPaperEvent() { - PaperIsCoolEvent coolEvent = new PaperIsCoolEvent(Component.text("Paper is cool!")) + PaperIsCoolEvent coolEvent = new PaperIsCoolEvent(Component.text("Paper is cool!")); coolEvent.callEvent(); // Plugins could have changed the message from inside their listeners here. So we need to get the message again. // This event structure allows for other plugins to change the message to their taste. @@ -121,11 +122,28 @@ public class ExamplePlugin extends JavaPlugin { // ... public void callCoolPaperEvent() { - PaperIsCoolEvent coolEvent = new PaperIsCoolEvent(Component.text("Paper is cool!")) + PaperIsCoolEvent coolEvent = new PaperIsCoolEvent(Component.text("Paper is cool!")); coolEvent.callEvent(); if (!coolEvent.isCancelled()) { Bukkit.broadcast(coolEvent.getMessage()); } } } -``` \ No newline at end of file +``` + +When an event is cancellable, `Event#callEvent` will return false if the event was cancelled. This allows you to directly use `callEvent` +in your if statement, instead of having to check `Cancellable#isCancelled` manually. + +```java title="ExamplePlugin.java" +public class ExamplePlugin extends JavaPlugin { + + // ... + + public void callCoolPaperEvent() { + PaperIsCoolEvent coolEvent = new PaperIsCoolEvent(Component.text("Paper is cool!")); + if (coolEvent.callEvent()) { // Directly get the output from callEvent + Bukkit.broadcast(coolEvent.getMessage()); + } + } +} +``` diff --git a/docs/paper/dev/event-api/event-listeners.md b/docs/paper/dev/event-api/event-listeners.md index 3f8711a60..28c3312e8 100644 --- a/docs/paper/dev/event-api/event-listeners.md +++ b/docs/paper/dev/event-api/event-listeners.md @@ -26,8 +26,8 @@ This method can be named anything you want, but it is recommended to name it som ## The listener method -The method body does not need to return any data, for this reason use `void` as the return type. -Listeners take in a single parameter, which is the event that is being listened for. +The method body does not need to return any data, for this reason, use void as the return type. +Listeners take in a single parameter, which is the event that is being listened to. ```java title="ExampleListener.java" public class ExampleListener implements Listener { @@ -41,9 +41,11 @@ public class ExampleListener implements Listener { :::note Events -There is no list of events that can be listened for, however take a look +There is no list of events that can be listened to, however take a look [here](https://jd.papermc.io/paper/1.19/org/bukkit/event/Event.html) to see all events that extend `Event`. +An event can only be listened to if it has a static `getHandlerList` method. + ::: ## Registering the listener @@ -130,5 +132,3 @@ public class ExampleListener implements Listener { } } ``` - - diff --git a/docs/paper/dev/event-api/handler-lists.md b/docs/paper/dev/event-api/handler-lists.md index 086f57970..1f9bd0ba4 100644 --- a/docs/paper/dev/event-api/handler-lists.md +++ b/docs/paper/dev/event-api/handler-lists.md @@ -4,7 +4,7 @@ slug: /dev/handler-lists # Handler Lists -Every `Event` has a `HandlerList` that contains all the listeners that are listening for that event. +Every `Event` that can be listened to has a `HandlerList` containing all the listeners that are listening to that event. This list is used to call the listeners when the event is called. ## Getting the handler list for an event diff --git a/docs/paper/dev/getting-started/README.md b/docs/paper/dev/getting-started/README.md index a1201ace3..2acd1a5de 100644 --- a/docs/paper/dev/getting-started/README.md +++ b/docs/paper/dev/getting-started/README.md @@ -3,7 +3,7 @@ import { useCurrentSidebarCategory } from "@docusaurus/theme-common"; # Development Guide -Welcome to the Paper Development Guide! This guide includes information and tutorials for +Welcome to the Paper Development Guide! This guide includes information and tutorials on how to start developing plugins for Paper. --- diff --git a/docs/paper/dev/getting-started/plugin-yml.md b/docs/paper/dev/getting-started/plugin-yml.md index 55b3eb9b1..f80ef8a03 100644 --- a/docs/paper/dev/getting-started/plugin-yml.md +++ b/docs/paper/dev/getting-started/plugin-yml.md @@ -194,7 +194,3 @@ A list of plugins that your plugin should be loaded __before__. They are specifi This is useful if you want to load your plugin before another plugin for the other plugin to use your plugin's API. - `loadbefore: [Vault, FactionsUUID]` - - - - diff --git a/docs/paper/dev/getting-started/project-setup.md b/docs/paper/dev/getting-started/project-setup.md index 057f059da..2ad9051d5 100644 --- a/docs/paper/dev/getting-started/project-setup.md +++ b/docs/paper/dev/getting-started/project-setup.md @@ -5,9 +5,9 @@ slug: /dev/project-setup # Paper Project Setup As the Paper team primarily uses [IntelliJ IDEA](https://www.jetbrains.com/idea/), this guide will be focused on that IDE. -However, the steps below should be applicable to other IDEs as well, with some minor changes. +However, the steps below should apply to other IDEs as well, with some minor changes. -The paper team uses [Gradle](https://gradle.org/) as its build system, and it's tools are implemented for Gradle. +The Paper team uses [Gradle](https://gradle.org/) as its build system, and its tools are implemented for Gradle. Most of the code below can be altered to work with other build systems, such as Maven, but this guide will only cover Gradle. Follow the guide [here](https://docs.gradle.org/current/userguide/migrating_from_maven.html) to learn how to migrate from Maven to Gradle. @@ -43,7 +43,7 @@ java { :::note -If your project creates a `src` directory automatically, you can skip this step. +If your IDE creates a `src` directory automatically, you can skip this step. ::: @@ -95,7 +95,7 @@ When [naming](https://docs.oracle.com/javase/tutorial/java/package/namingpkgs.ht your package name should be `io.papermc`. If you do not have a domain name, you could use something like your GitHub username. If you were Linus Torvalds, your package would be `io.github.torvalds`. -This is all then followed by the name of your project. +This is then followed by the name of your project. For example, if your project was called `ExamplePlugin`, your package would be `io.github.torvalds.exampleplugin`. This allows for a unique package name for every plugin.