new PluginManager()

PluginManager class, core of the HHM system.

Description

PluginManager class, core of the HHM system.

This class is responsible for managing the plugin and room lifecycle, like dependency management and plugin configuration.

Properties
Name Type Description
dependencies Object.<string, Array.<number>>

This caches reverse dependencies, i.e. it's mapping a plugin name to an array of plugin IDs which depend on it.

Methods


<private> _addDependent( pluginId, dependentName )

Adds a dependent to the dependencies of the given plugin.

Description

Adds a dependent to the dependencies of the given plugin.

This means that the plugin pluginId depends on the plugin dependentName.

Parameters
Name Type Description
pluginId number

ID of the depending plugin.

dependentName string

Name of the plugin that's being dependent on.


<private> _addPlugin( [ pluginName [, pluginCode [, loadStack ] ] ] ) → {Promise.<(number|Array.<number>)>}

Adds a plugin by name or by code, and returns the ID of the loaded plugin or -1 if there was an error, or the loadStack if it was given.

Description

Adds a plugin by name or by code, and returns the ID of the loaded plugin or -1 if there was an error, or the loadStack if it was given.

This function recursively loads a plugin and its dependencies and passes a load stack around which contains IDs of loaded plugins in the load order.

When initially calling this function, do not pass a loadStack, the function will then return the ID of the loaded plugin or -1 if there was an error.

Parameters
Name Type Attributes Description
pluginName string <optional>

Name of the plugin, set to undefined if you want to load a plugin by code.

pluginCode function | string <optional>

Plugin code as Function or string.

loadStack Array.<number> <optional>

Array of loaded plugin IDs in load order. Used internally during recursion.

Returns

When called without a loadStack, it will return the plugin ID or -1 if the plugin failed to load, otherwise it will return the updated loadStack.


<private> _checkPluginAndLoadDependencies( pluginId, loadStack )

Checks whether the given plugin is loaded and loads its dependencies.

Description

Checks whether the given plugin is loaded and loads its dependencies.

In case of any errors, the returned array will contain one or more false entries.

TODO return only false on error?

Parameters
Name Type Description
pluginId number

ID of the plugin.

loadStack Array.<number>

Array of loaded plugin IDs

Returns

Promise<Array.> Updated loadStack Array, boolean false indicates an error during plugin load, meaning all loaded plugins will be removed.


<private> _checkPluginsCompatible() → {boolean}

Checks whether incompatible plugins have been loaded.

Description

Checks whether incompatible plugins have been loaded.

Returns

true if all plugins are compatible with each other, false otherwise


<private> _createDependencyChain( dependencyId, alreadyInChain ) → {string}

Recursively creates a dependency chain for the given dependency.

Description

Recursively creates a dependency chain for the given dependency.

Strictly for logging purposes.

Parameters
Name Type Description
dependencyId number

ID for which to create a dependency chain.

alreadyInChain Array.<number>

To avoid endless recursion, the dependencies already processed are passed along in this Array.

Returns

Dependency chain as a newline-separated string, one line for each dependency, of the format "X required by Y".


<private> _enablePluginAndDependencies( pluginId, enabledPlugins ) → {boolean}

Recursively enables the given plugin and its dependencies.

Description

Recursively enables the given plugin and its dependencies.

Parameters
Name Type Description
pluginId number

ID of the plugin to be enabled.

enabledPlugins Array.<number>

Already enabled plugins, to disable endless recursion.

Returns

false if the plugin and its dependencies were already enabled, true otherwise.


<private> _executeRoomLinkHandlers( loadStack )

Executes the room link handlers of newly loaded plugins.

Description

Executes the room link handlers of newly loaded plugins.

After the onRoomLink handler execution order has been determined, handlers / events will be executed / triggered in this order:

  • onRoomLink handler on the plugin
  • beforePluginLoaded HHM event
  • plugin is then marked as loaded an can process events
  • pluginLoaded HHM event
Parameters
Name Type Description
loadStack Array.<number>

Array of plugin IDs.


_initializeCoreEventHandlers()

Adds event handlers which must be in place before any plugin is loaded.

Description

Adds event handlers which must be in place before any plugin is loaded.

Registers an initial onRoomLink handler which will be removed once it has been executed.


<private> _loadUserPlugins() → {Promise.<boolean>}

Loads the plugins defined in the user config.

Description

Loads the plugins defined in the user config.

Returns

Whether loading the user plugins was successful.


<private> _mergeConfig( pluginName, config )

Merges the given configuration into the configuration for the given plugin.

Description

Merges the given configuration into the configuration for the given plugin.

Parameters
Name Type Description
pluginName string

Name of the plugin.

config Object.<string, *>

Plugin configuration to be merged in.


<private> _postInit() → {Promise.<boolean>}

Executes the postInit code from the config if any.

Description

Executes the postInit code from the config if any.

Returns

Whether executing the postInit code was successful.


<private> _removePlugin( pluginId ) → {boolean}

Removes the room proxy for the given plugin.

Description

Removes the room proxy for the given plugin.

Parameters
Name Type Description
pluginId number

ID of the plugin to be removed.

Returns

Whether the removal was successful.


<private, static> _triggerEventOnRoom( room, eventHandlerName, args )

Triggers an event for the given room.

Description

Triggers an event for the given room.

Parameters
Name Type Description
room external:native-api.RoomObject

Room on which the event handler will be called.

eventHandlerName string

Name of the event handler.

args Array.<*>

Event handler arguments.


addPluginByName( pluginName ) → {number}

Loads the plugin for the given name and its dependencies.

Description

Loads the plugin for the given name and its dependencies.

Parameters
Name Type Description
pluginName string

Name of the plugin.

Returns

Plugin ID if the plugin and all of its dependencies have been loaded, -1 otherwise.


addPluginByCode( pluginCode, pluginName ) → {number}

Loads the plugin and its dependencies from the given code.

Description

Loads the plugin and its dependencies from the given code.

If you specify a plugin name, it can be overwritten from the loaded plugin code.

Parameters
Name Type Description
pluginCode function | string

Plugin code as Function or string.

pluginName string

Name of the plugin.

Returns

Plugin ID if the plugin and all of its dependencies have been loaded, -1 otherwise.


addRepository( repository [, append ] ) → {boolean}

Adds a plugin repository.

Description

Adds a plugin repository.

Convenience wrapper around PluginLoader#addRepository.

Parameters
Name Type Attributes Description
repository string | Object

The repository to be added, as string or Object.

append boolean <optional>

Whether to append or prepend the repository to the Array of repositories.

Returns

Whether the repository was successfully added.


disablePluginById( pluginId ) → {boolean}

Disables the plugin with the given ID.

Description

Disables the plugin with the given ID.

Before calling this, make sure the plugin can be disabled (i.e. all dependents have been disabled).

Parameters
Name Type Description
pluginId number

Plugin ID.

Returns

true if the plugin has been or was already disabled, false otherwise.


enablePluginById( pluginId ) → {boolean}

Enables the given plugin and its dependencies.

Description

Enables the given plugin and its dependencies.

Parameters
Name Type Description
pluginId number

Plugin ID.

Returns

true if any plugin was enabled, false otherwise.


getDependentPluginsById( pluginId [, recursive [, includeDisabled [, dependents ] ] ] ) → {Array.<number>}

Returns an Array of plugins that depend on the plugin with the given ID.

Description

Returns an Array of plugins that depend on the plugin with the given ID.

Parameters
Name Type Attributes Description
pluginId number

Plugins depending on this plugin will be returned.

recursive boolean <optional>

Whether to recursively plugins that indirectly depend on the given plugin.

includeDisabled boolean <optional>

Whether to include disabled dependencies.

dependents Set <optional>

Used internally to avoid endless recursion.

Returns

Array of plugin IDs which depend on the given pluginId.


getEnabledPluginIds() → {Array.<number>}

Returns an Array of plugin IDs for currently enabled plugins.

Description

Returns an Array of plugin IDs for currently enabled plugins.

Note that his only returns plugins which are fully loaded.

Returns

Enabled plugin IDs.


getHandlerNames() → {Array.<string>}

Returns an Array of all registered handler names.

Description

Returns an Array of all registered handler names.

Returns

Registered handler names.


getLoadedPluginIds() → {Array.<number>}

Returns an Array of loaded plugin IDs.

Description

Returns an Array of loaded plugin IDs.

Returns

Loaded plugin IDs.


getPluginById( pluginId ) → {external:haxball-room-trapper.TrappedRoom}

Returns the plugin for the given ID or undefined if no such plugin exists.

Description

Returns the plugin for the given ID or undefined if no such plugin exists.

Parameters
Name Type Description
pluginId number

Plugin ID.

Returns

getPluginByName( [ pluginName [, create ] ] ) → {external:haxball-room-trapper.TrappedRoom|undefined}

Returns the trapped room for the given plugin.

Description

Returns the trapped room for the given plugin.

Parameters
Name Type Attributes Description
pluginName string <optional>

Name of the plugin or undefined to create new plugin.

create boolean <optional>

true if a new plugin should be created if it does not exist. If no pluginName was given, this parameter is ignored and a new plugin is created.

Returns

Plugin room proxy or undefined if the plugin was not found and create is false.


<static> getPluginDependencies( pluginId [, recursive [, ids ] ] ) → {Array.<string>}

Returns a list of plugin dependencies.

Description

Returns a list of plugin dependencies.

Parameters
Name Type Attributes Description
pluginId number

Dependencies of this plugin are returned.

recursive boolean <optional>

Whether to return dependencies recursively, or only direct dependencies

ids boolean <optional>

Whether to return IDs instead of names.

Returns

Plugin names or IDs of dependencies of the given plugin.

Details

convert boolean parameters to destructuring


getPluginId( pluginName ) → {number}

Returns the ID for the given plugin, or -1 if the plugin does not exist.

Description

Returns the ID for the given plugin, or -1 if the plugin does not exist.

Parameters
Name Type Description
pluginName string

Name of the plugin.

Returns

Plugin ID for the plugin with the given name, or -1 if no such plugin exists.


getPluginLoader() → {PluginLoader}

Returns the plugin loader of this plugin manager.

Description

Returns the plugin loader of this plugin manager.

Returns

Associated plugin loader.


getPluginName( pluginId ) → {string|number}

Returns the plugin name for the given ID or the ID if the plugin has no associated name.

Description

Returns the plugin name for the given ID or the ID if the plugin has no associated name.

Parameters
Name Type Description
pluginId number

ID of the plugin.

Returns

Name of the plugin or ID if the plugin has no name.


getRoomManager() → {TrappedRoomManager}

Returns the trapped room manager.

Description

Returns the trapped room manager.

Returns

Trapped room manager of this plugin manager.


hasPluginById( pluginId ) → {boolean}

Returns true if a plugin with the given ID exists and is valid, false otherwise.

Description

Returns true if a plugin with the given ID exists and is valid, false otherwise.

A plugin is valid if HBInit() has been called and no error happened during plugin execution.

Parameters
Name Type Description
pluginId number

ID of the plugin.

Returns

Whether a plugin with the given ID exists and is valid.


hasPluginByName( pluginName ) → {boolean}

Returns true if the plugin with the given name exists and is valid, false otherwise.

Description

Returns true if the plugin with the given name exists and is valid, false otherwise.

Parameters
Name Type Description
pluginName string

Name of the plugin.

Returns

Whether a plugin with the given name exists and is valid.


isPluginRequired( pluginId )

Returns true if the plugin is required, false otherwise.

Description

Returns true if the plugin is required, false otherwise.

A plugin is required if a plugin that is not disabled depends on it.

Parameters
Name Type Description
pluginId number

ID of the plugin.

Returns

Whether an enabled plugin depends on this plugin.

Details

change implementation so that this checks whether the plugin can be disabled at all, i.e. whether it depends on itself or if one of its dependents depends on itself


<private> _provideRoom( [ room ] ) → {HhmRoomObject}

Provides a room object.

Description

Provides a room object.

If no room object was provided, create a new room based on the HHM.config.room configuration, or use an empty object if HHM.config.dryRun is true.

The resulting room object is then extended with some basic HHM functionality like access to plugins.

Parameters
Name Type Attributes Description
room external:native-api.RoomObject <optional>
Returns

Extended room object.

Details

split into provideRoom and decorateRoom or something?


setPluginConfig( pluginId [, paramName [, value ] ] )

Sets the given config parameter of the given plugin to the given value.

Description

Sets the given config parameter of the given plugin to the given value.

If no parameter name was given, an event will be triggered that the configuration was changed.

If an object is passed as the paramName, the whole config will be overwritten and an event will be triggered.

Parameters
Name Type Attributes Description
pluginId number

Plugin ID.

paramName string <optional>

Name of the configuration parameter.

value * <optional>

New value of the configuration parameter.


triggerEvent( eventHandlerName, ...args ) → {boolean}

Triggers an event with the given handler name and arguments.

Description

Triggers an event with the given handler name and arguments.

Calling an event handler directly will only execute the current plugin's event handler, while using this function will trigger all handlers for the given event. To trigger an event, simply use its event handler name.

Can also be (ab)used to trigger native events.

Parameters
Name Type Attributes Description
eventHandlerName string

Name of the event handler to be triggered.

args * <repeatable>

Event arguments.

Returns

false if one of the event handlers returned false, true otherwise.

Details

triggerHhmEvent( [ eventName [, args ] ] )

Trigger an HHM event.

Description

Trigger an HHM event.

Parameters
Name Type Attributes Description
eventName string <optional>

Name of the event.

args Object <optional>

Event arguments.

Details

documentation, make private?


triggerLocalEvent( plugin, eventHandlerName [, ...args ] )

Triggers an event only for the given plugin.

Description

Triggers an event only for the given plugin.

A corresponding HHM event will be triggered as well.

Parameters
Name Type Attributes Description
plugin external:haxball-room-trapper.TrappedRoom

Plugin room proxy.

eventHandlerName string

Name of the event handler.

args * <optional>
<repeatable>

Event arguments.

Details

make private?


start( [ room ] ) → {HhmRoomObject}

Starts the HHM plugin manager.

Description

Starts the HHM plugin manager.

If a room was provided, it will be used, otherwise a new room will be created. If no room and no room config was provided, the start will be aborted.

Parameters
Name Type Attributes Description
room external:native-api.RoomObject <optional>

Existing room object.

Returns

Extended or newly created room object.