Add public why-debug report API to FlagListener for addon developers

[Copilot]

BentoBox's why-debug system was only accessible inside FlagListener subclasses via a protected method tied to Event and Flag objects, making it unusable for arbitrary addon code. This adds a proper public API so addon developers can emit structured debug messages into the same why-debug channel.

Changes

FlagListener — new public Reason enum

Categorizes addon debug reports:

public enum Reason { INFO, WARNING, ERROR, BYPASS, MISSING_DATA }

FlagListener — three new public report overloads

// Simple — no addon context, defaults to Reason.INFO
report(@NonNull Location loc, @NonNull String message)

// With addon prefix in output
report(@Nullable Addon addon, @NonNull Location loc, @NonNull String message)

// Full control
report(@Nullable Addon addon, @NonNull Location loc, @NonNull String message, @NonNull Reason reason)

All three delegate to the full variant. The implementation scans Bukkit.getOnlinePlayers() for players that have why_debug metadata enabled in the given world, logs the message, and forwards it to the corresponding issuing admin.

Output format:

Why: [MyAddon] Player was blocked by custom rule - MISSING_DATA in world bskyblock_world at 10,64,20

Tests — new FlagListenerTest

Covers all overloads, all Reason values, and edge cases: null world, no debug-enabled players, no online players.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>API for "Why"</issue_title>
<issue_description>### Description

Is your feature request related to a problem?

BentoBox core has a nice debug messager, which admins can enable. But it currently affects only core listeners. And separate implementation would be necessary for every addon.

Describe the solution you'd like us to implement.

An API for sending debug messages for players with "why" enabled.

At the start, it could be as simple as:

public void report(@NonNull Location loc, @NonNull String message);

but useful would be also to know addon:

public void report(@NunNull Addon addon, @NonNull Location loc, @NonNull String message);

and some default reasonings, like info, crash, error would be cool to have:

enum Reasons
{
    INFO,  // informational message
    WARNING, // error message
    ERROR, // warning message
    BYPASS, // some things were bypassed.
    MISSING_DATA // some data was missing
}

public void report(@NunNull Addon addon, @NonNull Location loc, @NonNull String message, Reasons reasons);

Describe alternatives you've considered.

Write custom implementation for each addon, but it would be code duplication in most situations.
</issue_description>

<agent_instructions>Err on the side of simplicity. We'll also need documentation for how to use this that will go into the doc repo and release notes.</agent_instructions>

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

• Fixes API for "Why" #1371

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[sonarqubecloud]

Quality Gate passed

Issues
6 New issues
0 Accepted issues

Measures
0 Security Hotspots
94.7% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud