This class defines a Library object to be used inside a Haxball room. You may use the Library objects from inside other Addons.

Defines these functions that has to exist in every Library:

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

  This function is called internally inside the constructor of all Library's by default. The function body is empty by default. This means that the metadata values are not stored in Library 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 RoomConfigs.

  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:
    • version: number: The current version number of this Library.
    • author: string: The author of this Library.
    • description: string: A detailed description of this Library.

  Return value: None.

  Default definition (in node.js):

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

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

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

• Library.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)

  Return value: The initial value of this variable.

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

  Library.prototype.defineMetadata = function(metadata){
    //...do other stuff...
    this.variables = {}; // define an object that will hold all variable details inside all Libraries.
  };
  var originalDefineVariable = Library.prototype.defineVariable;
  Library.prototype.defineVariable = function(variable){
    //...do other stuff...
    originalDefineVariable(variable);
    this.variables[variable.name] = { // store all variable details inside all Libraries, 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 Library instance.

• name: string: Name of the Library. Every Library should have a unique name, since they can be accessed directly by their names from inside a Room object.
• metadata: object: Any information that we would want to show/update inside a GUI application about this Library. This is not used by the API by default, but we can reprogram the Library's prototype to make use of this value if we want. (For instructions, see section 1.)

Example Library definition:

// If you are using require.js library or in node.js, 
// API might also be defined via var API = require("node-haxball");
function TestLibrary(API){ 
  const { Library } = API;
  Object.setPrototypeOf(this, Library.prototype);
  Library.call(this, "testLibrary", { // this is the call to the constructor.
    version: 0.1,
    author: "author",
    description: `This is a test library`
  });
  // Custom Library codes here...
}

• room: Room: The Room object that this Library is attached to.

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

• initialize(): void

  If defined, called while creating or joining a room, or during a call to Room.updateLibrary. 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.updateLibrary. We should write all custom finalization logic inside this callback function.

  Parameters: None

  Return value: void