Plugins API Documentation

Provides API functions for interacting with the application’s plugin system.

This module serves as an interface to the global plugin manager instance, which is an object of PluginManager. It allows for retrieving plugin statuses, enabling or disabling plugins, reloading the plugin system, and triggering custom plugin events from external sources.

Key functionalities include: - Getting statuses and metadata of all discovered plugins (get_plugin_statuses()). - Setting the enabled/disabled state of a specific plugin (set_plugin_status()). - Reloading all plugins (reload_plugins()). - Triggering custom plugin events externally (trigger_external_plugin_event_api()).

These functions facilitate management and interaction with plugins, primarily for use by administrative interfaces like a web UI or CLI.

bedrock_server_manager.api.plugins.get_plugin_statuses(app_context: AppContext | None = None) → Dict[str, Any]

Retrieves the statuses and metadata of all discovered plugins.

This function first ensures the plugin configuration is synchronized with the plugin files on disk by calling an internal method of the PluginManager. It then returns a copy of the current plugin configuration.

Parameters:

plugin_manager (PluginManager) – The plugin manager instance.

Returns:

A dictionary with the operation result. On success: {"status": "success", "plugins": PluginConfigDict} where PluginConfigDict is a dictionary mapping plugin names (str) to their configuration (another dict containing keys like “enabled” (bool), “description” (str), “version” (str)). On error (unexpected): {"status": "error", "message": "<error_message>"}.

Return type:

Dict[str, Any]

bedrock_server_manager.api.plugins.set_plugin_status(plugin_name: str = None, enabled: bool = None, app_context: AppContext | None = None) → Dict[str, Any]

Sets the enabled/disabled status for a specific plugin.

This function updates the enabled field for the given plugin_name in the plugin configuration, which is managed by the PluginManager. The configuration is synchronized with disk before modification, and the changes are saved back to plugins.json.

Note

For the change in enabled status to take full effect (i.e., for the plugin to be loaded or unloaded), reload_plugins() typically needs to be called afterwards.

Parameters:

  • plugin_manager (PluginManager) – The plugin manager instance.

  • plugin_name (str) – The name of the plugin to configure.

  • enabled (bool) – True to enable the plugin, False to disable it.

Returns:

A dictionary with the operation result. On success: {"status": "success", "message": "Plugin '<name>' has been <enabled/disabled>..."} On error: {"status": "error", "message": "<error_message>"}.

Return type:

Dict[str, Any]

Raises:

UserInputError – If plugin_name is empty or not found in the configuration.

bedrock_server_manager.api.plugins.reload_plugins(app_context: AppContext | None = None) → Dict[str, Any]

Triggers the plugin manager to unload all active plugins and then reload all plugins based on the current configuration.

This function calls the reload method of the PluginManager instance.

Parameters:

plugin_manager (PluginManager) – The plugin manager instance.

Returns:

A dictionary with the operation result. On success: {"status": "success", "message": "Plugins have been reloaded successfully."} On error (unexpected): {"status": "error", "message": "<error_message>"}.

Return type:

Dict[str, Any]

bedrock_server_manager.api.plugins.trigger_external_plugin_event_api(event_name: str = None, payload: Dict[str, Any] = None, app_context: AppContext | None = None) → Dict[str, Any]

Allows an external source (like a web route or CLI) to trigger a custom plugin event.

This function calls the trigger_custom_plugin_event method of the PluginManager instance. The triggering_plugin_name argument for the core method is set to "external_api_trigger" to identify the source of this event.

Parameters:

  • plugin_manager (PluginManager) – The plugin manager instance.

  • event_name (str) – The name of the custom event to trigger. Must follow the ‘namespace:event_name’ format for custom events.

  • payload (Optional[Dict[str, Any]], optional) – A dictionary of data to pass as keyword arguments to the event listeners’ callback functions. Defaults to None (an empty dictionary will be passed).

Returns:

A dictionary with the operation result. On success: {"status": "success", "message": "Event '<event_name>' triggered."} On error (e.g., invalid event name format, unexpected error during dispatch): {"status": "error", "message": "<error_message>"}.

Return type:

Dict[str, Any]

Raises:

UserInputError – If event_name is empty or does not follow the ‘namespace:event_name’ format required by the plugin manager.