Add comprehensive plugin integration documentation #81

Copilot · 2026-01-05T07:16:10Z

Plugin Integration Documentation Expansion

Original prompt

This section details on the original issue you should resolve

<issue_title>Expand plugin integration documentation</issue_title>
<issue_description>As a plugin developer, I would appreciate comprehensive documentation on integrating my plugin with Mailboxes. It would be ideal if I could start sending messages to players with little to no friction.</issue_description>

Comments on the Issue (you are @copilot in this section)

Fixes Expand plugin integration documentation #80

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

- Created API.md with full API reference, examples, and best practices - Created QUICKSTART.md for quick 5-minute integration guide - Updated README.md with prominent links to developer documentation Co-authored-by: dmccoystephenson <21204351+dmccoystephenson@users.noreply.github.com>

- Add null checks before instanceof checks for consistency - Fix syntax highlighting for Gradle code blocks - Simplify message checking example to use documented methods - Improve bulk notification example to avoid performance issues with getOfflinePlayers() Co-authored-by: dmccoystephenson <21204351+dmccoystephenson@users.noreply.github.com>

- Fix rate limiting example to use per-player cooldown tracking - Optimize bulk notification to avoid repeated getPlayer() calls - Add clarifying comments for version comparison - Add missing imports for Stream API usage Co-authored-by: dmccoystephenson <21204351+dmccoystephenson@users.noreply.github.com>

Copilot

Pull request overview

This PR adds comprehensive plugin integration documentation for Mailboxes, making it easy for plugin developers to integrate with the Mailboxes API. The documentation addresses issue #80 by providing clear, practical examples and step-by-step guides.

Creates a quick start guide (QUICKSTART.md) for developers to send their first message in 5 minutes
Adds complete API documentation (API.md) with detailed method references, examples, and best practices
Updates README.md with clear links to the new documentation and highlights key features for developers

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 9 comments.

File	Description
README.md	Added "For Plugin Developers" section with links to new documentation and highlighted key API features
QUICKSTART.md	New quick start guide with dependency setup, API access, and practical examples for common use cases
API.md	Comprehensive API reference with detailed method documentation, multiple real-world examples, best practices, and troubleshooting guide

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

QUICKSTART.md

API.md

QUICKSTART.md

API.md

dmccoystephenson · 2026-01-05T07:33:38Z

@copilot address comments

- Add Command, CommandExecutor, CommandSender imports to QUICKSTART.md command example - Fix QUICKSTART.md command example to properly reference plugin instance - Add Location, EventHandler, PlayerDeathEvent imports to event examples - Add ChatColor import to message checking example in API.md - Add Level import to error handling example in API.md - Add Map, HashMap, UUID imports to rate limiting example in API.md - Clarify getTrackedPlayerUUIDs() is a placeholder method in bulk notification example Co-authored-by: dmccoystephenson <21204351+dmccoystephenson@users.noreply.github.com>

- Add M_Mailbox, Message, and ArrayList imports to message checking example - Add Bukkit, Player, List, and UUID imports to bulk notification example Co-authored-by: dmccoystephenson <21204351+dmccoystephenson@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 14 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-01-07T04:55:21Z

API.md

+public class QuestPlugin extends JavaPlugin {
+
+    private MailboxesAPI mailboxesAPI;
+
+    @Override
+    public void onEnable() {
+        setupMailboxesAPI();
+    }
+
+    private void setupMailboxesAPI() {
+        Plugin plugin = getServer().getPluginManager().getPlugin("Mailboxes");
+        if (plugin instanceof Mailboxes) {
+            mailboxesAPI = ((Mailboxes) plugin).getAPI();
+        }
+    }
+
+    public void onQuestComplete(Player player, String questName) {
+        if (mailboxesAPI != null) {
+            String message = String.format(
+                "Congratulations! You've completed the '%s' quest! Your reward has been added to your account.",
+                questName
+            );
+
+            mailboxesAPI.sendPluginMessageToPlayer("QuestPlugin", player, message);
+        }
+    }
+}
+```


Missing import statement for org.bukkit.plugin.java.JavaPlugin. The example extends JavaPlugin but doesn't import it.

Fixed in cec6f8f. Added the missing import for JavaPlugin.

Copilot · 2026-01-07T04:55:21Z

API.md

+public class EconomyPlugin extends JavaPlugin {
+
+    private MailboxesAPI mailboxesAPI;
+
+    public void notifyPlayerOfPayment(UUID playerUUID, double amount, String reason) {
+        if (mailboxesAPI == null) return;
+
+        String message = String.format(
+            "You received $%.2f! Reason: %s",
+            amount,
+            reason
+        );
+
+        boolean sent = mailboxesAPI.sendPluginMessageToPlayer(
+            "EconomyPlugin", 
+            playerUUID, 
+            message
+        );
+
+        if (sent) {
+            getLogger().info("Payment notification sent to player " + playerUUID);
+        }
+    }
+}


Missing imports for this example. The code uses JavaPlugin, Plugin, Mailboxes, and MailboxesAPI but doesn't show the necessary imports.

Fixed in cec6f8f. Added all missing imports: JavaPlugin, Plugin, Mailboxes, MailboxesAPI, and UUID.

Copilot · 2026-01-07T04:55:22Z

API.md

+import org.bukkit.event.entity.PlayerDeathEvent;
+
+@EventHandler
+public void onPlayerDeath(PlayerDeathEvent event) {
+    Player player = event.getEntity();
+    Location deathLocation = player.getLocation();
+
+    if (mailboxesAPI != null) {
+        String message = String.format(
+            "You died at coordinates: X=%.0f, Y=%.0f, Z=%.0f. Your items may still be there!",
+            deathLocation.getX(),
+            deathLocation.getY(),
+            deathLocation.getZ()
+        );
+
+        // Send immediately
+        mailboxesAPI.sendPluginMessageToPlayer("DeathNotifier", player, message);


Missing import statement for org.bukkit.event.Listener. The example is annotated with @eventhandler but doesn't show that the class needs to implement Listener or provide context about event registration, which could confuse developers about how to properly use this code.

Suggested change

import org.bukkit.event.entity.PlayerDeathEvent;

@EventHandler

public void onPlayerDeath(PlayerDeathEvent event) {

Player player = event.getEntity();

Location deathLocation = player.getLocation();

if (mailboxesAPI != null) {

String message = String.format(

"You died at coordinates: X=%.0f, Y=%.0f, Z=%.0f. Your items may still be there!",

deathLocation.getX(),

deathLocation.getY(),

deathLocation.getZ()

);

// Send immediately

mailboxesAPI.sendPluginMessageToPlayer("DeathNotifier", player, message);

import org.bukkit.event.Listener;

import org.bukkit.event.entity.PlayerDeathEvent;

public class DeathNotifierListener implements Listener {

@EventHandler

public void onPlayerDeath(PlayerDeathEvent event) {

Player player = event.getEntity();

Location deathLocation = player.getLocation();

if (mailboxesAPI != null) {

String message = String.format(

"You died at coordinates: X=%.0f, Y=%.0f, Z=%.0f. Your items may still be there!",

deathLocation.getX(),

deathLocation.getY(),

deathLocation.getZ()

);

// Send immediately

mailboxesAPI.sendPluginMessageToPlayer("DeathNotifier", player, message);

}

Fixed in cec6f8f. Restructured the example as a proper Listener class with all necessary imports and context about event registration.

Copilot · 2026-01-07T04:55:22Z

API.md

+- Support for item attachments (optional)
+- Access player mailboxes and messages
+


The documentation states that messages can have "item attachments (optional)" but there's no example or documentation showing how to actually attach items to messages when sending them through the API. The sendPluginMessageToPlayer methods only accept String content. Consider adding documentation about how to work with attachments or clarifying that this feature is not available through the plugin messaging API.

Suggested change

- Support for item attachments (optional)

- Access player mailboxes and messages

- Support for item attachments via the main Java API (optional; not available through the plugin messaging API)

- Access player mailboxes and messages

Note: The plugin messaging API methods (e.g., `sendPluginMessageToPlayer`) currently accept only `String` content and do not support item attachments. Use the main Java API to work with item attachments where supported.

Fixed in cec6f8f. Clarified that item attachments are not available through the plugin messaging API and are only available through the main plugin interface for player-to-player messages.

Copilot · 2026-01-07T04:55:22Z

API.md

+        // Send immediately
+        mailboxesAPI.sendPluginMessageToPlayer("DeathNotifier", player, message);


The example code uses mailboxesAPI.sendPluginMessageToPlayer with a Player object to send immediate notifications, but the player has just died and respawned. There's a potential timing issue where this might not work as expected. Consider adding a comment or using the UUID variant instead to ensure the message is properly delivered.

Fixed in cec6f8f. Changed to use the UUID variant to ensure the message is properly delivered even during respawn.

Copilot · 2026-01-07T04:55:24Z

API.md

+// Simple string comparison works for semantic versions like "v0.0.3"
+// For more complex version checking, consider a version parsing library


The comment states "Simple string comparison works for semantic versions like 'v0.0.3'" but this is misleading. String comparison using compareTo() does not correctly handle semantic versions. For example, "v0.0.10" would incorrectly compare as less than "v0.0.3". The comment should clarify this limitation rather than suggesting it works correctly.

Suggested change

// Simple string comparison works for semantic versions like "v0.0.3"

// For more complex version checking, consider a version parsing library

// Basic lexicographical string comparison (not full semantic version handling)

// This only works reliably if versions are consistently formatted (for example, zero-padded).

// For correct semantic version comparison, use a dedicated version parsing/comparison library.

Fixed in cec6f8f. Updated the comment to clearly state the limitations rather than suggesting it works correctly for semantic versions.

Copilot · 2026-01-07T04:55:24Z

API.md

+##### `getActiveMessage(int ID)`
+**Returns:** `Message` - A specific active message by ID


The method name getMessage(int ID) is documented but does not exist in the M_Mailbox class. The actual method in M_Mailbox does not have this signature. According to the source code, M_Mailbox has getActiveMessage(int ID) and getArchivedMessage(int ID), but not a general getMessage(int ID) method.

The getMessage(int ID) method does exist in M_Mailbox - see line 27-29 of M_Mailbox.java in the source code. Added documentation for it in cec6f8f to make it more visible in the API reference.

Copilot · 2026-01-07T04:55:24Z

API.md

+    // getTrackedPlayerUUIDs() is a placeholder - implement this method to return
+    // the list of player UUIDs you want to notify (e.g., from a database or config)


The code comment refers to "getTrackedPlayerUUIDs()" as a placeholder method that should be implemented, but doesn't clarify that this is not part of the Mailboxes API and must be implemented by the developer. This could be confusing. Consider explicitly stating this is a method the developer needs to implement in their own plugin.

Suggested change

// getTrackedPlayerUUIDs() is a placeholder - implement this method to return

// the list of player UUIDs you want to notify (e.g., from a database or config)

// getTrackedPlayerUUIDs() is a placeholder helper in YOUR plugin code – it is

// not provided by the Mailboxes API. Implement this method in your own plugin

// to return the list of player UUIDs you want to notify (e.g., from a database or config).

Fixed in cec6f8f. Expanded the comment to explicitly state this is a method the developer must implement in their own plugin code, not part of the Mailboxes API.

Copilot · 2026-01-07T04:55:24Z

QUICKSTART.md

+
+Use UUID to send messages to offline players:
+
+```java


Missing import statement for UUID in the offline player example. The example uses UUID.fromString() but doesn't import java.util.UUID.

Suggested change

```java

```java

import java.util.UUID;

Fixed in cec6f8f. Added the missing import for UUID.

Copilot · 2026-01-07T04:55:25Z

QUICKSTART.md

+```java
+public void notifyPayment(UUID playerUUID, double amount) {
+    String message = String.format("You received $%.2f!", amount);
+    mailboxesAPI.sendPluginMessageToPlayer("EconomyPlugin", playerUUID, message);
+}
+```


Missing import statement for UUID in the payment notification example. The example uses UUID as a parameter type but doesn't include the necessary import.

Fixed in cec6f8f. Added the missing import for UUID.

dmccoystephenson · 2026-01-07T05:34:41Z

@copilot Address comments

- Add JavaPlugin import to all examples that extend JavaPlugin - Add Listener interface and proper event handler structure to event examples - Clarify that item attachments are not available through plugin messaging API - Add getMessage(int ID) method documentation to M_Mailbox (method exists in source) - Improve getTrackedPlayerUUIDs() placeholder comment to clarify it's user-implemented - Update version comparison warning about string comparison limitations - Change HashMap to ConcurrentHashMap for thread safety in rate limiting example - Add UUID imports to QUICKSTART.md examples that use UUID - Use UUID variant in death event to avoid timing issues with respawning players Co-authored-by: dmccoystephenson <21204351+dmccoystephenson@users.noreply.github.com>

- Simplify UUID usage comment in death event example - Use professional tone in placeholder method comment (no all caps) Co-authored-by: dmccoystephenson <21204351+dmccoystephenson@users.noreply.github.com>

Initial plan

9225b60

Copilot AI assigned Copilot and dmccoystephenson Jan 5, 2026

Copilot started work on behalf of dmccoystephenson January 5, 2026 07:16 View session

Copilot AI and others added 3 commits January 5, 2026 07:21

dmccoystephenson marked this pull request as ready for review January 5, 2026 07:28

dmccoystephenson requested a review from Copilot January 5, 2026 07:28

Copilot started reviewing on behalf of dmccoystephenson January 5, 2026 07:28 View session

Copilot AI changed the title ~~[WIP] Expand documentation for plugin integration with Mailboxes~~ Add comprehensive plugin integration documentation Jan 5, 2026

Copilot AI requested a review from dmccoystephenson January 5, 2026 07:29

Copilot finished work on behalf of dmccoystephenson January 5, 2026 07:29

Copilot AI reviewed Jan 5, 2026

View reviewed changes

Copilot started work on behalf of dmccoystephenson January 5, 2026 07:34 View session

Copilot AI and others added 2 commits January 5, 2026 07:37

Add remaining missing imports to API.md examples

3642af6

- Add M_Mailbox, Message, and ArrayList imports to message checking example - Add Bukkit, Player, List, and UUID imports to bulk notification example Co-authored-by: dmccoystephenson <21204351+dmccoystephenson@users.noreply.github.com>

Copilot finished work on behalf of dmccoystephenson January 5, 2026 07:40

dmccoystephenson requested a review from Copilot January 7, 2026 04:50

Copilot started reviewing on behalf of dmccoystephenson January 7, 2026 04:51 View session

Copilot AI reviewed Jan 7, 2026

View reviewed changes

Copilot started work on behalf of dmccoystephenson January 7, 2026 05:35 View session

Copilot AI and others added 2 commits January 7, 2026 05:38

Polish documentation - improve comment tone and clarity

4aec4f5

- Simplify UUID usage comment in death event example - Use professional tone in placeholder method comment (no all caps) Co-authored-by: dmccoystephenson <21204351+dmccoystephenson@users.noreply.github.com>

Copilot finished work on behalf of dmccoystephenson January 7, 2026 05:42

		- Support for item attachments (optional)
		- Access player mailboxes and messages

		// Send immediately
		mailboxesAPI.sendPluginMessageToPlayer("DeathNotifier", player, message);

		// Simple string comparison works for semantic versions like "v0.0.3"
		// For more complex version checking, consider a version parsing library

-// Simple string comparison works for semantic versions like "v0.0.3"
-// For more complex version checking, consider a version parsing library
+// Basic lexicographical string comparison (not full semantic version handling)
+// This only works reliably if versions are consistently formatted (for example, zero-padded).
+// For correct semantic version comparison, use a dedicated version parsing/comparison library.

		##### `getActiveMessage(int ID)`
		Returns: `Message` - A specific active message by ID

		// getTrackedPlayerUUIDs() is a placeholder - implement this method to return
		// the list of player UUIDs you want to notify (e.g., from a database or config)

-    // getTrackedPlayerUUIDs() is a placeholder - implement this method to return
-    // the list of player UUIDs you want to notify (e.g., from a database or config)
+    // getTrackedPlayerUUIDs() is a placeholder helper in YOUR plugin code – it is
+    // not provided by the Mailboxes API. Implement this method in your own plugin
+    // to return the list of player UUIDs you want to notify (e.g., from a database or config).

Add comprehensive plugin integration documentation #81

Are you sure you want to change the base?

Add comprehensive plugin integration documentation #81

Conversation

Copilot AI commented Jan 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Plugin Integration Documentation Expansion

Comments on the Issue (you are @copilot in this section)

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dmccoystephenson commented Jan 5, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI commented Jan 5, 2026 •

edited

Loading