Class SyncBukkit

java.lang.Object
top.magstar.framework.SyncBukkit
public class SyncBukkit extends Object
Utility wrapper for executing Bukkit API operations safely on the main server thread.

Many methods in the Bukkit API are not thread-safe and must be called synchronously from the server's primary thread. SyncBukkit provides convenience wrappers to schedule these calls via BukkitRunnable, ensuring they run in the correct context when invoked from asynchronous or external threads.

Key Characteristics

  • Each exposed method internally creates a BukkitRunnable and executes it synchronously using BukkitScheduler.runTask(org.bukkit.plugin.Plugin, java.lang.Runnable).
  • Supports common server operations such as broadcasting messages, dispatching commands, modifying recipes, managing whitelist, reloading data, setting the default game mode, and shutting down the server.
  • Overloads provided for broadcasting both plain strings and BaseComponent arrays, allowing legacy and component-based chat support.
  • Null-safety annotations (Nonnull, ParametersAreNonnullByDefault, ParametersAreNullableByDefault) indicate which parameters may be null and are handled defensively.

Usage Example


 SyncBukkit sync = magstarPlugin.getSyncBukkit();

 // Safe to call from async thread
 sync.dispatchCommand(Bukkit.getConsoleSender(), "say Hello!");

 // Broadcast multiple messages
 sync.broadcast("§aServer restart soon!", "§ePlease finish your fights.");

 // Shut down the server safely
 sync.shutDown();

Limitations

  • This class is designed for void-returning Bukkit operations. Getter calls (e.g. Bukkit.getOnlinePlayers()) are not supported, since they would require executing synchronously and blocking the caller thread for results.
  • For getters, the caller should schedule its own synchronous task or use Bukkit's scheduler to obtain results directly.

Using this class helps plugin developers write thread-safe code while still taking advantage of asynchronous background tasks, reducing the risk of concurrency-related issues in Bukkit-based projects.

Since:
1.0.0
Version:
1.0.0
Author:
Berry_so
See Also:
  • Bukkit
  • BukkitRunnable

  • Constructor Details

    • SyncBukkit

      @ParametersAreNonnullByDefault public SyncBukkit(org.bukkit.plugin.java.JavaPlugin plugin)
      构造同步Bukkit操作包装器
      Parameters:
      plugin - 插件实例

  • Method Details

    • dispatchCommand

      @ParametersAreNullableByDefault public void dispatchCommand(org.bukkit.command.CommandSender cs, String cmd)
      在主线程执行命令
      Parameters:
      cs - 命令发送者
      cmd - 要执行的命令

    • setMaxPlayers

      public void setMaxPlayers(int count)
      设置最大玩家数
      Parameters:
      count - 最大玩家数

    • setWhiteList

      public void setWhiteList(boolean useWhiteList)
      设置是否启用白名单
      Parameters:
      useWhiteList - true表示启用白名单，false表示禁用

    • reloadWhiteList

      public void reloadWhiteList()
      重新加载白名单

    • broadcast

      @ParametersAreNullableByDefault public void broadcast(String... msg)
      广播消息到所有玩家
      Parameters:
      msg - 要广播的消息数组

    • broadcast

      @ParametersAreNullableByDefault public void broadcast(net.md_5.bungee.api.chat.BaseComponent... components)
      广播组件消息到所有玩家
      Parameters:
      components - 要广播的组件数组

    • reload

      public void reload()
      重新加载服务器

    • reloadData

      public void reloadData()
      重新加载服务器数据

    • addRecipe

      @ParametersAreNullableByDefault public void addRecipe(org.bukkit.inventory.Recipe... recipes)
      添加配方
      Parameters:
      recipes - 要添加的配方数组

    • clearRecipes

      public void clearRecipes()
      清除所有配方

    • resetRecipes

      public void resetRecipes()
      重置配方为默认值

    • removeRecipes

      @ParametersAreNullableByDefault public void removeRecipes(org.bukkit.NamespacedKey... name)
      移除配方
      Parameters:
      name - 要移除的配方键数组

    • shutDown

      public void shutDown()
      关闭服务器

    • setDefaultGameMode

      public void setDefaultGameMode(org.bukkit.GameMode mode)
      设置默认游戏模式
      Parameters:
      mode - 游戏模式

    • reloadPermissions

      public void reloadPermissions()
      重新加载权限

    • reloadCommandAliases

      public void reloadCommandAliases()
      重新加载命令别名