PluginServerInterface

API package path: mcdreforged.api.types

class mcdreforged.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) 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

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

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 = 'config.json', 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') 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

Returns:

A dict contains the loaded and processed config

New in version v2.2.0: The encoding parameter

New in version v2.12.0: The failure_policy and file_format parameters

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

New in version v2.2.0: The encoding parameter

New in version v2.12.0: The file_format parameter