Addon API Documentation

API functions for managing addons on Bedrock servers.

This module provides a high-level interface for installing and managing addons (e.g., .mcpack, .mcaddon files) for specific Bedrock server instances. It primarily orchestrates calls to the addon processing methods of the BedrockServer class.

Currently, the main functionality offered is:

  • Importing and installing addon files into a server’s behavior packs and resource packs directories via import_addon().

Operations that modify server files, like addon installation, are designed to be thread-safe using a lock (_addon_lock). The module also utilizes the server_lifecycle_manager() to optionally manage the server’s state (stopping and restarting) during these operations to ensure data integrity. All primary functions are exposed to the plugin system.

bedrock_server_manager.api.addon.import_addon(server_name: str, addon_file_path: str, stop_start_server: bool = True, restart_only_on_success: bool = True, app_context: AppContext | None = None) → Dict[str, str]

Installs an addon to a specified Bedrock server.

This function handles the import and installation of an addon file (.mcaddon or .mcpack) into the server’s addon directories. It is thread-safe, using a lock to prevent concurrent addon operations which could lead to corrupted files. It calls process_addon_file() for the core processing logic.

The function can optionally manage the server’s lifecycle by stopping it before the installation and restarting it after, using the server_lifecycle_manager(). Triggers before_addon_import and after_addon_import plugin events.

Parameters:

  • server_name (str) – The name of the server to install the addon on.

  • addon_file_path (str) – The absolute path to the addon file (.mcaddon or .mcpack).

  • stop_start_server (bool, optional) – If True, the server will be stopped before installation and started afterward. Defaults to True.

  • restart_only_on_success (bool, optional) – If True and stop_start_server is True, the server will only be restarted if the addon installation succeeds. Defaults to True.

Returns:

A dictionary with the operation result. Possible statuses: “success”, “error”, or “skipped” (if lock not acquired). On success: {"status": "success", "message": "Addon '<filename>' installed..."} On error: {"status": "error", "message": "<error_message>"}.

Return type:

Dict[str, str]

Raises: