Plugin

endstone.plugin

Classes relating to loading and managing plugins.

Modules:

Name	Description
plugin_loader

Classes:

Name	Description
Plugin	Represents a Plugin
PluginCommand	Represents a Command belonging to a Plugin
PluginLoadOrder	Represents the order in which a plugin should be initialized and enabled.
PluginLoader	Represents a plugin loader, which handles direct access to specific types of plugins
PluginManager	Represents a plugin manager that handles all plugins from the Server
Service	Represents a list of methods.
ServiceManager	Represent a service manager that manages services and service providers.
ServicePriority	Represents various priorities of a provider.

Plugin

Plugin()

Bases: Plugin

Represents a Plugin

Methods:

Name	Description
get_command	Gets the command with the given name, specific to this plugin.
on_disable	Called when this plugin is disabled
on_enable	Called when this plugin is enabled
on_load	Called after a plugin is loaded but before it has been enabled.
register_events	Registers all events defined in the given listener instance.
reload_config	Returns the plugin's configuration loaded from config.toml.
save_config	Saves the current configuration to the config.toml file.
save_default_config	Saves the default config.toml file to the plugin's data folder.
save_resources	Saves a packaged resource from the plugin module to the data folder.

Attributes:

Name	Type	Description
api_version
authors
commands
config	dict	Returns the plugin's configuration loaded from config.toml.
contributors
data_folder	Path	Returns the folder that the plugin data's files are located in.
default_permission
depend
description
is_enabled	bool	Returns a value indicating whether this plugin is currently enabled
load
load_before
logger	Logger	Returns the plugin logger associated with this server's logger.
name	str	Returns the name of the plugin.
permissions
plugin_loader	PluginLoader	Gets the associated PluginLoader responsible for this plugin
prefix
provides
server	Server	Returns the Server instance currently running this plugin
soft_depend
version
website

api_version class-attribute instance-attribute

api_version = None

authors class-attribute instance-attribute

authors = None

commands class-attribute instance-attribute

commands = None

config property

config: dict

Returns the plugin's configuration loaded from config.toml.

Loads and returns the plugin’s configuration data from config.toml. If the configuration has not been loaded yet, it is automatically reloaded using reload_config().

Returns:

Name	Type	Description
dict	dict	The plugin's configuration data.

contributors class-attribute instance-attribute

contributors = None

data_folder property

data_folder: Path

Returns the folder that the plugin data's files are located in.

default_permission class-attribute instance-attribute

default_permission = None

depend class-attribute instance-attribute

depend = None

description class-attribute instance-attribute

description = None

is_enabled property

is_enabled: bool

Returns a value indicating whether this plugin is currently enabled

load class-attribute instance-attribute

load = None

load_before class-attribute instance-attribute

load_before = None

logger property

logger: Logger

Returns the plugin logger associated with this server's logger.

name property

name: str

Returns the name of the plugin.

permissions class-attribute instance-attribute

permissions = None

plugin_loader property

plugin_loader: PluginLoader

Gets the associated PluginLoader responsible for this plugin

prefix class-attribute instance-attribute

prefix = None

provides class-attribute instance-attribute

provides = None

server property

server: Server

Returns the Server instance currently running this plugin

soft_depend class-attribute instance-attribute

soft_depend = None

version class-attribute instance-attribute

version = None

website class-attribute instance-attribute

website = None

get_command

get_command(name: str) -> PluginCommand

Gets the command with the given name, specific to this plugin.

on_disable

on_disable() -> None

Called when this plugin is disabled

on_enable

on_enable() -> None

Called when this plugin is enabled

on_load

on_load() -> None

Called after a plugin is loaded but before it has been enabled.

register_events

register_events(listener: object) -> None

Registers all events defined in the given listener instance.

Parameters:

Name	Type	Description	Default
listener	object	The listener object containing event handler methods to be registered.	required

reload_config

reload_config() -> dict

Returns the plugin's configuration loaded from config.toml.

Loads and returns the plugin’s configuration data from config.toml. If a default configuration file is packaged with the plugin, its values are used as defaults.

Returns:

Name	Type	Description
dict	dict	The plugin's configuration data.

save_config

save_config() -> None

Saves the current configuration to the config.toml file.

save_default_config

save_default_config() -> None

Saves the default config.toml file to the plugin's data folder.

If config.toml does not already exist in the plugin’s data folder, this method copies the default version from the plugin’s packaged resources. If the file already exists, the method does nothing and fails silently.

save_resources

save_resources(path: str, replace: bool = False) -> None

Saves a packaged resource from the plugin module to the data folder.

The method locates a resource bundled within the plugin’s package and copies it to the plugin’s data folder, preserving its relative directory structure. If the target file already exists, it will only be replaced if replace is set to True.

Parameters:

Name	Type	Description	Default
path	str	The relative path to the resource inside the plugin’s package. Directory separators are normalized to forward slashes.	required
replace	bool	Whether to overwrite the existing file if it already exists. Defaults to False.	False

Raises:

Type	Description
FileNotFoundError	If the specified resource cannot be found in the package.
OSError	If an error occurs while copying or creating directories.

PluginCommand

PluginCommand(
    name: str,
    description: str | None = None,
    usages: list[str] | None = None,
    aliases: list[str] | None = None,
    permissions: list[str] | None = None,
    *args,
    **kwargs
)

Bases: Command

Represents a Command belonging to a Plugin

Attributes:

Name	Type	Description
executor	CommandExecutor	The CommandExecutor to run when parsing this command
plugin	Plugin	The owner of this PluginCommand

executor property writable

executor: CommandExecutor

The CommandExecutor to run when parsing this command

plugin property

plugin: Plugin

The owner of this PluginCommand

PluginLoadOrder

Bases: Enum

Represents the order in which a plugin should be initialized and enabled.

Attributes:

Name	Type	Description
POSTWORLD
STARTUP

POSTWORLD class-attribute instance-attribute

POSTWORLD = 1

STARTUP class-attribute instance-attribute

STARTUP = 0

PluginLoader

PluginLoader(server: Server)

Represents a plugin loader, which handles direct access to specific types of plugins

Methods:

Name	Description
disable_plugin	Disables the specified plugin
enable_plugin	Enables the specified plugin
load_plugin	Loads the plugin contained in the specified file
load_plugins	Loads the plugin contained within the specified directory

Attributes:

Name	Type	Description
plugin_file_filters	list[str]	Returns a list of all filename filters expected by this PluginLoader
server	Server	Retrieves the Server object associated with the PluginLoader.

plugin_file_filters property

plugin_file_filters: list[str]

Returns a list of all filename filters expected by this PluginLoader

server property

server: Server

Retrieves the Server object associated with the PluginLoader.

disable_plugin

disable_plugin(plugin: Plugin) -> None

Disables the specified plugin

enable_plugin

enable_plugin(plugin: Plugin) -> None

Enables the specified plugin

load_plugin

load_plugin(file: str) -> Plugin

Loads the plugin contained in the specified file

load_plugins

load_plugins(directory: str) -> list[Plugin]

Loads the plugin contained within the specified directory

PluginManager

Represents a plugin manager that handles all plugins from the Server

Methods:

Name	Description
call_event	Calls an event which will be passed to plugins.
clear_plugins	Disables and removes all plugins
disable_plugin	Disables the specified plugin
disable_plugins	Disables all the loaded plugins
enable_plugin	Enables the specified plugin
enable_plugins	Enable all the loaded plugins
get_default_perm_subscriptions	Gets a set containing all subscribed Permissibles to the given default list, by permission level.
get_default_permissions	Gets the default permissions for the given permission level.
get_permission	Gets a Permission from its fully qualified name.
get_permission_subscriptions	Gets a set containing all subscribed Permissibles to the given permission.
get_plugin	Checks if the given plugin is loaded and returns it when applicable.
is_plugin_enabled
load_plugin	Loads the plugin in the specified file
load_plugins
recalculate_permission_defaults	Recalculates the defaults for the given Permission.
register_event	Registers the given event
remove_permission
subscribe_to_default_perms	Subscribes to the given Default permissions by permission level.
subscribe_to_permission	Subscribes the given Permissible for information about the requested Permission.
unsubscribe_from_default_perms	Unsubscribes from the given Default permissions by permission level.
unsubscribe_from_permission	Unsubscribes the given Permissible for information about the requested Permission.

Attributes:

Name	Type	Description
permissions	set[Permission]	Gets a set of all registered permissions.
plugins	list[Plugin]	Gets a list of all currently loaded plugins

permissions property

permissions: set[Permission]

Gets a set of all registered permissions.

plugins property

plugins: list[Plugin]

Gets a list of all currently loaded plugins

call_event

call_event(event: Event) -> None

Calls an event which will be passed to plugins.

clear_plugins

clear_plugins() -> None

Disables and removes all plugins

disable_plugin

disable_plugin(plugin: Plugin) -> None

Disables the specified plugin

disable_plugins

disable_plugins() -> None

Disables all the loaded plugins

enable_plugin

enable_plugin(plugin: Plugin) -> None

Enables the specified plugin

enable_plugins

enable_plugins() -> None

Enable all the loaded plugins

get_default_perm_subscriptions

get_default_perm_subscriptions(
    level: PermissionLevel,
) -> set[Permissible]

Gets a set containing all subscribed Permissibles to the given default list, by permission level.

get_default_permissions

get_default_permissions(
    level: PermissionLevel,
) -> list[Permission]

Gets the default permissions for the given permission level.

get_permission

get_permission(name: str) -> Permission

Gets a Permission from its fully qualified name.

get_permission_subscriptions

get_permission_subscriptions(
    permission: str,
) -> set[Permissible]

Gets a set containing all subscribed Permissibles to the given permission.

get_plugin

get_plugin(name: str) -> Plugin

Checks if the given plugin is loaded and returns it when applicable.

is_plugin_enabled

is_plugin_enabled(plugin: str) -> bool

Checks if the given plugin is enabled or not

is_plugin_enabled(plugin: Plugin) -> bool

Checks if the given plugin is enabled or not

load_plugin

load_plugin(file: str) -> Plugin

Loads the plugin in the specified file

load_plugins

load_plugins(directory: str) -> list[Plugin]

Loads the plugin contained within the specified directory

load_plugins(files: list[str]) -> list[Plugin]

Loads the plugins in the list of the files

recalculate_permission_defaults

recalculate_permission_defaults(perm: Permission) -> None

Recalculates the defaults for the given Permission.

register_event

register_event(
    name: str,
    executor: Callable[[Event], None],
    priority: EventPriority,
    plugin: Plugin,
    ignore_cancelled: bool,
) -> None

Registers the given event

remove_permission

remove_permission(perm: Permission) -> None

Removes a Permission registration from this plugin manager by permission object.

remove_permission(name: str) -> None

Removes a Permission registration from this plugin manager by name.

subscribe_to_default_perms

subscribe_to_default_perms(
    level: PermissionLevel, permissible: Permissible
) -> None

Subscribes to the given Default permissions by permission level.

subscribe_to_permission

subscribe_to_permission(
    permission: str, permissible: Permissible
) -> None

Subscribes the given Permissible for information about the requested Permission.

unsubscribe_from_default_perms

unsubscribe_from_default_perms(
    level: PermissionLevel, permissible: Permissible
) -> None

Unsubscribes from the given Default permissions by permission level.

unsubscribe_from_permission

unsubscribe_from_permission(
    permission: str, permissible: Permissible
) -> None

Unsubscribes the given Permissible for information about the requested Permission.

Service

Service()

Represents a list of methods.

ServiceManager

Represent a service manager that manages services and service providers.

Methods:

Name	Description
load
register	Register a provider of a service.
unregister
unregister_all	Unregister all the services registered by a particular plugin.

load

load(name: str) -> Service

register

register(
    name: str,
    provider: Service,
    plugin: Plugin,
    priority: ServicePriority,
) -> None

Register a provider of a service.

unregister

unregister(name: str, provider: Service) -> None

Unregister a particular provider for a particular service.

unregister(provider: Service) -> None

Unregister a particular provider.

unregister_all

unregister_all(plugin: Plugin) -> None

Unregister all the services registered by a particular plugin.

ServicePriority

Bases: IntEnum

Represents various priorities of a provider.

Attributes:

Name	Type	Description
HIGH
HIGHEST
LOW
LOWEST
NORMAL

HIGH class-attribute instance-attribute

HIGH = 3

HIGHEST class-attribute instance-attribute

HIGHEST = 4

LOW class-attribute instance-attribute

LOW = 1

LOWEST class-attribute instance-attribute

LOWEST = 0

NORMAL class-attribute instance-attribute

NORMAL = 2