AddonManager

Provides access to the server’s Add-on Manager to manage installed files, and online discovery. The addon global exposes the existing ServerObject.addon manager.

Installed and remotely available add-ons are represented by AddonFileObject and AddonWebObject, respectively.

Note

After downloading or changing add-ons, you’ll generally need to restart the server. On Bukkit-based server types like Paper, Spigot, or Purpur, you can use the /reload command in some cases to hot-reload them. See the example for hot-reloading

Vanilla servers don’t support add-ons, but the AddonManager is still included for compatibility. Because of this, the following methods and attributes will return None, an empty list, or False with certain checks

View the source: AddonManager

Methods

addon.search_addons(query)

Returns a list of AddonWebObject matching the query, ordered by provider search relevance

Parameters	Type	Description
query*	str	Partial search term or full add-on name

addon.download_addon(target)

Downloads an add-on from a string of the add-on name, ID, or an AddonWebObject provided by addon.search_addons(). The file is saved in addon.addon_path

Note

This method will automatically determine the most compatible version for your server. See Download Add-ons for more details

Parameters	Type	Description
target*	str / AddonWebObject	Target add-on name or object to download

addon.import_addon(path)

Imports a .jar file to addon.addon_path

Parameters	Type	Description
path*	str / AddonFileObject	Full system path to the .jar file, or an existing add-on file object

addon.addon_state(target, enabled=True, all=False)

Enables/disables an installed AddonFileObject, or all add-ons if specified. Requires target or all, and not both

Parameters	Type	Description
target*	AddonFileObject	An add-on object from addon.get_addon()
enabled	bool	Enable or disable the add-on. Defaults to True
all*	bool	Operate on every installed add-on. Defaults to False

addon.delete_addon(target)

Permanently deletes an installed AddonFileObject

Parameters	Type	Description
target*	AddonFileObject	An add-on object from addon.get_addon()

addon.get_addon(query, online=False)

Retrieves an AddonFileObject from the installed server add-ons, or an AddonWebObject from the online repository if online=True

Parameters	Type	Description
query*	str	Add-on name
online	bool	Defaults to False

addon.return_single_list()

Returns a flattened list of all AddonFileObject from addon.installed_addons

addon.filter_addons(query)

Returns a list of locally installed AddonFileObject entries ranked by a search term matched against titles, filenames, authors, and descriptions

Parameters	Type	Description
query*	str	Search term to match against installed add-ons

addon.check_for_updates()

Checks the AddonFileObject.addon_version for installed add-ons against online releases. Returns True if one or more add-ons require an update, otherwise False. Check addon.get_update_list() for the matching objects

Note

Use addon.update_addon() or addon.update_all() to apply available updates

addon.check_geyser()

Checks installed add-on IDs for Geyser support on supported distributions. Returns True if Geyser is detected

addon.get_update_list()

Returns installed AddonFileObject values for which update URLs have already been discovered

addon.update_addon(target)

Downloads an available update for the target add-on, and replaces the .jar when successful. Returns the updated AddonFileObject or None. This method preserves the enabled or disabled state

Parameters	Type	Description
target*	AddonFileObject	An add-on object from addon.get_addon()

addon.update_all()

Updates all installed add-ons with discovered update URLs. Returns a list of successfully updated AddonFileObject values.

addon.find_addon(addon)

Looks up a web add-on by name or file object through the configured add-on providers. Returns a matching AddonWebObject when available.

Parameters	Type	Description
addon*	str / AddonFileObject	Add-on name or installed add-on object

addon._hash_changed()

Internal method for determining if the add-on configuration has been modified since the last server restart. Returns bool

Attributes

Note

All attributes are read-only, and thus will not change the server data when modified

Attribute	Type	Description
addon.installed_addons	dict	Contains lists of AddonFileObject; see the structure in examples
addon.addon_path	str	Full filesystem path to the server’s add-ons directory
addon.disabled_addon_path	str	Full filesystem path to the server’s disabled add-ons directory
addon.active_updates	list	str, Identifiers of add-ons whose update operations are in progress
addon.geyser_support	bool	True If Geyser is detected on a supported distribution

Examples

Automatic hot-reloading:

def reload():
    if server.type in ('paper', 'purpur', 'spigot', 'craftbukkit'):
        server.execute('reload')
    else: server.restart()

@server.on_loop(interval=5, unit='second'):
    if addon._hash_changed(): reload()

Download example:

target = addon.find_addon('worldedit')
if target:
    installed = addon.download_addon(target)
    server.log(f'Installed {installed} successfully!')

List all installed add-ons:

for file in addon.return_single_list():
    log_type = 'success' if file.enabled else 'warning'
    server.log(f'{file.name} - {file.author} ({file.addon_version})', log_type)

Installed add-ons structure:

addon.installed_addons = {
     'enabled': [AddonFileObject, AddonFileObject, ...],
    'disabled': [AddonFileObject, AddonFileObject, ...]
}