Player API Documentation

Provides API functions for managing the central player database.

This module offers an interface to interact with the application’s central player database, typically stored in players.json. It leverages the BedrockServerManager to perform operations such as:

• Manually adding or updating player entries (gamertag and XUID) via add_players_manually_api().

• Retrieving all known player entries from the database using get_all_known_players_api().

• Discovering players by scanning server logs and updating the database via scan_and_update_player_db_api().

These functions are exposed to the plugin system and provide a structured way to manage player data globally across all server instances.

bedrock_server_manager.api.player.add_players_manually_api(player_strings: List[str], settings=None, app_context: AppContext | None = None) → Dict[str, Any]

Adds or updates player data in the database.

This function takes a list of strings, each containing a player’s gamertag and XUID, parses them, and saves the data to the player database. It uses parse_player_cli_argument() (after joining the list into a single comma-separated string) and then save_player_data(). Triggers before_players_add and after_players_add plugin events.

Parameters:

player_strings (List[str]) – A list of strings. Each string should represent a single player in the format “gamertag:xuid” (e.g., "PlayerOne:1234567890123456"). Example list: ["PlayerOne:123...", "PlayerTwo:654..."].

Returns:

A dictionary with the operation result. On success: {"status": "success", "message": "<n> player entries processed...", "count": <n>} On error (parsing or saving): {"status": "error", "message": "<error_message>"}

Return type:

Dict[str, Any]

Raises:

• UserInputError – If any player string in player_strings is malformed (propagated from parse_player_cli_argument).

• BSMError – If saving to the database fails.

bedrock_server_manager.api.player.get_all_known_players_api(settings=None, app_context: AppContext | None = None) → Dict[str, Any]

Retrieves all player data from the database.

Calls get_known_players().

Returns:

A dictionary with the operation result. On success: {"status": "success", "players": List[PlayerDict]} where each PlayerDict typically contains “name” and “xuid”. Returns an empty list for players if the database is empty. On unexpected error: {"status": "error", "message": "<error_message>"}.

Return type:

Dict[str, Any]

bedrock_server_manager.api.player.scan_and_update_player_db_api(settings=None, app_context: AppContext | None = None) → Dict[str, Any]

Scans all server logs to discover and save player data.

This function iterates through the log files of all managed servers, extracts player connection information (gamertag and XUID), and updates the central player database with any new findings. It calls discover_and_store_players_from_all_server_logs(). Triggers before_player_db_scan and after_player_db_scan plugin events.

Returns:

A dictionary with the operation result. On success: {"status": "success", "message": "<summary_message>", "details": ScanResultDict} where ScanResultDict contains keys like: "total_entries_in_logs" (int), "unique_players_submitted_for_saving" (int), "actually_saved_or_updated_in_db" (int), "scan_errors" (List[Dict[str, str]]). On error: {"status": "error", "message": "<error_message>"}.

Return type:

Dict[str, Any]

Raises:

BSMError – Can be raised by the underlying manager method, e.g., AppFileNotFoundError if the main server base directory is misconfigured, or FileOperationError if the final save to the database fails. Individual server scan errors are reported within the “details” part of a successful response.