PluginServerInterface

API package path: mcdreforged.api.types

class mcdreforged.plugin.si.plugin_server_interface.PluginServerInterface(mcdr_server: MCDReforgedServer, plugin: AbstractPlugin)[source]: Derived from ServerInterface, PluginServerInterface adds the ability for plugins to control the plugin itself on the basis of ServerInterface

Plugin Registry

PluginServerInterface.register_event_listener(event: PluginEvent | str, callback: Callable, priority: int | None = None) → None[source]

Register an event listener for the current plugin

Parameters:

event – The id of the event, or a PluginEvent instance. It indicates the target event for the plugin to listen
callback – The callback listener method for the event
priority – The priority of the listener. It will be set to the default value 1000 if it’s not specified

PluginServerInterface.register_command(root_node: Literal, *, allow_duplicates: bool = False) → None[source]

Register a command for the current plugin

Parameters:: root_node – the root node of your command tree. It should be a Literal node
Keyword Arguments:: allow_duplicates – If set to False (default), a warning will be printed if duplicated command root node is found. If set to True, the warning will be suppressed as what it behaves before

Added in version v2.13.0: The allow_duplicates parameter

PluginServerInterface.register_help_message(prefix: str, message: str | RTextBase | Dict[str, str | RTextBase], permission: int = 0) → None[source]

Register a help message for the current plugin, which is used in !!help command

Parameters:

prefix – The help command of your plugin. When player click on the displayed message it will suggest this prefix parameter to the player. It’s recommend to set it to the entry command of your plugin
message – A neat command description. It can be a str or a RText Also, it can be a dict maps from language to description message
permission – The minimum permission level for the user to see this help message. With default permission, anyone can see this message

PluginServerInterface.register_translation(language: str, mapping: Dict[str, str | Dict[str, str | TranslationKeyDictNested]]) → None[source]

Register a translation mapping for a specific language for the current plugin

Parameters:

language – The language of this translation
mapping – A dict which maps translation keys into translated text. The translation key could be expressed as node name which under root node or the path of a nested multi-level nodes

PluginServerInterface.register_server_handler(server_handler: ServerHandler)[source]

Register a plugin-provided server handler

The server handler will override the configured server handler of MCDR, within the lifecycle of the current plugin

If multiple plugins provide multiple server handler, only the first one will be used, and warning messages will be logged

Parameters:: server_handler – The server handler to register

Added in version v2.13.0.

PluginServerInterface.register_info_filter(info_filter: InfoFilter)[source]

Register a plugin-provided info filter. See InfoFilter for more information

The info filter take effects within the lifecycle of the current plugin

Warning

The info filter callbacks will be invoked in the MCDR main thread, not the task executor thread

Make sure your function is well optimized, or it might lag MCDR, and also be aware of multithreading race condition

Parameters:: info_filter – The info filter to register

Added in version v2.13.0.

Plugin Utils

PluginServerInterface.get_self_metadata() → Metadata[source]: Return the metadata of the plugin itself

PluginServerInterface.get_data_folder() → str[source]

Return a unified data directory path for the current plugin

The path of the folder will be "config/plugin_id"/ where plugin_id is the id of the current plugin if the directory does not exist, create it

Example:

with open(os.path.join(server.get_data_folder(), 'my_data.txt'), 'w') as file_handler:
    write_some_data(file_handler)

Returns:: The path to the data directory

PluginServerInterface.open_bundled_file(relative_file_path: str) → IO[bytes][source]

Open a file inside the plugin with readonly binary mode

Example:

with server.open_bundled_file('message.txt') as file_handler:
    message = file_handler.read().decode('utf8')
server.logger.info('A message from the file: {}'.format(message))

Parameters:: relative_file_path – The related file path in your plugin to the file you want to open
Returns:: A un-decoded bytes file-like object
Raises:: FileNotFoundError – if the plugin is not a packed plugin (that is, a solo plugin)

PluginServerInterface.load_config_simple(file_name: str | None = None, default_config: Optional = None, *, in_data_folder: bool = True, echo_in_console: bool = True, source_to_reply: CommandSource | None = None, target_class: Type[SerializableType] | None = None, encoding: str = 'utf8', file_format: Literal['json', 'yaml'] | None = None, failure_policy: Literal['regen', 'raise'] = 'regen', data_processor: Callable[[dict], bool] | None = None) → dict | SerializableType[source]

A simple method to load a dict or Serializable type config from a json file

Default config is supported. Missing key-values in the loaded config object will be filled using the default config

Example 1:

config = {
    'settingA': 1
    'settingB': 'xyz'
}
default_config = config.copy()

def on_load(server: PluginServerInterface, prev_module):
    global config
    config = server.load_config_simple('my_config.json', default_config)

Example 2:

class Config(Serializable):
    settingA: int = 1
    settingB: str = 'xyz'

config: Config

def on_load(server: PluginServerInterface, prev_module):
    global config
    config = server.load_config_simple(target_class=Config)

Assuming that the plugin id is my_plugin, then the config file will be in "config/my_plugin/my_config.json"

Parameters:

file_name – The name of the config file. It can also be a path to the config file
default_config – A dict contains the default config. It’s required when the config file is missing, or exception will be risen. If target_class is given and default_config is missing, the default values in target_class will be used when the config file is missing

Keyword Arguments:

in_data_folder – If True, the parent directory of file operating is the data folder of the plugin
echo_in_console – If logging messages in console about config loading
source_to_reply – The command source for replying logging messages
target_class – A class derived from Serializable. When specified the loaded config data will be deserialized to an instance of target_class which will be returned as return value
encoding – The encoding method to read the config file. Default "utf8"
file_format – The syntax format of the config file. Default: None, which means that MCDR will try to detect the format from the name of the config file
failure_policy – The policy of handling a config loading error. "regen" (default): try to re-generate the config; "raise": directly raise the exception
data_processor – A callback function that processes the data read from the config file. It should accept one argument and return a bool. The argument is the parsed config file, normally a dict-like object. The return value indicates if the file saving operation should be performed after the config loading Example usage: config data migration

Returns:

A dict contains the loaded and processed config

Added in version v2.2.0: The encoding parameter

Added in version v2.12.0: The failure_policy and file_format parameter

Added in version v2.13.0: The data_processor parameter

PluginServerInterface.save_config_simple(config: dict | Serializable, file_name: str = 'config.json', *, in_data_folder: bool = True, encoding: str = 'utf8', file_format: Literal['json', 'yaml'] | None = None) → None[source]

A simple method to save your dict or Serializable type config as a json file

Parameters:

config – The config instance to be saved
file_name – The name of the config file. It can also be a path to the config file

Keyword Arguments:

in_data_folder – If True, the parent directory of file operating is the data folder of the plugin
encoding – The encoding method to write the config file. Default "utf8"
file_format – The syntax format of the config file. Default: None, which means that MCDR will try to detect the format from the name of the config file

Added in version v2.2.0: The encoding parameter

Added in version v2.12.0: The file_format parameter