npm package: @purposeinplay/win-sdk-js
Description: Win SDK is a Javascript framework for connecting HTML5 games to the Win platform.
Latest version: 0.0.11

# 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:

```bash
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.

```bash
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.

```bash
# 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](https://github.com/purposeinplay/win-sdk/blob/master/winsdk/dist/index.iife.js) and include it in your `index.html` file.

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

### Usage with NPM

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

```javascript
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.

```js
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.

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

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

##### Tournament Object

```json
{
  "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.

```js
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.

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

## Lifecycle and Race-Safety Notes

- The SDK now exposes a lightweight global stub immediately on script load. Calls made before initialization (e.g., `setGameLoadingProgress`, `onStartAsync`) are safely queued.
- After `initializeAsync` resolves, the stub is promoted to the real instance and queued calls are flushed.
- `setGameLoadingProgress` made pre-init is buffered (latest value only) and sent once after init.
- `onStartAsync` resolves immediately even if the `start` event arrived before you attached the listener.
- `gameReadyAsync` is idempotent: multiple calls will reuse the same in-flight promise and only publish once.

### Recommended ordering

1. Load SDK script
2. Optionally set early progress via `setGameLoadingProgress(x)`
3. `await WinSDK.initializeAsync({ gameId })`
4. `await WinSDK.onStartAsync()` then start gameplay
5. When ready to play, call `await WinSDK.gameReadyAsync()`

### 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.

```js
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

```js
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).

```js
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.

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

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