Getting Started

Requirements

Colyseus version 0.14 is currently used in OP Arcade

170KB

colyseus-sandbox-template.zip

archive

sandbox template that can be used as the base for the game integration

When using the Colyseus Arena, the .env file has to be named arena.env, otherwise it won't be loaded

Different Modes are required for the game: Tournament and For Fun

For Fun - this is the easier version to build as it does not require to be secure

Since no tournament is involved all the logic of the game can be handled on the client side and Colyseus integration is not needed

We need to host the build version of the game on an external url, then OP Arcade website will point a reference to the link, check our Blaze Racing Netlify URL and have a little fun 🚘 In case the game build needs any of the player's informations, the following parameters are sent from OP Arcade

• displayname — current name of the logged in user. Name will be urlencoded so will need some additional processing to remove escape characters if any.

• image_url — avatar image url of the logged in user

• wallet_address — wallet address of currently logged in user

Tournament - The game logic and score posting is done on Colyseus server, this requires for the game build to be modified in certain areas.

The OP Arcade system sends the following parameters when launching in Tournament Mode.

The first 3 parameters are required to be passed to Colyseus upon client creation:

• playerid

• otp

• tourneyid

Other parameters are also sent by OP Arcade, these are optional and can be used if needed:

• displayname — current name of the logged in user. Name will be urlencoded so will need some additional processing to remove escape characters if any.
• image_url — avatar image url of the logged in user

• wallet_address — wallet address of currently logged in user

How does our system work in Production?

In production, the OPArcade system passes the above parameters on launch by sending a GET request to your hosted game.

The url will have the following structure, it will only show the tournament id param.

The full url to get the values from will be found in the iframe component of the website, check next page on how to get the values correctly

Your game then passes it to Colyseus when calling joinOrCreate.

// Sample parsing inside Unity Code — using Application.absoluteURL

string launchParams = Application.absoluteURL.split("?"[0])[1];
Debug.log(launchParams);

string[] parameters = launchParams.Split(char.Parse("&"));

foreach (string param in parameters)
{
    Debug.Log(param);
}

• For the sake of development, these can be any value for now and will be manually adjusted by the OPArcade team prior to release.

• These three parameters must be made available when connecting to Colyseus as they will be used in checking authorised gameplay on our servers.

Example below:

join():Promise<void> {
        return new Promise((resolve, reject) => {
            this.client
                .joinOrCreate<ITriskaState>('triska_room', {
                    playerId: this.playerId,
                    token: this.otp,
                    tourneyId: this.tourneyId,
                    sessionId: this.sessionId,
                    walletAddress: this.wallet_address //optional - useful if game will be using player NFT's

                })
                .then((room) => {
                    this.room = room;
                    this.processRoomMessages(this.room);

                    resolve();
                })
                .catch(reject);
        });
    }

Games should send a postMessage upon end of gameplay

In order for OP Arcade to understand that the tournament round has ended we need to inform the website of this event.

A common example of when this message should be sent is when the player dies in the game or when a match between two players has ended with a winner.

The message should send “end-round”. It informs the i-frame container parent of game completion such as below

// Send end-round message to OP Arcade

window.parent.postMessage("end-round", "https://test.outplay.games");

In case you are integrating with unity, please look at the following for reference. Create first a script calling window.parent.postmessage and then call the script from within Unity.

Implement the onAuth function

To implement the onAuth function we need to ensure that playerId, token, tourneyId are passed to the onAuth function

Check how to implement on the Colyseus documentation

For development, please make this onAuth function return true.

Example of onAuth function

// Authorize client based on provided options before WebSocket handshake is complete
  async onAuth(client, options) {
    this.playerId = options.playerId; //double check
    this.tourneyId = options.tourneyId; //double check
    this.token = options.otp; //double check
    this.walletAddress = options.wallet_address; //optional //double check

    if (this.playerId && this.tourneyId && this.token) {
	    // just return true here when developing
      return await this.api.validateOtp(this.playerId, this.tourneyId, this.token);
    }

    return false;
  }