Deploying a Game within the Marketplace

Make it easy for the players to trade Living Assets, without having to build the UI into the game.

Introduction

This tutorial shows how to deploy a browser-based game together with Freeverse's fully-featured, customizable web-marketplace: allowing players to trade their Living Assets without having to build a custom marketplace user interface within the game itself.

The key take-aways of this tutorial are:

• The browser-game fully integrated and deployed with Freeverse's Customizable Marketplace.

• A marketplace for players to buy 'new' items, and trade items among themselves.

• A fully-integrated payment solutions that allows players to buy and sell in any regular currency or cryptocurrency.

• One-click signup using email or social-media, and connecting either Freeverse's Onboarding Wallet, or Metamask and Walletconnect for existing web3 users.

• Fully customizable visuals, matching the existing ones in the game.

• Automatic upgrades with new features, bug fixes, payment providers options, etc.

See an example of how the game will look like below:

Prerequisites

This example will result in four core components working in harmony: the game client, game server, Freeverse's Living Assets API, and Freeverse's Customizable Marketplace.

High-level architecture integration

Game Client

Any web-based game engine or build architecture can be used with this tutorial, as long as it can run in a browser.

Game Server

The game must control all logic regarding users and user accounts in a dedicated server. In this sense, the game should be at-least partially server authoritative, in that the server must have control over the creation of new assets, and evolution of existing asset properties. However, not all game logic must run on the server.

Living Assets API

All the blockchain features discussed in this tutorial make use of the Freeverse Living Assets platform. Interacting with its API is done through a GraphQL interface.

The description of this API and many other aspects related to it are discussed in other sections of this documentation, therefore some details will reference those sections.

Interacting with the API needs an active Universe. Please contact the sales team to create one.

Freeverse Customizable Marketplace

The Customizable Marketplace ("the marketplace") is the basic element in this tutorial. It is a web-based game marketplace that can be adapted visually to any game or brand, hosted in Freeverse's servers, and comes with trading features ready out-of-the-box.

The marketplace allows the player to sign up on the platform, and create or register a web3 wallet for trading, storing the owned assets and keeping funds. This information is essential in identifying the user in the game (asking for all the player's assets for example) and rendering the game accordingly.

The appearance and functionality of the marketplace are all controlled by a JSON configuration file.

Full documentation on the Customizable Marketplace can be found here.

Using a Customizable Marketplace needs an active Universe. Please contact the sales team to create one.

Integration Overview

This tutorial will embed a browser-based game into an <iframe> element hosted within the marketplace, such as in the example in the screenshot below.

A user can login to the marketplace, which can then pass the user's details to the game instance, in the form of an encrypted URL parameter. This parameter can then be decoded to display the user's Living Assets within the game.

A Unity WebGL binary embedded in an iframe on a Customizable Marketplace

The overall flow by which a game is integrated into the marketplace is as follows:

1. The game binary is hosted on a third-party hosting service.

2. An instance of the Freeverse Marketplace is customized to match the game's style and appearance.

3. One tab of the marketplace embeds an iframe which points to the URL of the hosted game.

4. The marketplace calls the game's iframe with a URL parameter. This parameter contains encrypted information regarding the logged-in user (their email and web3 address).

5. The URL parameter is forwarded to the game server to be decrypted.

6. The game server decrypts the information and informs the game client about the logged in user, thus enabling their items to be shown in the game.

7. The user can see and play with their Living Assets in the game

Integration Walkthrough

1) Game hosting configuration

Upload the game client to a web hosting service of your choice, and note the URL. The marketplace will call this URL from an embedded iFrame.

2) Configure the marketplace iFrame to send user data to game

The marketplace configuration file (explained here) controls all marketplace appearance and functionality aspects.

The most important customizable element is the ability to embed an <iframe> element pointing to the game deployment. When calling this URL from the iFrame, the marketplace will add a custom URL parameter which contains user data, concatenated and encrypted using public key cryptography and Ethereum-compatible addresses.

The URL parameter is called encryptedData.

For instance, an example iframe url might be https://mygame.myserver.com/?encryptedData=2f89...<snip>...fd90

The code below is a snippet from the marketplace JSON configuration file which will generate the url:

Game URL and Public Key provided by the customer

"url": link to the URL where your game binary will be deployed (without parameters)

"keys": Enumerates the type of data that will be encrypted within the URL parameter

"publicKey": the key used to encrypt this data.

The marketplace will encrypt the logged-in user's data using the provided public key. The game will use the corresponding private key to extract the data.

Thus, to effectively communicate this information to the game, we must create a unique public/private key pair following the Ethereum format. Creating a public and private key pair is straightforward, and can be done programmatically using various languages, or can be done online.

Any public/private key pair can be used for this communication. Nevertheless, the private key should be stored securely, as always.

3) Decode the encryptedData URL parameter

While is it possible to decode the encryptedData parameter within the game client, doing so requires storing the private decryption key within the game binary. If this key is extracted by a malicious user, that user could potentially play the game using a different user's assets.

As such we strongly recommend performing the decryption of the parameters server side.

In order for the game to understand which user is logged in to the marketplace, the encryptedData URL parameter must be decoded. Thus, the following should be implemented:

• The game server implements a custom endpoint that receives the encryptedData parameter.

• The game server decodes the encryptedData parameter (for example, using the code snippet below).

• The game server informs the current game client session of the decoded data.

• The game client uses this information to allow the user to view and play with their Living Assets.

The following code snippet shows how the encryptedData URL parameter can be quickly decrypted to provide the user information.

Node.JS

// Decrypt the encryptedData url parameter to a JSON object
// with the hashed email and web3 address of the user

// npm install eth-crypto
const EthCrypto = require('eth-crypto');
const privateKey = '0x...43'; // the private key for decryption
const encryptedString = '<encryptedUrl_parameter_string>';

// decrypts a string that was encrypted for a given publicKey
const decryptWithPrivateKey = async (encryptedString, privateKey) => {
  
  // converting the encypted String into an encrypted object
  const encryptedObject = EthCrypto.cipher.parse(encryptedString);
  
  // decrypt the encrypted object with the private key
  const decrypted = await EthCrypto.decryptWithPrivateKey(
    privateKey,
    encryptedObject,
  );

  // parse decrypted string to JSON
  const decryptedJSON = JSON.parse(decrypted);
  
  //output JSON result to console
  console.log(decryptedJSON);
};

decryptWithPrivateKey(encryptedString, privateKey);

// output:
// {
//   email: '<hashed email>',
//   id: '<web3 address>'
// }

Options for sending the encryptedData to the game server

There are two options for sending the encryptedData parameter to be decoded on the server.

1. Communicate with the game server endpoint directly from the browser (for example, use the javascript fetch API). Care must be taken here with Cross Origin Resource Sharing (CORS) errors (either make sure the local game client page is hosted in the same domain as the game server, or configure the server to permit CORS correctly.

2. Pass the encryptedData string to the game binary first (for example, for a Unity game, see Interaction with Browser Scripting), and allow the game to communicate with the server via your regular paths.

4) Customize the marketplace

The Customizable Marketplace allows the developer to tailor the visuals of the marketplace with the game. It is not mandatory, but recommended for giving the same experience to the players. More information about how to tailor the marketplace here.

5) Connect to the Living Assets API to read user data

Now we have the user's detail, we can now send queries (read-only operations) or mutations (write operations that affect the status of an asset, or create a new one) that affect this user.

For a further tutorial on how to do this in your game's server, see the Managing Assets on a Game Server tutorial.

Conclusions

In this tutorial, we have seen that deploying your web-based game with a ready-to-go trading marketplace is straightforward. Gamers can trade Living Assets in a stable and highly configurable environment, and the game can be accessed by the players very easily.