# Getting Started

#### <mark style="color:blue;">Requirements</mark>

{% hint style="info" %}
Colyseus version 0.14 is currently used in OP Arcade
{% endhint %}

{% file src="/files/VMGsLSZIvGU3sfrjugge" %}
sandbox template that can be used as the base for the game integration
{% endfile %}

{% hint style="warning" %}
When using the Colyseus Arena, the <mark style="color:orange;"><mark style="color:purple;"><mark style="color:green;">`.env`<mark style="color:green;"><mark style="color:purple;"></mark> file has to be named <mark style="color:green;">`arena.env`</mark>, otherwise it won't be loaded
{% endhint %}

#### <mark style="color:blue;">**Different Modes are required for the game: Tournament and For Fun**</mark>

**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](https://blaze-racing.netlify.app/) 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](https://docs.unity3d.com/ScriptReference/Networking.UnityWebRequest.UnEscapeURL.html) if any.&#x20;
* `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`.&#x20;

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](https://docs.unity3d.com/ScriptReference/Networking.UnityWebRequest.UnEscapeURL.html) 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

<mark style="color:blue;">**How does our system work in Production?**</mark>

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.

{% hint style="info" %}
The full url to get the values from will be found in the `iframe` component of the website, [check next page](/colyseus-integration/arcadia-tournaments/getting-the-url-params.md) on how to get the values correctly
{% endhint %}

<figure><img src="/files/1uM61BB7nCN4DNDyrhcN" alt=""><figcaption></figcaption></figure>

Your game then passes it to Colyseus when calling joinOrCreate.

```csharp
// 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**:

```javascript
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);
        });
    }
```

#### <mark style="color:blue;">**Games should send a postMessage upon end of gameplay**</mark>

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

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.

{% hint style="info" %}
The message should send “end-round”. It informs the i-frame container parent of game completion such as below
{% endhint %}

```javascript
// 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](https://docs.unity3d.com/Manual/webgl-interactingwithbrowserscripting.html) for reference. Create first a script calling `window.parent.postmessage` and then call the script from within Unity.

#### <mark style="color:blue;">Implement the onAuth function</mark>

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](https://docs.colyseus.io/colyseus/server/room/)

For development, please make this onAuth function return `true`.

**Example of onAuth function**

```typescript
// 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;
  }
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://gitbook.arcadia.fun/colyseus-integration/arcadia-tournaments/getting-started.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.