initialization

Our library constructor takes two object parameters:

libraryConstructor(object: WindowLike, config: LibConfig)

The first parameter: object: WindowLike

This parameter is added only for customizations inside some custom environments like NW.js, or special cases. You should usually pass window directly here. It requires the following data structure:

type WindowLike = {
  setTimeout: (callback: function, ms?: number, ...args: any[])=>number,
  clearTimeout: (handle: number)=>void,
  setInterval: (callback: function, ms?: number, ...args: any[])=>number, 
  clearInterval: (handle: number)=>void, 
  requestAnimationFrame: (callback: function, ...args: any[])=>number, 
  cancelAnimationFrame: (handle: number)=>void,
  console: ConsoleLike, 
  performance: PerformanceLike, 
  crypto: CryptoLike,
  RTCPeerConnection: RTCPeerConnectionLike,
  RTCIceCandidate: RTCIceCandidateLike,
  RTCSessionDescription: RTCSessionDescriptionLike,
  WebSocket: WebSocketLike,
  XMLHttpRequest: XMLHttpRequestLike,
  JSON5: JSON5Like,
  pako: pakoLike
};

• JSON5 and pako objects are obtained using JSON5 and pako libraries. This is done automatically in our library's npm package, but you can still customize it however you like. They are used internally by Haxball mostly for IO operations. All of the other objects exist in the window object of all browser environments.

• For custom environments like NW.js; you might have to bind all functions inside window object to window before sending them to the library, like this:

  var bindedSetTimeout = window.setTimeout.bind(window);

The second parameter: config: LibConfig

This parameter defines the main configuration for the library. It requires the following data structure:

type LibConfig = {
  backend: {
    hostname: string = 'www.haxball.com',
    hostnameWs: string = 'p2p.haxball.com',
    secure: boolean = true
  },
  proxy: {
    WebSocketChangeOriginAllowed: boolean = false,
    WebSocketUrl: string = 'wss://p2p.haxball.com/',
    HttpUrl: string = 'https://www.haxball.com/rs/'
  },
  proxyAgent: ProxyAgentLike = null,
  version: number = 9,
  noVariableValueChangeEvent: boolean = false,
  noWebRTC: boolean = false,
  stunServer: string = "stun:stun.l.google.com:19302",
  identityToken: string = null
}

• backend object defines the backend to communicate with. If you have a custom backend server, you can directly connect to it by changing these values. (Meanwhile, our custom backend project is also almost ready.)

• proxy object defines the properties of a proxy server. You can change the default endpoints to fit your own proxy server here.

  • WebSocket libraries inside browsers do not allow origin change for security reasons, so we need a proxy server to change the websocket request's origin for us. In custom environments like NW.js where origin change is allowed, we do not need to use a proxy server. In such cases, WebSocketChangeOriginAllowed can be true.
  • WebSocketUrl and HttpUrl both should always end with a trailing /. They are appended host or client at the end while being used.

• proxyAgent is any http(s)/socks5 proxy agent that you can use with this api. Does not work in browsers. Applies to the websocket connections while using Room.create and Room.join if these functions are not called with their own proxyAgent parameters.

• version is Haxball's expected version number. Beware that if you change this, you might not be able to join Haxball rooms due to version mismatch, and other people might not join your rooms with the same reason. This is designed for complete custom Haxball websites to which you can invite lots of people, and nobody else can join the created room from normal clients.

• noVariableValueChangeEvent; if true, disables the mechanism that enables variable value change event which in turn improves performance while reaching a variable's value that was defined by any Addon.defineVariable function. (Variable will have a directly accessable, actual value; instead of a property that points to the actual variable.)

• noWebRTC; if true, skips the WebRTC initialization. Needed to be able to use the API functions that are not related to networking in environments without WebRTC support. Defaults to: false.

• stunServer: The url address of an external stun server that is required for the communication via WebRTC to work correctly. Defaults to: stun:stun.l.google.com:19302.

• identityToken: A token that represents a user data in a database of a custom proxy/backend server. Defaults to null.