Win SDK

Win is a play-to-earn mobile gaming platform powered by the blockchain that enables players to compete in skill-based games. The core component is the Win SDK, which allows developers to instantly deploy crypto rewards into any mobile game with just two lines of code to transform it into a competitive multiplayer experience for Web3.

Prerequisites

Sign Up For a Developer Account

To integrate the Win HTML5 SDK, you must first create an account on the Win Developer Console.

Get Your Game ID

Your Win Game ID is used to identify your game on the platform. Once you have your Game ID, you can immediately start developing the game. To receive your Game ID, add a new game project via the Win Developer Console. After providing some basic details about your game, you can find your Game ID in the top left of the header.

Testing the game from a local server

A big part of the Instant Games experience comes from the native overlays that are added to the game before and after each play session. In order to facilitate the development and testing workflow, we enable developers to run the game from a local server with a very similar experience to what their players will see on our platform. This is done through our embedded test player, which requires a small amount of configuration.

Enabling SSL via localhost

Since our embedded test player is working under the win.app domain, it can only be served through https. In order to embed content in a page served via https, the embedded content also needs to be served via SSL. The next steps will walk you through setting up a localhost server that serves secure content. We are showing one option below, but there are many solutions possible to enable this behavior.

Step 1: Install the http-server package via npm. If you don't have npm installed, follow the install instructions on the Node.JS website. After that, run the following command:

npm install -g http-server

Step 2: Create a private key and a certificate via openssl. This is necessary to run the secure local server.

cd path/to/my/game/
openssl genrsa 2048 > key.pem
$ openssl req -x509 -days 1000 -new -key key.pem -out cert.pem
# Fill out necessary information

Step 3: Run the game from localhost with SSL. Once the key and certificate are ready, you can serve from localhost using SSL.

# Starts to serve via HTTPS, with cache disabled
http-server --ssl -c-1 -p 8080 -a 127.0.0.1
Starting up http-server, serving ./ through https
Available on:
https://127.0.0.1:8080
Hit CTRL-C to stop the server

Step 4: After this, pointing your browser to https://localhost:8080 should show you the game running.

Note: You must try to access it at least once, as you might need to approve a security warning from your browser before continuing. If that is the case and you skip this step, your game will not load.

For example, on Chrome you might need to access chrome://flags/#allow-insecure-localhost and enable 'Allow invalid certificates for resources loaded from localhost.' to get rid of the warning.

Running the embedded player from your browser

Now that the game is being served from localhost via a secure connection, you can embed it in our player. Point your browser here:

https://playground.win.app/21knightsanddragons?url=https://localhost:8080/src/game.html

Usage

Download the minified framework located in dist/index.iife.js and include it in your index.html file.

<script src="/index.iife.js"></script>

Usage with NPM

Install the framework with command npm install @purposeinplay/win-sdk-js. Then use:

import winsdk from "@purposeinplay/win-sdk-js";

API Overview

WinSDK.initializeAsync

Before you can use the SDK, you need to initialize it by calling the initializeAsync method. The SDK makes extensive use of Promises for asynchronous functionality. You'll only be able to interact with the loading UI after WinSDK.initializeAsync() resolves.

WinSDK.initializeAsync({ gameId: "123456" }).then(function () {
  // Before your game calls WinSDK.initializeAsync, it must be able to
  // accept mute and unmute command the game MUST NOT play any sound
  // durring this phase.
});

Parameters

gameID string The id of the desired game.

WinSDK.onStartAsync

The platform notifies the game that the game should start. Put your game start logic here.

WinSDK.onStartAsync().then((ev) => {
  myGame.start();
});

Returns A Promise that resolves with a Tournament object when the SDK is ready.

Tournament Object

{
  "tournament": {
    "id": "fa8b6b95-ec9b-4173-9d02-baca5e7a99b7",
    "name": "Tournament Name",
    "seed": "24501"
  }
}

WinSDK.setGameLoadingProgress(percentage)

Report the game's initial loading progress. Once you start downloading the necessary assets for initializing the game, you need to inform the SDK about the loading progress in order for us to display the loading bar to players.

WinSDK.setLoadingProgress(50); // Assets are 50% loaded

Parameters

percentage number A number between 0 and 100.

WinSDK.gameReadyAsync

This indicates to the platform that the game has finished initial loading and is ready to start.

  WinSDK.gameReadyAsync().then(() => {
    ...
  });

WinSDK.getRandomNumberAsync

Random numbers can be essential to many different types of games. However, it also causes fairness concerns when playing in Win tournaments. In order to address the potential imbalance caused by random numbers, the Win SDK has methods to generate random numbers; the numbers returned by Win are in the same sequence for each player in a match.

WinSDK.getRandomNumberAsync().then(({ number }) => {
  console.log("Random Number is", number);
});

Returns A Promise that resolves with a Result object when the random number has been generated.

WinSDK.getRandomNumberInRangeAsync

WinSDK.getRandomNumberInRangeAsync(1, 100).then(({ number }) => {
  console.log("Random Number in range is", number);
});

Parameters

min The minimum int value of the range.

max The maximum int value of the range.

Returns A Promise that resolves with a Result object when the random number has been generated.

Result Object

Represents a data structure that includes the generated random number.

WinSDK.submitScoreAsync

Posts a player's score to the Win Platform. This API should only be called within a tournament context at the end of an activity (example: when the player doesn't have "lives" to continue the game).

WinSDK.submitScoreAsync(score).then(() => {
  ...
})

Returns A Promise that resolves when the score post is completed.

Parameters

score number An integer value representing the player's score at the end of an activity.

WinSDK.forfeitMatchAsync

Notifies the Win Platform that the game is over.

WinSDK.forfeitMatchAsync().then(() => {
  ...
})

Returns A Promise that resolves when the forfeit request is completed.