Quick Start Single Player

The following flow provides a standard example of using Sequence Wallet for authentication in Gamers Lab, along with handling a single-player game that features 'levels' or 'matches'.

Before starting, ensure that you have Sequence Wallet installed and set up in your Unity or Unreal Engine application.

Overview

A standard flow chart with associated functions can be found at the end of this document for a more detailed reference.

Player Authentication & Session API

1. Wallet Sign-In (Sequence)

Obtain a Sequence Wallet IdToken (JWT) to initiate user login. This token will be submitted to your backend to authenticate and mint a platform JWT.

Sequence SDK References

• Unreal Guide

• Unity Guide

// Example in Unity
const jwt = await wallet.getIdToken();

Save the resulting JWT for future use. It will be used once for session login.

---

2. Player Account Management

A. Check if the wallet address is linked to an existing player

Endpoint: GET /api/BlockchainStorage/players/lookup/address/{address}

Instructions: Use this to verify if a wallet is already associated with a player. Returns 404 or 500 if the player does not exist. Always check for both.

Response 200:

{
  "playerIndex": 0
}

---

B. Check if username (playerId) is available

Endpoint: GET /api/BlockchainStorage/players/lookup/index/{playerId}

Instructions: Create a username field in your game UI. This call checks if the username is already in use. Returns 404 or 500 if username is available.

Response 200 if taken:

{
  "playerIndex": 0
}

---

C. Create New Player (Anonymous Registration)

Endpoint: POST /api/BlockchainStorage/players/add/anon

Instructions: Allows user registration without needing admin credentials. Protected by a simple password scheme. Save the player Index for future use. This is the key identifier for the Gamers LAB platform.

Body:

{
  "playerId": "your_username",
  "playerAddress": "0xabc...",
  "signInPassword": "gameSecret"
}

Response 200:

{
  "transactionHash": "0x...",
  "playerIndex": 2
}

---

3. Login With Sequence JWT

Endpoint: POST /api/Auth/wallet/login/sequence-jwt

Instructions: Submit the Sequence-issued JWT. The API will return a Gamers LAB specific JWT. You may now discard the Sequence JWT and use the Gamers LAB JWT for all future calls.

Body:

{
  "jwt": "<SequenceJWT>"
}

Response: Returns 200 OK with the platform JWT in the body.

---

4. Start Login Session

Endpoint: POST /api/BlockchainStorage/sessions/login/start

Instructions: Call once per app open to begin a login session. Only available after login is completed. From this point on, the Gamers LAB JWT token will be required for all calls for authentication purposes.

Body:

{
  "device": "PC",
  "startTime": 1715670000
}

Response 200:

{
  "transactionHash": "0x...",
  "sessionId": 1
}

---

5. Gameplay Tracking

A. Start Match Session (Single Player)

Endpoint: POST /api/BlockchainStorage/match/sessions/start/singleplayer

Instructions: Call when a new level loads. It requires the level or match name. Store the matchSessionId for future calls (such as adding records for the player, ending the match, or adding new users).

Body:

{
  "level": "world-1"
}

Response 200:

{
  "transactionHash": "0x...",
  "matchSessionId": 42
}

---

B. Add Game Event Record

Endpoint: POST /api/BlockchainStorage/records/match/add

Instructions: Use this endpoint throughout the match to log events (kills, pickups, etc.). Values such as otherPlayers may be empty. This field should only be used with registered player-to-player events.

Body:

{
  "matchSessionId": 42,
  "score": 100,
  "key": "enemyDefeated",
  "value": "orc",
  "otherPlayers": [3, 4]
}

Response 200:

{
  "transactionHash": "0x...",
  "id": 27
}

---

C. Player Data Match End

Endpoint:

/api/BlockchainStorage/match/player/end

Instructions:

Use this endpoint to set the final score for the match for this specific player

Body:

{
  "matchSessionId": 0,
  "score": 0,
  "winLoss": 0,
  "matchPosition": 0,
}

Response 200:

{
  "transactionHash": "string",
  "playDataId": 0,
  "playerIndex": 0
}

D. Match Session End (Single Player)

Endpoint: POST /api/BlockchainStorage/match/sessions/singleplayer/end

Instructions: Call this when the player dies or finishes the level.

Body:

{
  "matchSessionId": 42
}

Response 200:

{
  "transactionHash": "0x...",
  "playDataId": 15
}

---

6. Player Score (Optional)

A. Get Player Score

Endpoint: GET /api/BlockchainStorage/players/{playerIndex}

Instructions: To retrieve a player's current score, request their full profile and extract the score field. This is useful before overwriting their score.

Response 200:

{
  "playerId": "sample",
  "address": "0xfeCc86F60887373c4CDF736f7f7be29C52D12a91",
  "playerType": 0,
  "score": 0,
  "identifiers": {},
  "verifiedAddresses": []
}

---

B. Set Player Score

Endpoint: POST /api/BlockchainStorage/players/set/score

Instructions: This call will overwrite the existing score, so make sure to retrieve it first if needed.

Body:

{
  "newScore": 1400
}

Response:

{
  "transactionHash": "0x...",
  "playerIndex": 2,
  "newScore": 1400
}

7. Logout Tracking

End Login Session

Endpoint: POST /api/BlockchainStorage/sessions/login/end

Instructions: Call when the player exits the game or signs out.

Body:

{
  "sessionId": 1
}

Response:

{
  "transactionHash": "0x..."
}

Detailed Flow Map