World API Documentation

Provides API functions for managing Bedrock server worlds.

This module offers a high-level interface for world-related operations on Bedrock server instances. It wraps methods of the BedrockServer class to facilitate tasks such as:

• Retrieving the active world name (get_world_name()).

• Exporting the active server world to a .mcworld archive file (export_world()).

• Importing a world from a .mcworld file, replacing the active world (import_world()).

• Resetting the active server world, prompting regeneration on next start (reset_world()).

Operations involving world file modifications (export, import, reset) are thread-safe using a unified lock (_world_lock) to prevent data corruption. For actions that require the server to be offline (like import or reset), this module utilizes the server_lifecycle_manager() to safely stop and restart the server. All functions are exposed to the plugin system.

bedrock_server_manager.api.world.get_world_name(server_name: str, app_context: AppContext | None = None) → Dict[str, Any]

Retrieves the configured world name (level-name) for a server.

This function reads the server.properties file to get the name of the directory where the world data is stored, by calling get_world_name().

Parameters:

server_name (str) – The name of the server to query.

Returns:

A dictionary with the operation result. On success: {"status": "success", "world_name": "<world_name_str>"}. On error: {"status": "error", "message": "<error_message>"}.

Return type:

Dict[str, Any]

Raises:

• InvalidServerNameError – If server_name is not provided.

• BSMError – Can be raised by BedrockServer instantiation or by the underlying get_world_name method (e.g., AppFileNotFoundError if server.properties is missing, or ConfigParseError if level-name is missing or malformed).

bedrock_server_manager.api.world.export_world(server_name: str, export_dir: str | None = None, stop_start_server: bool = True, app_context: AppContext | None = None) → Dict[str, Any]

Exports the server’s currently active world to a .mcworld archive.

This operation is thread-safe due to _world_lock. If stop_start_server is True, it uses the server_lifecycle_manager() to ensure the server is stopped during the export for file consistency, and then restarted. The core world export is performed by export_world_directory_to_mcworld(). Triggers before_world_export and after_world_export plugin events.

Parameters:

• server_name (str) – The name of the server whose world is to be exported.

• export_dir (Optional[str], optional) – The directory to save the exported .mcworld file. If None, it defaults to a “worlds” subdirectory within the application’s global content directory (defined by paths.content setting). Defaults to None.

• stop_start_server (bool, optional) – If True, the server will be stopped before the export and restarted afterwards. Defaults to True.

Returns:

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

Return type:

Dict[str, Any]

Raises:

• InvalidServerNameError – If server_name is empty.

• FileOperationError – If the content directory setting (paths.content) is missing when export_dir is None, or for other file I/O errors during export or lifecycle management.

• BSMError – Propagates errors from underlying operations, including AppFileNotFoundError if world directory is missing, BackupRestoreError from export, or errors from server stop/start.

bedrock_server_manager.api.world.import_world(server_name: str, selected_file_path: str, stop_start_server: bool = True, app_context: AppContext | None = None) → Dict[str, str]

Imports a world from a .mcworld file, replacing the active world.

This is a destructive operation that replaces the current world. It is thread-safe and manages the server lifecycle to ensure data integrity.

Warning

This is a DESTRUCTIVE operation. The existing active world directory will be deleted before the new world is imported.

If stop_start_server is True, this function uses the server_lifecycle_manager() to ensure the server is stopped during the import. The core world import is performed by import_active_world_from_mcworld(). Triggers before_world_import and after_world_import plugin events.

Parameters:

• server_name (str) – The name of the server to import the world into.

• selected_file_path (str) – The absolute path to the .mcworld file to import.

• stop_start_server (bool, optional) – If True, the server will be stopped before the import and restarted afterwards. 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": "World '<name>' imported..."} On error: {"status": "error", "message": "<error_message>"}.

Return type:

Dict[str, str]

Raises:

• InvalidServerNameError – If server_name is empty.

• MissingArgumentError – If selected_file_path is empty.

• FileNotFoundError – If selected_file_path does not exist (from implementation).

• BSMError – Propagates errors from underlying operations, including BackupRestoreError from import, ExtractError, or errors from server stop/start.

bedrock_server_manager.api.world.reset_world(server_name: str, app_context: AppContext | None = None) → Dict[str, str]

Resets the server’s world by deleting the active world directory.

This is a destructive action. Upon next start, the server will generate a new world based on its server.properties configuration. This function is thread-safe and manages the server lifecycle.

Warning

This is a DESTRUCTIVE operation. The existing active world directory will be permanently removed.

This function uses the server_lifecycle_manager() to ensure the server is stopped before deleting the world and restarted afterwards (which will trigger new world generation). The active world directory is deleted using delete_active_world_directory(). Triggers before_world_reset and after_world_reset plugin events.

Parameters:

server_name (str) – The name of the server whose world is to be reset.

Returns:

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

Return type:

Dict[str, str]

Raises:

• InvalidServerNameError – If server_name is empty.

• BSMError – Propagates errors from underlying operations, including FileOperationError from deletion, errors determining the world name, or errors from server stop/start.