Interface Utils

interface Utils {
    authFromKey(authKey: string): Promise<Auth>;
    authToNumber(auth: string): BigInt;
    byteArrayToIp(data: Uint8Array): string;
    calculateAllRoomDistances(geo: GeoLocation, list: RoomData[]): void;
    colorToNumber(color: string): number;
    compareBits(value1: number, value2: number, bitMask: number): boolean;
    compareBits(value1: BigInt, value2: BigInt, bitMask: BigInt): boolean;
    exportStadium(stadium: IStadium): string;
    generateAuth(): Promise<[string, Auth]>;
    generateRoomId(
        params: GenerateRoomIdParams,
    ): Promise<GenerateRoomIdReturnValue>;
    getDefaultStadiums(): IStadium[];
    getGeo(): Promise<GeoLocation>;
    getRoomList(): Promise<RoomData[]>;
    hexStrToNumber(str: string): string;
    ipToNumber(ip: string): number | BigInt | null;
    keyState(dirX: Direction, dirY: Direction, kick: boolean): number;
    numberToAuth(auth: BigInt): string;
    numberToColor(number: number): string;
    numberToIp(ip: number | BigInt): string | null;
    parseGeo(
        geoStr?: string | object,
        fallback?: object,
        retNull?: boolean,
    ): GeoLocation;
    parseStadium(textDataFromHbsFile: string): IStadium | undefined;
    promiseWithTimeout(promise: Promise<void>, msec: number): Promise<void>;
    refreshRoomToken(
        params: RefreshRoomTokenParams,
    ): Promise<RefreshRoomTokenReturnValue>;
    reverseKeyState(
        state: number,
    ): { dirX: Direction; dirY: Direction; kick: boolean };
    runAfterGameTick(callback: () => void, ticks: number): void;
}

Methods

authFromKey

authFromKey(authKey: string): Promise<Auth>

Recreates the auth object from the given authKey. The returned object is only to be used as parameter to the function Room.join. Bad inputs or any internal error will result in a rejected promise.

Parameters

authKey: string
A simplified string that represents an auth object.

Returns Promise<Auth>

The Auth object that was generated from the given authKey.

Example

function joinRoomWithOldAuth(roomId, authKey, playerName, playerAvatar){
  Utils.authFromKey(authKey).then((authObj)=>{
    Room.join({
      id: roomId,
    }, {
      storage: {
        player_name: playerName,
        avatar: playerAvatar,
        player_auth_key: authKey,
        // ...
      }, 
      authObj: authObj,
      // ...
      // other parameters here
      // ...
    });
  }, (error)=>{
    console.error("Wrong auth key.");
  });
}

authToNumber

authToNumber(auth: string): BigInt
Returns the numeric representation of the given auth string. Returns null if the length of the auth string is not 43.
Parameters
- auth: string
  The auth value to be converted.
Returns BigInt
A BigInt.
Example
```
console.log(Utils.authToNumber("abcabcabcabcabcabcabcabcabcabcabcabcabcabca"));
```

byteArrayToIp

byteArrayToIp(data: Uint8Array): string
Converts a Uint8Array that was read from the backend into a readable ip address string.
Parameters
- data: Uint8Array
  The data to be converted
Returns string
The recovered ip address string.

calculateAllRoomDistances

calculateAllRoomDistances(geo: GeoLocation, list: RoomData[]): void
Calculates the distances to the given GeoLocation geo of all rooms in given roomList and stores them inside each room's dist property.
Parameters
- geo: GeoLocation
  The location to calculate the distances to.
- list: RoomData[]
  The room list to update.
Returns void
void.
Example
```
function getRoomListSortedByDistanceToGeoLocation(geoLocation){
  return Utils.getRoomList().then((list)=>{
    calculateAllRoomDistances(geoLocation, list);
    list.sort((a, b) => (a.dist - b.dist));
    return list;
  });
}
```

colorToNumber

colorToNumber(color: string): number
Returns the number representation of the given html color string. (rgba representation) This function is mostly intended to be used in renderers and map editors.
- Bad inputs will return undefined.
- Alpha value of the input color is not used. (The game engine currently assigns 255 to all alpha values by default.)
Parameters
- color: string
  The rgba representation of a color.
Returns number
An integer that represents the given color.
Example
```
function createCustomSegment(x1, y1, x2, y2, curve, rgbColor){
  return room.state.createSegmentFromObj({
    v0: room.state.createVertex({x: x1, y: y1}),
    v1: room.state.createVertex({x: x2, y: y2}),
    curve: curve, 
    color: Utils.colorToNumber(rgbColor)
  });
}
```

compareBits

compareBits(value1: number, value2: number, bitMask: number): boolean
Compares the bits of value1 and value2 at the exact positions that are 1 in the given bitMask.
Parameters
- value1: number
  The first value to be compared.
- value2: number
  The second value to be compared.
- bitMask: number
  The bit mask that represents which bits to compare.
Returns boolean
A boolean whose value is true if all bits that are compared are equal.
Example
```
console.log(Utils.compareBits(10, 6, 2));
console.log(Utils.compareBits(10, 5, 2));
```
compareBits(value1: BigInt, value2: BigInt, bitMask: BigInt): boolean
Parameters
- value1: BigInt
- value2: BigInt
- bitMask: BigInt
Returns boolean

exportStadium

exportStadium(stadium: IStadium): string
Generate and return text content from a stadium object that can be directly written in a .hbs file.
Parameters
- stadium: IStadium
Returns string
The string(.hbs) representation of the stadium object.

generateAuth

generateAuth(): Promise<[string, Auth]>

Generates a new player_auth_key along with its companion auth object(authObj) to be used as parameters to the function Room.join. We should store the auth key and use it later if we want to be recognized in Mooball rooms. Any internal error will result in a rejected promise.

Returns Promise<[string, Auth]>

A new auth key and auth object.

Example

function joinRoomWithNewAuth(roomId, playerName, playerAvatar){
  Utils.generateAuth().then(([authKey, authObj])=>{
    Room.join({
      id: roomId,
    }, {
      storage: {
        player_name: playerName,
        avatar: playerAvatar,
        player_auth_key: authKey,
        // ...
      }, 
      authObj: authObj,
      // ...
      // other parameters here
      // ...
    });
  }
}

generateRoomId

generateRoomId(params: GenerateRoomIdParams): Promise<GenerateRoomIdReturnValue>
Generates and returns the room id corresponding to the given room token. This function also refreshes the room token and returns the new token.
Parameters
- params: GenerateRoomIdParams
  An object that might have the following keys:
  
  token: string: The room token.
  
  proxyAgent: object: A custom proxy agent to use for the connection. This method does not work in browsers. (Default value is null)
Returns Promise<GenerateRoomIdReturnValue>
A Promise that resolves to an object that contains roomId, (roomEndpoint) and newToken keys. The promise is rejected if an error occurs.

getDefaultStadiums

getDefaultStadiums(): IStadium[]

Returns the default stadium array.

Returns IStadium[]

All of the default stadiums as an array.

Example

function exportDefaultStadium(index){
  var allDefaultStadiums = Utils.getDefaultStadiums();
  return Utils.exportStadium(allDefaultStadiums[index]);
}

getGeo

getGeo(): Promise<GeoLocation>

Connects to moo-hoo.com, retrieves your location based on IP address using backend's geolocation API and returns it. Might throw errors.

Returns Promise<GeoLocation>

A promise that returns a GeoLocation object that has your location data retrieved from the backend server.

Example

function joinRoomWithNewAuthAndBackendGeo(roomId, playerName, playerAvatar){
  Utils.getGeo().then((geo)=>{
    Utils.generateAuth().then(([authKey, authObj])=>{
      Room.join({
        id: roomId,
      }, {
        storage: {
          player_name: playerName,
          avatar: playerAvatar,
          player_auth_key: authKey,
          geo: geo,
          // ...
        }, 
        authObj: authObj,
        // ...
        // other parameters here
        // ...
      });
    }
  }).catch((ex)=>{
    console.error("Error:", ex);
  });
}

getRoomList

getRoomList(): Promise<RoomData[]>
Connects to moo-hoo.com, retrieves the current room list and returns it.

Returns Promise<RoomData[]>
A promise that returns the current list of open public rooms returned from the moo-hoo.com.
Example
```
Utils.getRoomList().then((list)=>{
  list.forEach((room)=>{
    console.log(room);
  });
});
```

hexStrToNumber

hexStrToNumber(str: string): string
Converts the playerObject.conn values to readable ip address string.
Parameters
- str: string
  The string to be converted
Returns string
The converted ip address string.

ipToNumber

ipToNumber(ip: string): number | BigInt | null
Returns the numeric representation of the given ip address. Returns null if the input string is ill-formatted.
Parameters
- ip: string
  The ip address to be converted.
Returns number | BigInt | null
An integer for ipv4 string, a BigInt for ipv6 string.
Example
```
console.log(Utils.ipToNumber("8.8.8.8"));
console.log(Utils.ipToNumber("2001:0000:130f::09c0:876a:130b"));
```

keyState

keyState(dirX: Direction, dirY: Direction, kick: boolean): number
Returns an integer key state value, only to be used with Room.setKeyState.
Parameters
- dirX: Direction
  Desired x direction. One of [-1:left, 0:still, 1:right].
- dirY: Direction
  Desired y direction. One of [-1:up, 0:still, 1:down].
- kick: boolean
  Desired pressed state of the kick button.
Returns number
An integer in the range [0, 31].
Example
```
// This will be interpreted as pressing left direction key and kick key, and releasing all other keys.
room.setKeyState(Utils.keyState(-1, 0, true));
```

numberToAuth

numberToAuth(auth: BigInt): string
Returns the auth string for the numeric representation of it. Returns null if the input number is invalid.
Parameters
- auth: BigInt
  The numeric representation of an auth string to be converted.
Returns string
An auth string.
Example
```
console.log(Utils.numberToAuth(Utils.authToNumber("abcabcabcabcabcabcabcabcabcabcabcabcabcabca")));
```

numberToColor

numberToColor(number: number): string
Returns the html color string (rgba representation) of the given number. This function is mostly intended to be used in renderers and map editors. Bad inputs will return a bad string output.
Parameters
- number: number
  A number in the range [0, 16777215].
Returns string
The rgba representation of the color that was generated from the given number.
Example
```
function drawTextWithColor(canvas, x, y, text, color){
  var ctx = canvas.getContext("2d");
  ctx.fillStyle = Utils.numberToColor(color);
  ctx.fillText(text, x, y);
  return canvas;
}
```

numberToIp

numberToIp(ip: number | BigInt): string | null
Returns the ip address string of a given numeric representation. Returns null if the input number is invalid.
Parameters
- ip: number | BigInt
  The numeric representation of an ip address to be converted.
Returns string | null
A formatted ip string.
Example
```
console.log(Utils.numberToIp(Utils.ipToNumber("8.8.8.8")));
console.log(Utils.numberToIp(Utils.ipToNumber("2001:0000:130f::09c0:876a:130b")));
```

parseGeo

parseGeo(
    geoStr?: string | object,
    fallback?: object,
    retNull?: boolean,
): GeoLocation
Parses the given string or json object as a GeoLocation object and returns it.
Parameters
- OptionalgeoStr: string | object
  An (optionally stringified) object that may have the following keys:
  
  lat: Latitude value.
  
  lon: Longitude value.
  
  flag: Country code.
- Optionalfallback: object
  An object whose keys will be used as fallback if the first parameter does not have any of the requested key(s). It should have lat, lon, flag as well.
- OptionalretNull: boolean
  Whether to return null if geoStr is null. Defaults to true.
Returns GeoLocation
A GeoLocation object.

parseStadium

parseStadium(textDataFromHbsFile: string): IStadium | undefined

Parses a string(.hbs) as a Stadium object.

Parameters

textDataFromHbsFile: string
The string representation of a Stadium object.

Returns IStadium | undefined

The generated Stadium object, or undefined if an error occurs.

Example

function changeStadium(room, fileObj){
  var fr = new FileReader();
  fr.onload = function(){
    try{
      room.setCurrentStadium(Utils.parseStadium(fr.result));
    }
    catch(ex){
      console.log(ex.toString());
    }
  };
  fr.readAsText(fileObj);
}

promiseWithTimeout

promiseWithTimeout(promise: Promise<void>, msec: number): Promise<void>
Returns a new promise that executes the given promise until msec milliseconds have passed. If timeout is reached, the promise is rejected.
Parameters
- promise: Promise<void>
  A Promise that has to be executed with a time limit
- msec: number
  The time limit
Returns Promise<void>
The new promise with time limit.

refreshRoomToken

refreshRoomToken(
params: RefreshRoomTokenParams,
): Promise<RefreshRoomTokenReturnValue>
Generates a new room token from an old room token OR a rcr(recaptcha response) value.
Parameters
- params: RefreshRoomTokenParams
  An object that might have the following keys:
  
  token: string: The old room token. (Default value is "")
  
  rcr: string: The recaptcha response value received from Google Recaptcha v2 API. (Default value is "")
Returns Promise<RefreshRoomTokenReturnValue>
A Promise that resolves to an object that contains code and value keys. code can be 0, 1 or 2. Possible scenarios are as follows:
- If code = 0; The token value was accepted and value contains the new room token.
- If code = 1; The token value was rejected and value contains the sitekey value that is required by Google Recaptcha v2 API to show recaptcha inside a website.
- If code = 2; An error occurred while sending request or receiving response and value contains the error.

reverseKeyState

reverseKeyState(
state: number,
): { dirX: Direction; dirY: Direction; kick: boolean }
Returns the explanation of the given key state.
Parameters
- state: number
  A key state value in the range [0, 31].
Returns { dirX: Direction; dirY: Direction; kick: boolean }
An object that holds values for x, y directions and kick.
Example
```
console.log(Utils.reverseKeyState(3));
```

runAfterGameTick

runAfterGameTick(callback: () => void, ticks: number): void
Runs a callback function after ticks game ticks.
Parameters
- callback: () => void
  The function to run.
- ticks: number
  Number of ticks to wait before running the callback function. Defaults to 1.
Returns void
void.
Example
```
Utils.runAfterGameTick(()=>{
  console.log("This code will run after 3 game ticks.");
}, 3);
```

Interface Utils

Index

Methods

Methods

authFromKey

Parameters

Returns Promise<Auth>

Example

authToNumber

Parameters

Returns BigInt

Example

byteArrayToIp

Parameters

Returns string

calculateAllRoomDistances

Parameters

Returns void

Example

colorToNumber

Parameters

Returns number

Example

compareBits

Parameters

Returns boolean

Example

Parameters

Returns boolean

exportStadium

Parameters

Returns string

generateAuth

Returns Promise<[string, Auth]>

Example

generateRoomId

Parameters

Returns Promise<GenerateRoomIdReturnValue>

getDefaultStadiums

Returns IStadium[]

Example

getGeo

Returns Promise<GeoLocation>

Example

getRoomList

Returns Promise<RoomData[]>

Example

hexStrToNumber

Parameters

Returns string

ipToNumber

Parameters

Returns number | BigInt | null

Example

keyState

Parameters

Returns number

Example

numberToAuth

Parameters

Returns string

Example

numberToColor

Parameters

Returns string

Example

numberToIp

Parameters

Returns string | null

Example

parseGeo

Parameters

Returns GeoLocation

parseStadium

Parameters

Returns IStadium | undefined

Example

promiseWithTimeout

Parameters

Returns Promise<void>