This class defines a Plugin object to be used inside a Haxball room. A Plugin is a piece of code that can be activated/deactivated and, when activated, enchances the current capabilities of the software or does some specific/extra tasks while still being capable of the software's original functionalities.

• Plugin.addonType: This will always return the value of AddonType.Plugin. This value can be useful for checks while importing addons from files etc. Example workflow of importing addons:

  1- Read the file contents. 2- Execute it and expect a function as the result. 3- Execute the function with the new keyword and get an instance of the addon. 4- Check addonInstance.__proto__.constructor.addonType value to see whether the type of addon is correct. 5- Store the object somewhere and use it when you are creating/joining a room.

Defines these functions that has to exist in every Plugin:

• Plugin.prototype.defineMetadata(metadata: object): void

  This function is called internally inside the constructor of all Plugins by default. The function body is empty by default. This means that the metadata values are not stored in Plugin objects by default, because they are not useful in a non-GUI node.js environment. If we want to make use of the metadata, we might override this behavior by overriding this method. Remember that this should be done after initializing the API and before initializing any Plugins.

  Parameters:

  • metadata: object: An object that holds some metadata values. This value might depend on what you want to do with this API. The examples in the GitHub repo are intended to be shown in a web application GUI that can be accessed by anyone. Therefore, they use the following structure for this object:
    • name: string: Name of the RoomConfig that will be displayed on the GUI.
    • version: number: The current version number of this RoomConfig.
    • author: string: The author of this RoomConfig.
    • description: string: A detailed description of this RoomConfig.
    • allowFlags: int: This value defines whether it is possible to use this RoomConfig while hosting or joining (or both) a room.

  Return value: None.

  Default definition (in node.js):

  Plugin.prototype.defineMetadata = function(metadata){};

  Example (default) definition (in a complex website):

  Plugin.prototype.defineMetadata = function(metadata){
    this.metadata = metadata;
  };

• Plugin.prototype.setVariableGUIProps(varName: string, ...vals: ({name: string, value: any})[]): void

  This function might be used to modify some GUI properties regarding a specific variable called varName. The function body is empty by default, since we do not have a GUI in a non-GUI node.js environment. All other parameters after the first parameter should be structured as {name: propName, value: propValue}. Here, each property named propName is requested to set its new value to propValue. For example; in a GUI environment, setVariableGUIProps("testVariable", {name: "visible", value: false}) could make the testVariable disappear from the GUI.

  Parameters:

  • varName: string: The name of the variable whose GUI properties are desired to be modified.
  • ...vals: ({name: string, value: any})[]: The property name/value pairs.

  Return value: None.

• Plugin.prototype.defineVariable(variableObj: Variable): void

  This function defines a variable inside the Addon object that can be changed from outside. If we want to make use of the metadata that we sent into this function, we can override this function. Only name and value fields are used by the default implementation. The implementation also depends on the API's global config.noVariableValueChangeEvent variable.

  Parameters:

  • variableObj: Variable: An object that might hold some metadata values along with the variable's name and value. This object might depend on what you want to do with this API. The examples in the GitHub repo are intended to be shown in a web application GUI that can be accessed by anyone. Therefore, the following structure is used for this object:
    • name: string: Name of the variable.
    • value: any: The default/initial value of this variable.
    • type: VariableType: Type of this variable. (omittable)
    • description: string: A detailed description of this variable. (omittable)
    • range: object: The possible range of this variable's value. Should only be applied to numbers(literally) and maybe strings(for min and max length of the string). (omittable)
      • min: number: The minimum value for this variable. (omittable)
      • max: number: The maximum value for this variable. (omittable)
      • step: number: The step increment/decrement for this variable. (for easy increment/decrement via a spinbox) (omittable)

  NOTE: This function is called internally inside the constructor of all Plugins just once by default to create the boolean variable active using the below code:

  this.defineVariable({
    name: "active",
    description: "Whether this plugin is active or not.", 
    type: VariableType.Boolean,
    value: active
  });

  Return value: The initial value of this variable.

  Example (default) definition (in a complex website):

  Plugin.prototype.defineMetadata = function(metadata){
    //...do other stuff...
    this.variables = {}; // define an object that will hold all variable details inside all Plugins.
  };
  var originalDefineVariable = Plugin.prototype.defineVariable;
  Plugin.prototype.defineVariable = function(variable){
    //...do other stuff...
    originalDefineVariable(variable);
    this.variables[variable.name] = { // store all variable details inside all Plugins, so that you can show them later in your GUI application if you want to.
      type: variable.type, 
      range: variable.range, 
      description: variable.description
    };
    //...do other stuff...
  };

Creates a new Plugin instance.

• name: string: Name of the Plugin. Every Plugin should have a unique name, since they can be accessed directly by their names from inside a Room object.
• active: boolean: Activation status of the Plugin. If this is true, the Plugin is automatically activated just after initialization, while a Room object is being created.
• metadata: Any information that we would want to show/update inside a GUI application about this Plugin. This is not used by the API by default, but we can reprogram the Plugin's prototype to make use of this value if we want.

Example Plugin definition:

function TestPlugin(API){
  const { Plugin, AllowFlags } = API;
  Object.setPrototypeOf(this, Plugin.prototype);
  Plugin.call(this, "template", true, {
    version: "0.1",
    author: "author",
    description: `This is a test plugin`,
    allowFlags: AllowFlags.CreateRoom|AllowFlags.JoinRoom
  });
  // Plugin codes here...
}

• name: string: Name of the Plugin. Should be unique and constant.
• active: boolean: Activation status of the Plugin. We should use Room.setPluginActive(plugin, value) if we need to change this value later.
• room: Room: The Room object that this Plugin is attached to.

The API can work with the following callback functions inside a Plugin object.

• initialize(): void

  If defined, called while creating or joining a room, or during a call to Room.updatePlugin. You should write all custom initialization logic inside this callback function.

  Parameters: None

  Return value: void

• finalize(): void

  If defined, called while leaving a room, or during a call to Room.updatePlugin. We should write all custom finalization logic inside this callback function.

  Parameters: None

  Return value: void

• Common Callbacks

  A Plugin calls all common callbacks by prepending on before the callback's name. As an example; if the common callback is RoomPropertiesChange(props: object), it is called as customData = onRoomPropertiesChange(props: object, customData: object) here.

  We have to select the callbacks that we want to use and prepend on to their name while defining them in our Plugin. All of these callbacks may also take an extra customData parameter that is passed from the previously called callback and may also return a new customData object to the next callback in the callback queue. This is done to be able to better communicate between API components.

  NOTE: To use the modifier callbacks(except onOperationReceived, which is just like the other callbacks) in Plugin classes, we do not prepend on, we directly define them inside Plugin classes.

  Example: Here is how we can write the code to add a RoomPropertiesChange callback to our Plugin:

  this.onRoomPropertiesChange = function(props, customData){
    // callback code here...
    // return customData; // you can return whatever you want here
  }

  You can see the complete list of common callbacks here.