Overview of Plugins

config/sidebar.paper.ts

@@ -100,9 +100,9 @@ const paper: SidebarsConfig = {
           },
           items: [
             "dev/getting-started/project-setup",
-            "dev/getting-started/userdev",
             "dev/getting-started/plugin-yml",
             "dev/getting-started/paper-plugins",
+            "dev/getting-started/userdev",
           ],
         },
         {
@@ -133,13 +133,14 @@ const paper: SidebarsConfig = {
                 "dev/api/component-api/i18n",
               ]
             },
-            "dev/api/roadmap",
+            "dev/api/how-do-plugins-work",
             "dev/api/pdc",
             "dev/api/custom-inventory-holder",
             "dev/api/scheduler",
             "dev/api/plugin-messaging",
             "dev/api/plugin-configs",
             "dev/api/folia-support",
+            "dev/api/roadmap",
           ],
         },
         {

docs/paper/admin/getting-started/getting-started.md

@@ -20,20 +20,6 @@ With the release of Minecraft 1.18, Paper now requires **Java 17** to run. We re
 | 1.16.5         | Java 16                  |
 | 1.17.1-1.18.1+ | Java 21                  |
 
-## Migrating to Paper
-
-### From Vanilla
-
-Migrating from Vanilla is easy, but there are some differences, namely in world saves. Paper (and
-CraftBukkit and Spigot) separate out each dimension of a world (nether, the end, etc.) into separate
-world folders.
-
-Paper will handle this conversion for you automatically. No additional consideration is required.
-
-### From Craftbukkit or Spigot
-
-Paper is a drop in replacement for both CraftBukkit and Spigot, you don't need to make any changes.
-
 ## Downloading Paper
 
 Paper provides runnable server jars directly from our
@@ -62,3 +48,17 @@ To configure your server, see the [Global Configuration](../reference/configurat
 ## Updating The Server
 
 Updating Paper is simple! See our [Update Tutorial](../how-to/update.md) for more information.
+
+## Migrating to Paper
+
+### From Vanilla
+
+Migrating from Vanilla is easy, but there are some differences, namely in world saves. Paper (and
+CraftBukkit and Spigot) separate out each dimension of a world (nether, the end, etc.) into separate
+world folders.
+
+Paper will handle this conversion for you automatically. No additional consideration is required.
+
+### From Craftbukkit or Spigot
+
+Paper is a drop in replacement for both CraftBukkit and Spigot, you don't need to make any changes.

docs/paper/admin/how-to/aikars-flags.md

@@ -10,6 +10,9 @@ description: Aikar's flags are a set of JVM flags designed to improve the perfor
 Use these flags exactly, only changing Xmx and Xms. These flags work and scale accordingly to any
 size of memory, even 500MB but modern Minecraft versions will not do well with such low memory.
 
+For an automated script to generate these flags for you, see
+[Our Script Generator](/misc/tools/start-script-gen).
+
 ```bash
 java -Xms10G -Xmx10G -XX:+UseG1GC -XX:+ParallelRefProcEnabled -XX:MaxGCPauseMillis=200 -XX:+UnlockExperimentalVMOptions -XX:+DisableExplicitGC -XX:+AlwaysPreTouch -XX:G1NewSizePercent=30 -XX:G1MaxNewSizePercent=40 -XX:G1HeapRegionSize=8M -XX:G1ReservePercent=20 -XX:G1HeapWastePercent=5 -XX:G1MixedGCCountTarget=4 -XX:InitiatingHeapOccupancyPercent=15 -XX:G1MixedGCLiveThresholdPercent=90 -XX:G1RSetUpdatingPauseTimePercent=5 -XX:SurvivorRatio=32 -XX:+PerfDisableSharedMem -XX:MaxTenuringThreshold=1 -Dusing.aikars.flags=https://mcflags.emc.gs -Daikars.new.flags=true -jar paper.jar --nogui
 ```

docs/paper/dev/api/how-do-plugins-work.md

@@ -0,0 +1,113 @@
+---
+slug: /dev/how-do-plugins-work
+description: How plugins work in Paper.
+---
+
+# How Plugins Work
+
+## Introduction
+
+Plugins are a way to extend the functionality of a Minecraft server. They are written in JVM-based languages such as 
+Java, Kotlin, Groovy or Scala. Plugins are loaded from the `plugins` folder in the server directory. Plugins will be 
+loaded from a `.jar` file.  Each plugin has a main class that is specified in the plugin's `plugin.yml` file. This
+class must extend JavaPlugin, and is the entry point for the plugin and is where the plugin's lifecycle methods are 
+defined.
+
+:::warning
+
+We do not recommend writing code inside your main class's constructor as there are no guarantees about what
+API is available at that point. Instead, you should use the `onLoad` method to initialize your plugin. Also,
+do not call your plugin's constructor directly. This will cause issues with your plugin.
+
+:::
+
+## Plugin Lifecycle
+
+Plugins are loaded and unloaded at runtime. When a plugin is loaded, it is initialized and enabled. When a plugin is 
+unloaded, it is disabled and finalized.
+
+### Initialization
+
+When a plugin is loaded, it is initialized. This means that the plugin is loaded into memory and its `onLoad` 
+method is called. This method is used to initialize the plugin and set up any resources that it needs. Most of the
+Bukkit API is not available at this point, so it is not safe to interact with it.
+
+### Enabling
+
+When a plugin is enabled, its `onEnable` method is called. This method is used to set up any resources that the plugin 
+needs to run. This method is called when the plugin is initialized but before the server has started ticking, so it is 
+safe to register event listeners and other resources that the plugin needs to run, however often not safe to interact 
+with a lot of APIs.
+
+This is when you can also open database connections, start threads, and other things that are not safe to do in the
+`onLoad` method.
+
+### Disabling
+
+When a plugin is disabled, its `onDisable` method is called. This method is used to clean up any resources that the 
+plugin has allocated. This method is called before all plugins are unloaded, and is meant for any cleanup that needs to
+be done before the plugin is unloaded. This may include saving data to disk or closing connections to databases.
+
+## Event Listeners
+
+Events are a way for plugins to listen to things that happen in the server and run code when they are fired. For 
+example, the `PlayerJoinEvent` is fired when a player joins the server. This is a more performant way to run code when 
+something happens, as opposed to constantly checking. See our [event listener page](/paper/dev/event-listeners) for more.
+
+Some events are cancellable. This means that when the event is fired, it can be cancelled which negates or stops the 
+effect of the event. For example, the `PlayerMoveEvent` is cancellable. This means that when it is cancelled, the player 
+will not move. This is useful for things like anti-cheat, where you want to cancel the event if the player is moving too fast.
+
+It is important to think about how "hot" an event is when writing event listeners. A "hot" event is an event that is fired
+very often. For example, the `PlayerMoveEvent` is fired every time a player moves. This means that if you have a lot of
+expensive code in your event listener, it will be run every time a player moves. This can cause a lot of lag. It is
+important to keep event listeners as lightweight as possible. One possible way is to quickly check if the event should
+be handled, and if not, return. For example, if you only want to handle the event if the player is moving from one block
+to another, you can check if the player's location has changed blocks. If it hasn't, you can return from the listener.
+
+## Commands
+
+Commands are a way for players, the console, RCON and command blocks to run code on the server. Commands are registered
+by plugins and can be run by command senders. For example, the `/help` command is registered by the server and can be
+run by players. Commands can be run by players by typing them in the chat or by running them from a command block.
+
+Commands can have arguments. For example, the `/give` command takes an argument for the player to give the item to and
+an argument for the item to give. Arguments are separated by spaces. For example, the command `/give Notch diamond` will
+give the player named Notch a diamond. Note here that the arguments are `["Notch", "diamond"]`.
+
+### Permissions
+
+Permissions are a way to control who can run commands and who can listen to events. Permissions 
+are registered by plugins and can be checked by other plugins. Permissions can be granted to players and groups. 
+Permissions have a hierarchical nature. For example, the `paper.command.help` permission is a sub-permission to 
+`paper.command`. This means that if a player has the `paper.command` permission, they will also have the 
+`paper.command.help` permission.
+
+## Configuration
+
+Plugins can have configuration files. These files are used to store data that the plugin needs to run. For example, a
+plugin that adds a new block to the game might have a configuration file that stores the block's ID. Configuration files
+are stored in the `plugins` folder in the server directory. Configuration files are written in YAML. See 
+[here](/paper/dev/plugin-configurations) for more information.
+
+## Scheduling Tasks
+
+Plugins can schedule tasks to run at a later time. This is useful for things like running code after a certain amount
+of time has passed. For example, a plugin might want to run code after 5 seconds. This can be done by scheduling a task
+to run after 100 ticks - one second is 20 ticks during normal operation. It is important to note that tasks might be 
+delayed if the server is lagging. For example, if the server is only running at 10 ticks per second, a task that is 
+scheduled to run after 100 ticks will take 10 seconds.
+
+In Java, typically you could use `Thread.sleep()` to delay the execution of code. However, if the code is running on the main
+thread, this will cause the server to pause for the delay. Instead, you should use the `Scheduler` API to schedule tasks
+to run later. Learn more about the `Scheduler` API [here](/paper/dev/scheduler).
+
+## Components
+
+Since Minecraft 1.7 and the introduction of the `Component` API, plugins can now send messages to players that contain
+rich text. This means that plugins can send messages that contain things like colors, bold text, and clickable links.
+Colors were always possible, but only through the use of legacy color codes.
+
+Paper implements a library called `Adventure` that makes it easy to create and send messages to players. Learn more
+about the `Adventure` API [here](https://docs.advntr.dev/) from their docs or our docs 
+[here](/paper/dev/component-api/introduction).

docs/paper/dev/api/scheduler.md

@@ -22,6 +22,10 @@ In Minecraft there are 20 ticks per second, or one tick every 50 milliseconds. T
 20 times per second. A tick taking more than 50ms to execute is the moment when your server starts to fall behind on 
 its work and lag.
 
+A task that should run after 100 ticks will run after 5 seconds (100 ticks / 20 ticks per second = 5 seconds). However,
+if the server is only running at 10 ticks per second, a task that is scheduled to run after 100 ticks will take 10
+seconds.
+
 ### Converting between human units and Minecraft ticks
 
 Every method of the scheduler that takes a delay or period uses ticks as a unit of time.

docs/paper/dev/getting-started/plugin-yml.mdx

@@ -3,10 +3,10 @@ slug: /dev/plugin-yml
 description: A guide to Bukkit's plugin.yml file.
 ---
 
-# Bukkit Plugin YML
+# Plugin YML
 
-The plugin.yml file is the main configuration file for your plugin. 
-It contains information about your plugin, such as its name, version, and description. 
+The plugin.yml file is the main configuration file for your plugin.
+It contains information about your plugin, such as its name, version, and description.
 It also contains information about the plugin's dependencies, permissions, and commands.
 
 The plugin.yml file is located in the `resources` directory of your project.
@@ -41,14 +41,14 @@ api-version: '%%_MAJ_MC_%%'
 
 :::note
 
-The fields in this section are not in any particular order. 
+The fields in this section are not in any particular order.
 If they have an asterisk (\*) next to them, that means they are required.
 
 :::
 
 ### name*
 
-The name of your plugin. This is what will be displayed in the plugin list and log messages. 
+The name of your plugin. This is what will be displayed in the plugin list and log messages.
 This will be overridden in the logs if the prefix is set.
 - `name: ExamplePlugin`