Skip to main content
info

For Cadence 0.42 go to Legacy Docs

Tutorial - How to Build FlowWords

Outline

The FlowWords tutorial example project is the complete FlowWords game, with the FlowSDK and any SDK related code removed.

In this tutorial, you will learn how to;

  1. Configure the FlowSDK and local emulator for use with Unity
  2. Deploy contracts, create Accounts and run Transactions on the Flow emulator from within Unity.
  3. Incorporate Flow Accounts, Transactions and Scripts into Unity projects using Code

Requirements

FlowWords Tutorial has been tested on Unity version 2021.3.6f1

This tutorial assumes you have created a blank project, and installed the FlowSDK package from the Unity Asset Store, and FlowWords Tutorial Sample.

Step 1 – Configure the FlowSDK and local emulator

  1. Open the scene at Assets\Samples\Flow SDK\<version>\Flow Words Tutorial Assets\Scenes\Game.unity

    Open Game scene example

  2. Open the Flow Control Manager window, at Window->Flow->Flow Control.
    This will create a Flow Control GameObject in the Game scene, and a FlowControlData asset in the Resources folder if they do not already exist.

    Open Flow Control Manager example

  3. Go to the Emulator Settings tab. If the manager states the Flow Executable cannot be found, use the Install button provided and follow the instructions to install the Flow CLI.
    Note: If Unity still does not detect the emulator after installing the Flow CLI, you may need to restart your computer for the install to take effect.

  4. Set a directory for our Emulator data to reside in. This is where the emulator stores the state of the emulated Flow blockchain.
    For the purposes of this tutorial, we will create a new folder called FlowEmulator inside our project folder.

    Set Emulator data directory example

  5. Click Start Emulator to start the emulator and create the emulator_service_account, and ensure “Run emulator in play mode” is checked.

    Start Emulator example

    NOTE: If this is the first time you have run the emulator on Windows, you may be presented with a dialog to allow access through your firewall. This is safe to allow.

  6. Go to the Accounts tab and verify that the service account has been created.
    This is the account we will use to create more accounts, and deploy our game contract on to the emulator.

    Flow Control Manager Accounts final state

  7. Back on the Emulator Settings tab, you can click Show Emulator Log, to view the output.

    Flow Emulator Output example

Step 2 – Deploy Contracts, create Accounts and run Transactions

We have provided you with the FlowWords game contract, but before we can interact with the contract, we have to deploy it to the blockchain.

We also have to set up some text replacements as, once deployed, our scripts will require hardcoded references to the contract name and deployed address.

Set up Text Replacements

Text replacements allow us to set and update references across all of our local Cadence scripts, without having to update each file individually.

  1. Open the Flow Control Manager window, and navigate to the Text Replacements tab.

  2. Set up the text replacements as follows. You can add text replacements by clicking the ‘+’ button at the top of the panel.

    Flow Control Manager Text Replacement final state

    The anatomy of a text replacement is as follows;
    Description: A friendly description, has no bearing on functionality.
    Original Text: The original text, in your script files, which you want to replace.
    Replacement Text: The text that you wish to replace the original text with. This is what gets submitted to the chain.
    Active: This checkbox enables or disables the text replacement.
    Apply to Accounts: Select which, if any, accounts this text replacement should apply to.
    Apply to Gateways: Select which, if any, gateways (such as Emulator, or TestNet) this replacement should apply to.

Create User Accounts

While it would be perfectly possible to play our game with the emulator service account, we will often want to test our contracts with multiple different user accounts.

To create a new user account;

  1. Open the Flow Control Manager window, and navigate to the Tools tab.

  2. In the Create New Account section;

    Flow Control Manager new account creation example

    1. Select the paying account. This will usually be the emulator_service_account
    2. Enter a friendly name for the new account. This name is just for your own reference and does not get written to the chain.
    3. Click Create
  3. If successful, the new account will appear under the Flow Control Manager Accounts tab.

    Flow Control Manager new account example final state

Deploy the Contract

Before anyone can interact with a contract, it must be deployed to the blockchain.

We are going to deploy our game contract to the emulator, for local testing. But for deploying to Testnet, or Mainnet follow the same process.

  1. Go to the Emulator Settings tab, in the Flow Control Manager, and Start the Emulator if it is not already running.

  2. Go to the Tools tab. In the Manage Contracts section, enter the contract name of ‘FlowWords’ – this should match our CONTRACT_NAME text replacement precisely.

  3. Populate the Contract field with game-contract.cdc, which can be found in Resources/contracts

    Resources folder example

  4. Finally, ensure that the Account field contains emulator_service_account, and click the Deploy Contract button.

    Flow Control Manager contract deployment example

  5. To check if the contract has deployed successfully, open the Flow Emulator Output window. Successful deployment will look as follows;

    Flow Emulator Output example

Submit Transactions

For administration purposes, it is sometimes useful to be able to directly submit transactions to the chain.

We can use a transaction to check out text replacements are set up correctly, and our game contract has successfully deployed.

  1. In Flow Control Manager, navigate to tools.

  2. In the Transactions section;

    Flow Control Manager contract deployment example

    1. Populate the Transaction field with check-contract-deployed.cdc, located in Resources/transactions

      Resources folder example

    2. Set the Signer field to the new Account we just created earlier. ‘Player1’

    3. Click Execute Transaction

  3. If you have successfully configured the SDK and deployed the game contract, you will see the following message;

    Flow Emulator Output example

Step 3 – Incorporate Flow Accounts, Transactions and Scripts into Code

We have our SDK and emulator configured, and our game contract deployed.
Now we are going to create the code which will allow our game to send and receive data from the blockchain.

Our FlowWords tutorial project contains a script called FlowInterface.cs, which can be found in the Scripts folder. This script contains all of our blockchain interfacing functions, which are called from GameManager.cs and UIManager.cs.

Our game FlowInterface has 5 main functions:

  • Login
  • Logout
  • GetGameDataFromChain
  • SubmitGuess
  • LoadHighScoresFromChain

Our functions are going to need to access a number of cadence scripts and transactions.
These have been provided for you, and can be found in the Resources\scripts folder and Resources\transactions folder.

Resources folder example

FlowInterface.cs has a number of Serialized TextAsset fields, which can be populated via the Unity inspector. Select the GameFlowInterface gameobject in the Game.unity scene, and populate the fields as follows, using the scripts and transactions in the aforementioned folders; (you may find these have already been populated for you)

GameFlowInterface script assignment final state example

Login

Open FlowInterface.cs and find the Login function stub.

The Login function’s role is to take the credentials entered by the user, create a FlowControl.Account object with which we can submit transactions to the chain, and run the login.cdc transaction.

At the top of the file, add the following using statements to grant us easy access to the Flow SDK structures.


_10
using DapperLabs.Flow.Sdk.Cadence;
_10
using DapperLabs.Flow.Sdk.DataObjects;
_10
using DapperLabs.Flow.Sdk.DevWallet;
_10
using Convert = DapperLabs.Flow.Sdk.Cadence.Convert;

Your file should now look like this:


_13
using System;
_13
using System.Collections;
_13
using System.Collections.Generic;
_13
using System.Linq;
_13
using System.Numerics;
_13
using System.Threading.Tasks;
_13
using UnityEngine;
_13
using DapperLabs.Flow.Sdk;
_13
using DapperLabs.Flow.Sdk.Unity;
_13
using DapperLabs.Flow.Sdk.Cadence;
_13
using DapperLabs.Flow.Sdk.DataObjects;
_13
using DapperLabs.Flow.Sdk.DevWallet;
_13
using Convert = DapperLabs.Flow.Sdk.Cadence.Convert;

Uncomment the following at line 56:


_10
//private FlowControl.Account FLOW_ACCOUNT = null;

We now have to register a wallet provider with the Flow SDK. We are going to use DevWallet, which comes with the Flow SDK, and is only intended for development purposes on emulator and testnet. Add the following to the Start function:


_10
// Set up SDK to access Emulator
_10
FlowConfig flowConfig = new FlowConfig()
_10
{
_10
NetworkUrl = "http://127.0.0.1:8888/v1", // emulator
_10
Protocol = FlowConfig.NetworkProtocol.HTTP
_10
};
_10
FlowSDK.Init(flowConfig);
_10
_10
// Register DevWallet wallet provider with SDK
_10
FlowSDK.RegisterWalletProvider(new DevWalletProvider());

Your Start function should now look like this:


_18
private void Start()
_18
{
_18
if (Instance != this)
_18
{
_18
Destroy(this);
_18
}
_18
_18
// Set up SDK to access Emulator
_18
FlowConfig flowConfig = new FlowConfig()
_18
{
_18
NetworkUrl = "http://127.0.0.1:8888/v1", // emulator
_18
Protocol = FlowConfig.NetworkProtocol.HTTP
_18
};
_18
FlowSDK.Init(flowConfig);
_18
_18
// Register DevWallet wallet provider with SDK
_18
FlowSDK.RegisterWalletProvider(new DevWalletProvider());
_18
}

WARNING: Do not use DevWallet in production builds. It is only intended for development purposes and does NOT securely store keys.
Having the Address and Private Keys to a blockchain account gives your application full access to all of that account’s funds and storage. They should be treated with extreme care.

Next, we will fill out the body of the Login function.


_11
/// <summary>
_11
/// Attempts to log in by executing a transaction using the provided credentials
_11
/// </summary>
_11
/// <param name="username">An arbitrary username the player would like to be known by on the leaderboards</param>
_11
/// <param name="onSuccessCallback">Function that should be called when login is successful</param>
_11
/// <param name="onFailureCallback">Function that should be called when login fails</param>
_11
public void Login(string username, System.Action<string, string> onSuccessCallback, System.Action onFailureCallback)
_11
{
_11
// Authenticate an account with DevWallet
_11
_11
}

First, we have to invoke the wallet provider to authenticate the user and get their flow address. Add the following code to the Login function;


_10
// Authenticate an account with DevWallet
_10
FlowSDK.GetWalletProvider().Authenticate(
_10
"", // blank string will show list of accounts from Accounts tab of Flow Control Window
_10
(string address) => onSuccessCallback(address, username),
_10
onFailureCallback);

The Authenticate function takes parameters as follows;

  • The first parameter is a username which corresponds to the name of an account in the Accounts tab. If you leave this string blank (as above), a dialog will be shown to the user to select an account from the Accounts tab.
  • The second parameter is a success callback for Authenticate(). We pass in a lambda function which starts a coroutine to run our async function OnAuthSuccess. This takes the flow address that we got from Authenticate(), as well as a few other parameters.
  • The third parameter is a callback for if Authenticate() fails. We pass through the fail callback that was passed to Login.

Your completed Login function should look as follows;


_17
/// <summary>
_17
/// Attempts to log in by executing a transaction using the provided credentials
_17
/// </summary>
_17
/// <param name="username">An arbitrary username the player would like to be known by on the leaderboards</param>
_17
/// <param name="onSuccessCallback">Function that should be called when login is successful</param>
_17
/// <param name="onFailureCallback">Function that should be called when login fails</param>
_17
public void Login(string username, System.Action<string, string> onSuccessCallback, System.Action onFailureCallback)
_17
{
_17
// Authenticate an account with DevWallet
_17
if (FlowSDK.GetWalletProvider().IsAuthenticated() == false)
_17
{
_17
FlowSDK.GetWalletProvider().Authenticate(
_17
"", // blank string will show list of accounts from Accounts tab of Flow Control Window
_17
(string address) => onSuccessCallback(address, username),
_17
onFailureCallback);
_17
}
_17
}

Now we need to implement the GetGameDataFromChain function for when we successfully authenticate our user and get their flow address.
At this point we have successfully authenticated our user, and all subsequent Scripts and Transactions will be submitted via the authenticated account.

GetGameDataFromChain

This function executes the get-current-gamestate.cdc transaction on the chain, and then processes the emitted events to get the CurrentGameState for the logged in account, and current GameStartTime for the game of the day, which we use to show time remaining.


_24
/// <summary>
_24
/// Attempts to get the current game state for the user from chain.
_24
/// </summary>
_24
/// <param name="username">An arbitrary username the player would like to be known by on the leaderboards</param>
_24
/// <param name="onSuccessCallback">Callback on success</param>
_24
/// <param name="onFailureCallback">Callback on failure</param>
_24
public IEnumerator GetGameDataFromChain(string username, System.Action<Decimal, List<GuessResult>, Dictionary<string, string>> onSuccessCallback, System.Action onFailureCallback)
_24
{
_24
// get FLOW_ACCOUNT object for text replacements
_24
_24
// execute getCurrentGameState transaction on chain
_24
_24
// check for error. if so, break.
_24
_24
// transaction success, get data from emitted events
_24
_24
// process currentGameState event
_24
_24
// process gameStartTime event
_24
_24
// call GameManager to set game state
_24
_24
yield return null;
_24
}

As you will recall, we previously configured a number of text replacements.
These are useful, and allow us to easily change some hardcoded data from a contract or transaction, such as the deploy address of the contract, from one central location without having to edit every cadence script in our project.
Our transactions and scripts will need to access the text replacement function, which lives in the FlowControl.Account class, so we need to first create a FlowControl.Account object as follows;


_10
// get FLOW_ACCOUNT object for text replacements
_10
FLOW_ACCOUNT = new FlowControl.Account
_10
{
_10
GatewayName = "Emulator", // the network to match
_10
AccountConfig = new Dictionary<string, string> { { "Address", FlowSDK.GetWalletProvider().GetAuthenticatedAccount().Address } } // the account address to match
_10
};

We are about to pull down the user's saved game data. To make processing event data easier, we have declared three classes to hold the results of events emitted by transactions:


_14
public class StatePayload
_14
{
_14
public List<GuessResult> currentState;
_14
}
_14
_14
public class TimePayload
_14
{
_14
public Decimal startTime;
_14
}
_14
_14
public class GuessResultPayload
_14
{
_14
public string result;
_14
}

Let's compare these to the payloads for each event in the contract:


_14
access(all) event CurrentState(currentState: [UserGuess])
_14
access(all) event LastGameStart(startTime: UFix64)
_14
access(all) event GuessResult(result: String)
_14
_14
access(all) struct UserGuess
_14
{
_14
access(all) let Guess: String
_14
access(all) let Result: String
_14
init(guess: String, result: String)
_14
{
_14
self.Guess = guess
_14
self.Result = result
_14
}
_14
}

When using Cadence.Convert, cadence arrays are converted into C# Lists, as shown in the StatePayload class and CurrentState event.

In GameManager.cs, the GuessResult class is declared as:


_18
public class GuessResult
_18
{
_18
/// <summary>
_18
/// the guess that was submitted
_18
/// </summary>
_18
[Cadence(CadenceType = "String", Name = "Guess")]
_18
public string word;
_18
/// <summary>
_18
/// A 5 letter code indicating the result and resulting color a cell should be.
_18
/// </summary>
_18
/// <remarks>
_18
/// "p" = the letter at this position was in the word and in the correct (p)osition, color the cell green.
_18
/// "w" = the letter at this position was in the (w)ord, but in the incorrect position, color the cell yellow.
_18
/// "n" = the letter at this position was (n)ot in the word.
_18
/// </remarks>
_18
[Cadence(CadenceType = "String", Name = "Result")]
_18
public string colorMap;
_18
}

We want the Cadence fields Guess and Result to map to the C# fields word and colorMap. To do this, we add a Cadence attribute to each field with a Name parameter that tells it which Cadence fields maps to that class field.

We did not have to do that with the three payload classes we defined earlier because the C# field names exactly match the Cadence field names in the contract.

Now that we have an Account object for text replacement, we can use it with the Transactions class to Submit our login.cdc transaction.

Add the following code to the GetGameDataFromChain function;


_11
// execute getCurrentGameState transaction on chain
_11
Task<FlowTransactionResult> getStateTask = Transactions.SubmitAndWaitUntilExecuted(FLOW_ACCOUNT.DoTextReplacements(loginTxn.text), new CadenceString(username));
_11
_11
while (!getStateTask.IsCompleted)
_11
{
_11
int dots = ((int)(Time.time * 2.0f) % 4);
_11
_11
UIManager.Instance.SetStatus($"Retrieving data from chain" + new string('.', dots));
_11
_11
yield return null;
_11
}

Because transactions can take quite some time on chain, we create an asynchronous Task by calling SubmitAndWaitUntilExecuted from the Transactions class, to prevent blocking the main game thread.
Into SubmitAndWaitUntilExecuted, we pass the script that we want to execute, and any parameters.

For our script, we refer to the serialized TextAsset field, loginTxn, to which we will assign login.cdc in the inspector.
We pass our script into SubmitAndWaitUntilExecuted via the DoTextReplacements function on our FLOW_ACCOUNT object, which will parse the cadence script and replace any of our defined text replacements.

For parameters, the login.cdc script is expecting a single String parameter with the player’s display name in it. We pass in a new CadenceString object, which we create inline from the encapsulating function’s username string parameter.

Next, we simply wait until our asynchronous task.IsCompleted.
While we wait, we update the UI with a simple animated ‘Connecting…’ text status, and yield to the Unity engine to prevent blocking the thread.

Once our transaction has completed, we want to check if it was successful on chain. Add the following code beneath the transaction submission code;


_10
// check for error. if so, break.
_10
if (getStateTask.Result.Error != null || getStateTask.Result.ErrorMessage != string.Empty || getStateTask.Result.Status == FlowTransactionStatus.EXPIRED)
_10
{
_10
onFailureCallback();
_10
yield break;
_10
}

Here we must check the transaction Result for three conditions:

  • Error: Was there an error submitting the transaction to the blockchain?
  • ErrorMessage: Was there an error during processing on the blockchain?
  • Status: A status of EXPIRED means that the transaction did not execute on time and was discarded.

Any error here, and we are simply going to fail the login, and call our onFailureCallback.

Next, we process the result of our transaction.
This transaction is designed to return the game state for the user, and the time remaining on the word of the day, via emitted events.
We can access these emitted events via the .Result.Events property on our task.
To do so, add the following code below our submission logic;


_10
// transaction success, get data from emitted events
_10
List<FlowEvent> events = getStateTask.Result.Events;
_10
FlowEvent currentStateEvent = events.Find(x => x.Type.EndsWith(".CurrentState"));
_10
FlowEvent startTimeEvent = events.Find(x => x.Type.EndsWith(".LastGameStart"));
_10
_10
if (currentStateEvent == null || startTimeEvent == null)
_10
{
_10
onFailureCallback();
_10
yield break;
_10
}

This chunk accesses the returned Events list, and attempts to find events ending with “.CurrentState” and “.LastGameStart”. We use .EndsWith, as the transaction returns fully qualified event names, and the name of the deployed contract may change during development.
Finally, we check that we do indeed have both of our required events, and if not, call the onFailure callback and break.

Next, we will parse the contents of each event. Add the following code to the function;


_36
// process current game state event
_36
Decimal gameStartTime = 0;
_36
Dictionary<string, string> letterStatuses = new Dictionary<string, string>();
_36
List<GuessResult> results = Convert.FromCadence<StatePayload>(currentStateEvent.Payload).currentState;
_36
foreach (GuessResult newResult in results)
_36
{
_36
newResult.word = newResult.word.ToUpper();
_36
for (int i = 0; i < 5; i++)
_36
{
_36
bool letterAlreadyExists = letterStatuses.ContainsKey(newResult.word[i].ToString());
_36
string currentStatus = letterAlreadyExists ? letterStatuses[newResult.word[i].ToString()] : "";
_36
switch (currentStatus)
_36
{
_36
case "":
_36
letterStatuses[newResult.word[i].ToString()] = newResult.colorMap[i].ToString();
_36
break;
_36
case "p":
_36
break;
_36
case "w":
_36
if (newResult.colorMap[i] == 'p')
_36
{
_36
letterStatuses[newResult.word[i].ToString()] = newResult.colorMap[i].ToString();
_36
}
_36
break;
_36
case "n":
_36
if (newResult.colorMap[i] == 'p' || newResult.colorMap[i] == 'w')
_36
{
_36
letterStatuses[newResult.word[i].ToString()] = newResult.colorMap[i].ToString();
_36
}
_36
break;
_36
}
_36
}
_36
}
_36
_36
// get game start time event
_36
gameStartTime = Convert.FromCadence<TimePayload>(startTimeEvent.Payload).startTime;

From the contract, we know that the CurrentState event returns a list of UserGuess structs. We want to convert these to a C# List<GuessResult>.


_10
List<GuessResult> results = Convert.FromCadence<StatePayload>(currentStateEvent.Payload).currentState;

This converts the Payload of the currentStateEvent event into a StatePayload object, then sets results to the currentState field of that object.

Then, we iterate over the results list and update the letterStatuses that we display.

The GameStartTime event is processed similarly:


_10
gameStartTime = Convert.FromCadence<TimePayload>(startTimeEvent.Payload).startTime;

The startTimeEvent payload is converted into a TimePayload object and the startTime field is extracted from that. Because the Cadence type is UFix64, we get back a C# Decimal struct.

Finally, we call our onSuccess callback to return our results to our caller.
Add the following lines to the bottom of the function;


_10
// call GameManager to set game state
_10
onSuccessCallback(gameStartTime, results, letterStatuses);

You can now remove the yield return null at the base of the function if you wish.

Your completed function should now look like this;


_85
/// <summary>
_85
/// Attempts to get the current game state for the user from chain.
_85
/// </summary>
_85
/// <param name="username">An arbitrary username the player would like to be known by on the leaderboards</param>
_85
/// <param name="onSuccessCallback">Callback on success</param>
_85
/// <param name="onFailureCallback">Callback on failure</param>
_85
public IEnumerator GetGameDataFromChain(string username, System.Action<Decimal, List<GuessResult>, Dictionary<string, string>> onSuccessCallback, System.Action onFailureCallback)
_85
{
_85
// get FLOW_ACCOUNT object for text replacements
_85
FLOW_ACCOUNT = new FlowControl.Account
_85
{
_85
GatewayName = "Emulator", // the network to match
_85
AccountConfig = new Dictionary<string, string> { { "Address", FlowSDK.GetWalletProvider().GetAuthenticatedAccount().Address } } // the account address to match
_85
};
_85
_85
// execute getCurrentGameState transaction on chain
_85
Task<FlowTransactionResult> getStateTask = Transactions.SubmitAndWaitUntilExecuted(FLOW_ACCOUNT.DoTextReplacements(loginTxn.text), new CadenceString(username));
_85
_85
while (!getStateTask.IsCompleted)
_85
{
_85
int dots = ((int)(Time.time * 2.0f) % 4);
_85
_85
UIManager.Instance.SetStatus($"Retrieving data from chain" + new string('.', dots));
_85
_85
yield return null;
_85
}
_85
_85
// check for error. if so, break.
_85
if (getStateTask.Result.Error != null || getStateTask.Result.ErrorMessage != string.Empty || getStateTask.Result.Status == FlowTransactionStatus.EXPIRED)
_85
{
_85
onFailureCallback();
_85
yield break;
_85
}
_85
_85
// transaction success, get data from emitted events
_85
List<FlowEvent> events = getStateTask.Result.Events;
_85
FlowEvent currentStateEvent = events.Find(x => x.Type.EndsWith(".CurrentState"));
_85
FlowEvent startTimeEvent = events.Find(x => x.Type.EndsWith(".LastGameStart"));
_85
_85
if (currentStateEvent == null || startTimeEvent == null)
_85
{
_85
onFailureCallback();
_85
yield break;
_85
}
_85
_85
// process current game state event
_85
Decimal gameStartTime = 0;
_85
Dictionary<string, string> letterStatuses = new Dictionary<string, string>();
_85
List<GuessResult> results = Convert.FromCadence<StatePayload>(currentStateEvent.Payload).currentState;
_85
foreach (GuessResult newResult in results)
_85
{
_85
newResult.word = newResult.word.ToUpper();
_85
for (int i = 0; i < 5; i++)
_85
{
_85
bool letterAlreadyExists = letterStatuses.ContainsKey(newResult.word[i].ToString());
_85
string currentStatus = letterAlreadyExists ? letterStatuses[newResult.word[i].ToString()] : "";
_85
switch (currentStatus)
_85
{
_85
case "":
_85
letterStatuses[newResult.word[i].ToString()] = newResult.colorMap[i].ToString();
_85
break;
_85
case "p":
_85
break;
_85
case "w":
_85
if (newResult.colorMap[i] == 'p')
_85
{
_85
letterStatuses[newResult.word[i].ToString()] = newResult.colorMap[i].ToString();
_85
}
_85
break;
_85
case "n":
_85
if (newResult.colorMap[i] == 'p' || newResult.colorMap[i] == 'w')
_85
{
_85
letterStatuses[newResult.word[i].ToString()] = newResult.colorMap[i].ToString();
_85
}
_85
break;
_85
}
_85
}
_85
}
_85
_85
// get game start time event
_85
gameStartTime = Convert.FromCadence<TimePayload>(startTimeEvent.Payload).startTime;
_85
_85
// call GameManager to set game state
_85
onSuccessCallback(gameStartTime, results, letterStatuses);
_85
}

Logout

The Logout function’s role is to disconnect the authenticated wallet from your app, and to clear the FlowControl.Account object, to prevent any more transactions from being executed with those account credentials.

The Logout function is very simple. Simply add the following line;


_10
FLOW_ACCOUNT = null;
_10
FlowSDK.GetWalletProvider().Unauthenticate();

This clears the FlowAccount object, preventing any more transactions from being submitted with it, and unauthenticates the user from the wallet provider.

Your completed Logout function should now look like this;


_10
/// <summary>
_10
/// Clear the FLOW account object
_10
/// </summary>
_10
public void Logout()
_10
{
_10
FLOW_ACCOUNT = null;
_10
FlowSDK.GetWalletProvider().Unauthenticate();
_10
}

SubmitGuess

This function has two phases. First, it checks that the entered word is valid by submitting the check-word.cdc script to chain, and processing the returned value.

If the word is deemed valid, it then submits the word guess to the game contract using the currently logged in user’s credentials, by executing the submit-guess.cdc transaction script on chain, and then processing the emitted events.

For phase one, enter the following code at the top of the SubmitGuess function;


_23
// submit word via checkWord script to FLOW chain to check if word is valid
_23
Task<FlowScriptResponse> checkWordTask = Scripts.ExecuteAtLatestBlock(FLOW_ACCOUNT.DoTextReplacements(checkWordScript.text), new CadenceString(word.ToLower()));
_23
_23
while (!checkWordTask.IsCompleted)
_23
{
_23
int dots = ((int)(Time.time * 2.0f) % 4);
_23
UIManager.Instance.SetStatus("Waiting for server" + new string('.', dots));
_23
yield return null;
_23
}
_23
_23
if (checkWordTask.Result.Error != null)
_23
{
_23
onFailureCallback();
_23
UIManager.Instance.SetStatus("Error checking word validity.");
_23
yield break;
_23
}
_23
_23
bool wordValid = ((checkWordTask.Result.Value as CadenceString).Value == "OK");
_23
if (wordValid == false)
_23
{
_23
onFailureCallback();
_23
yield break;
_23
}

This code starts by calling ExecuteAtLatestBlock, passing in the checkWordScript and our guess word as a CadenceString object, to create an async Task using our Flow Account object.

Scripts on Cadence can be thought of as read-only transactions, which are performed very quickly.
Since scripts are read only, they do not require signing, and are best to use when you need to quickly get publicly available data from chain.

As with our previous transactions, we then wait until our task.IsCompleted, and then check for any errors in the result. With scripts we only have to check the Result.Error, as this catches all possible failure modes.

We then process the return value of the script, which can be found in the Result.Value property on our completed task object. Scripts do not emit events like transactions, but have return values like a regular function.
The return value is of the generic base type CadenceBase, which we cast to CadenceString, as we are expecting a string type return value.

If the word guess is deemed to be invalid we call the onFailure callback and break, otherwise we proceed onto the guess submission phase.

For the second phase of the function, add the following code below phase one;


_37
// if word is valid, submit guess via transaction to FLOW chain
_37
Task<FlowTransactionResult> submitGuessTask = Transactions.SubmitAndWaitUntilExecuted(FLOW_ACCOUNT.DoTextReplacements(submitGuessTxn.text), new CadenceString(word.ToLower()));
_37
while (!submitGuessTask.IsCompleted)
_37
{
_37
int dots = ((int)(Time.time * 2.0f) % 4);
_37
UIManager.Instance.SetStatus("Waiting for server" + new string('.', dots));
_37
yield return null;
_37
}
_37
_37
if (submitGuessTask.Result.Error != null || submitGuessTask.Result.ErrorMessage != string.Empty || submitGuessTask.Result.Status == FlowTransactionStatus.EXPIRED)
_37
{
_37
onFailureCallback();
_37
yield break;
_37
}
_37
_37
// get wordscore
_37
string wordScore = "";
_37
FlowEvent ourEvent = submitGuessTask.Result.Events.Find(x => x.Type.EndsWith(".GuessResult"));
_37
if (ourEvent != null)
_37
{
_37
wordScore = Convert.FromCadence<GuessResultPayload>(ourEvent.Payload).result;
_37
_37
// check if we are out of guesses
_37
if (wordScore == "OutOfGuesses")
_37
{
_37
onFailureCallback();
_37
UIManager.Instance.SetStatus("Out Of Guesses. Try again tomorrow.");
_37
yield break;
_37
}
_37
_37
// process result
_37
onSuccessCallback(word, wordScore);
_37
}
_37
else
_37
{
_37
onFailureCallback();
_37
}

This phase begins by submitting the submit-guess.cdc transaction, passing in our guess word as a new CadenceString parameter. We then wait for the task to complete as usual, and check for any errors.
As this is a transaction, we once again check the three possible failure modes, and call the onFailure callback if the transaction failed.

Next we parse our transaction’s emitted events.


_10
access(all) event GuessResult(result: String)

We are expecting an event called GuessResult, with a single string parameter called result. We created a C# version of that event: GuessResultPayload.


_22
// get wordscore
_22
string wordScore = "";
_22
FlowEvent ourEvent = submitGuessTask.Result.Events.Find(x => x.Type.EndsWith(".GuessResult"));
_22
if (ourEvent != null)
_22
{
_22
wordScore = Convert.FromCadence<GuessResultPayload>(ourEvent.Payload).result;
_22
_22
// check if we are out of guesses
_22
if (wordScore == "OutOfGuesses")
_22
{
_22
onFailureCallback();
_22
UIManager.Instance.SetStatus("Out Of Guesses. Try again tomorrow.");
_22
yield break;
_22
}
_22
_22
// process result
_22
onSuccessCallback(word, wordScore);
_22
}
_22
else
_22
{
_22
onFailureCallback();
_22
}

We first find our event in the Result.Events list on our task object.

If our event is found, we then convert the payload to a GuessResultPayload and store the result field as wordScore. We then pass the guess word, and the result back to our caller via the onSuccess callback.

If the GuessResult event cannot be found in the Result.Events list, we call the onFailure callback.

Once complete, your SubmitGuess function should look like this:


_63
public IEnumerator SubmitGuess(string word, System.Action<string, string> onSuccessCallback, System.Action onFailureCallback)
_63
{
_63
// submit word via checkWord script to FLOW chain to check if word is valid
_63
Task<FlowScriptResponse> checkWordTask = Scripts.ExecuteAtLatestBlock(FLOW_ACCOUNT.DoTextReplacements(checkWordScript.text), new CadenceString(word.ToLower()));
_63
while (!checkWordTask.IsCompleted)
_63
{
_63
int dots = ((int)(Time.time * 2.0f) % 4);
_63
UIManager.Instance.SetStatus("Waiting for server" + new string('.', dots));
_63
yield return null;
_63
}
_63
_63
if (checkWordTask.Result.Error != null)
_63
{
_63
onFailureCallback();
_63
UIManager.Instance.SetStatus("Error checking word validity.");
_63
yield break;
_63
}
_63
_63
bool wordValid = ((checkWordTask.Result.Value as CadenceString).Value == "OK");
_63
if (wordValid == false)
_63
{
_63
onFailureCallback();
_63
yield break;
_63
}
_63
_63
// if word is valid, submit guess via transaction to FLOW chain
_63
Task<FlowTransactionResult> submitGuessTask = Transactions.SubmitAndWaitUntilExecuted(FLOW_ACCOUNT.DoTextReplacements(submitGuessTxn.text), new CadenceString(word.ToLower()));
_63
while (!submitGuessTask.IsCompleted)
_63
{
_63
int dots = ((int)(Time.time * 2.0f) % 4);
_63
UIManager.Instance.SetStatus("Waiting for server" + new string('.', dots));
_63
yield return null;
_63
}
_63
_63
if (submitGuessTask.Result.Error != null || submitGuessTask.Result.ErrorMessage != string.Empty || submitGuessTask.Result.Status == FlowTransactionStatus.EXPIRED)
_63
{
_63
onFailureCallback();
_63
yield break;
_63
}
_63
_63
// get wordscore
_63
string wordScore = "";
_63
FlowEvent ourEvent = submitGuessTask.Result.Events.Find(x => x.Type.EndsWith(".GuessResult"));
_63
if (ourEvent != null)
_63
{
_63
wordScore = Convert.FromCadence<GuessResultPayload>(ourEvent.Payload).result;
_63
_63
// check if we are out of guesses
_63
if (wordScore == "OutOfGuesses")
_63
{
_63
onFailureCallback();
_63
UIManager.Instance.SetStatus("Out Of Guesses. Try again tomorrow.");
_63
yield break;
_63
}
_63
_63
// process result
_63
onSuccessCallback(word, wordScore);
_63
}
_63
else
_63
{
_63
onFailureCallback();
_63
}
_63
}

LoadHighScoresFromChain

This function fires off a number of small scripts simultaneously, which pull publicly available high score data from the game contract on chain using;

  • get-highscores.cdc
  • get-player-cumulativescore.cdc
  • get-player-guess-distribution.cdc
  • get-player-maxstreak.cdc
  • get-player-scores.cdc
  • get-player-streak.cdc.

It then processes their returned values, and passes them out to the onSuccess call for the high scores UI to render.

For this function, we are going to first fire off a number of simultaneous scripts on the blockchain. This is something you want to avoid with transactions, as transaction order of execution cannot be guaranteed due to the distributed nature of blockchain, however as scripts are read-only, and do not mutate the chain, order of execution is far less likely to matter.

To execute the scripts, add the following code to the top of the function;


_32
// get player's wallet public address
_32
string playerWalletAddress = FlowSDK.GetWalletProvider().GetAuthenticatedAccount().Address;
_32
_32
// execute scripts to get highscore data
_32
Dictionary<string, Task<FlowScriptResponse>> tasks = new Dictionary<string, Task<FlowScriptResponse>>();
_32
tasks.Add("GetHighScores", Scripts.ExecuteAtLatestBlock(FLOW_ACCOUNT.DoTextReplacements(GetHighScores.text)));
_32
tasks.Add("GetPlayerCumulativeScore", Scripts.ExecuteAtLatestBlock(FLOW_ACCOUNT.DoTextReplacements(GetPlayerCumulativeScore.text), new CadenceAddress(playerWalletAddress)));
_32
tasks.Add("GetPlayerWinningStreak", Scripts.ExecuteAtLatestBlock(FLOW_ACCOUNT.DoTextReplacements(GetPlayerWinningStreak.text), new CadenceAddress(playerWalletAddress)));
_32
tasks.Add("GetPlayerMaxWinningStreak", Scripts.ExecuteAtLatestBlock(FLOW_ACCOUNT.DoTextReplacements(GetPlayerMaxWinningStreak.text), new CadenceAddress(playerWalletAddress)));
_32
tasks.Add("GetGuessDistribution", Scripts.ExecuteAtLatestBlock(FLOW_ACCOUNT.DoTextReplacements(GetGuessDistribution.text), new CadenceAddress(playerWalletAddress)));
_32
_32
// wait for completion
_32
bool complete = false;
_32
while (!complete)
_32
{
_32
complete = true;
_32
foreach (KeyValuePair<string, Task<FlowScriptResponse>> task in tasks)
_32
{
_32
complete = complete && task.Value.IsCompleted;
_32
}
_32
yield return null;
_32
}
_32
_32
// check for errors
_32
foreach (KeyValuePair<string, Task<FlowScriptResponse>> task in tasks)
_32
{
_32
if (task.Value.Result.Error != null)
_32
{
_32
onFailureCallback();
_32
yield break;
_32
}
_32
}

This block of code first obtains the public address of the current authenticated player and creates a Dictionary<string, Task> to store our concurrent script tasks.
We then sequentially create async Tasks for each script that we want to execute, using ExecuteAtLatestBlock, and add them to the Task dictionary.

In our use case, we want all of the tasks to complete before we display any results, so our wait for completion code block iterates over every Task in the dictionary, and only moves on once every task.IsComplete.

Checking for errors is similarly done using a foreach loop, where every task is checked to ensure the Error field is null. If even one task has an Error, we call the onFailure callback and break.

Next we need to process the returned values. Add the following code beneath the previous;


_12
// load global highscores
_12
List<ScoreStruct> GlobalScores = Convert.FromCadence<List<ScoreStruct>>(tasks["GetHighScores"].Result.Value);
_12
GlobalScores = GlobalScores.OrderByDescending(score => score.Score).Take(10).ToList();
_12
_12
// load player scores
_12
BigInteger PlayerCumulativeScore = Convert.FromCadence<BigInteger>(tasks["GetPlayerCumulativeScore"].Result.Value);
_12
BigInteger PlayerWinningStreak = Convert.FromCadence<BigInteger>(tasks["GetPlayerWinningStreak"].Result.Value);
_12
BigInteger PlayerMaximumWinningStreak = Convert.FromCadence<BigInteger>(tasks["GetPlayerMaxWinningStreak"].Result.Value);
_12
List<BigInteger> PlayerGuessDistribution = Convert.FromCadence<List<BigInteger>>(tasks["GetGuessDistribution"].Result.Value);
_12
_12
// callback
_12
onSuccessCallback(GlobalScores, PlayerCumulativeScore, PlayerWinningStreak, PlayerMaximumWinningStreak, PlayerGuessDistribution);

Our global highscores are an array of Scores objects in the contract.


_10
access(contract) let TopScores : [Scores]
_10
access(all) struct Scores
_10
{
_10
access(all) let AccId : Address
_10
access(all) let Name : String
_10
access(all) let Score : UInt
_10
}

We have a ScoreStruct defined HighScoresPanel.cs as:


_10
public struct ScoreStruct
_10
{
_10
public string Name;
_10
public BigInteger Score;
_10
}


_10
List<ScoreStruct> GlobalScores = Convert.FromCadence<List<ScoreStruct>>(tasks["GetHighScores"].Result.Value);
_10
GlobalScores = GlobalScores.OrderByDescending(score => score.Score).Take(10).ToList();

Here we get the result of the GetHighScores task and convert it into a List<ScoreStruct>. Then we reorder the list and keep only the highest ten values.

Next, we parse the detailed statistics for the current player, using Convert.FromCadence to convert from the Cadence values into the C# types we want.

Finally, we call the onSuccess callback, passing in all of our parsed results.

Once complete, your function should look as follows;


_50
public IEnumerator LoadHighScoresFromChain(System.Action<List<ScoreStruct>, BigInteger, BigInteger, BigInteger, List<BigInteger>> onSuccessCallback, System.Action onFailureCallback)
_50
{
_50
// get player's wallet public address
_50
string playerWalletAddress = FlowSDK.GetWalletProvider().GetAuthenticatedAccount().Address;
_50
_50
// execute scripts to get highscore data
_50
Dictionary<string, Task<FlowScriptResponse>> tasks = new Dictionary<string, Task<FlowScriptResponse>>();
_50
tasks.Add("GetHighScores", Scripts.ExecuteAtLatestBlock(FLOW_ACCOUNT.DoTextReplacements(GetHighScores.text)));
_50
tasks.Add("GetPlayerCumulativeScore", Scripts.ExecuteAtLatestBlock(FLOW_ACCOUNT.DoTextReplacements(GetPlayerCumulativeScore.text), new CadenceAddress(playerWalletAddress)));
_50
tasks.Add("GetPlayerWinningStreak", Scripts.ExecuteAtLatestBlock(FLOW_ACCOUNT.DoTextReplacements(GetPlayerWinningStreak.text), new CadenceAddress(playerWalletAddress)));
_50
tasks.Add("GetPlayerMaxWinningStreak", Scripts.ExecuteAtLatestBlock(FLOW_ACCOUNT.DoTextReplacements(GetPlayerMaxWinningStreak.text), new CadenceAddress(playerWalletAddress)));
_50
tasks.Add("GetGuessDistribution", Scripts.ExecuteAtLatestBlock(FLOW_ACCOUNT.DoTextReplacements(GetGuessDistribution.text), new CadenceAddress(playerWalletAddress)));
_50
_50
// wait for completion
_50
bool complete = false;
_50
while (!complete)
_50
{
_50
complete = true;
_50
foreach (KeyValuePair<string, Task<FlowScriptResponse>> task in tasks)
_50
{
_50
complete = complete && task.Value.IsCompleted;
_50
}
_50
yield return null;
_50
}
_50
_50
// check for errors
_50
foreach (KeyValuePair<string, Task<FlowScriptResponse>> task in tasks)
_50
{
_50
if (task.Value.Result.Error != null)
_50
{
_50
onFailureCallback();
_50
yield break;
_50
}
_50
}
_50
_50
// load global highscores
_50
List<ScoreStruct> GlobalScores = Convert.FromCadence<List<ScoreStruct>>(tasks["GetHighScores"].Result.Value);
_50
GlobalScores = GlobalScores.OrderByDescending(score => score.Score).Take(10).ToList();
_50
_50
// load player scores
_50
BigInteger PlayerCumulativeScore = Convert.FromCadence<BigInteger>(tasks["GetPlayerCumulativeScore"].Result.Value);
_50
BigInteger PlayerWinningStreak = Convert.FromCadence<BigInteger>(tasks["GetPlayerWinningStreak"].Result.Value);
_50
BigInteger PlayerMaximumWinningStreak = Convert.FromCadence<BigInteger>(tasks["GetPlayerMaxWinningStreak"].Result.Value);
_50
List<BigInteger> PlayerGuessDistribution = Convert.FromCadence<List<BigInteger>>(tasks["GetGuessDistribution"].Result.Value);
_50
_50
// callback
_50
onSuccessCallback(GlobalScores, PlayerCumulativeScore, PlayerWinningStreak, PlayerMaximumWinningStreak, PlayerGuessDistribution);
_50
_50
yield return null;
_50
}

Step 5 – Play FlowWords!

If you have correctly followed all of the steps above, you will now have a working project.

  1. Return to the Unity editor, and press the Play button.
  2. Enter a friendly name - this will appear on the leaderboard.
  3. Click Log In.
  4. Select an account from the dialog that appears to authenticate with.

You should see the login screen, say Connecting…, and then Loading…

Login Panel User Interface

Followed shortly thereafter by the game screen;

Game User Interface

And the High Scores screen (if you click the button);

HighScores User Interface

Step 6 – Further Experimentation

For an extra challenge, try some of the following;

  • Add more accounts and play with some friends, hot seat style
  • Modify the game-contract.cdc to make a new game every 5 minutes instead of every 24 hours.
  • Try to remove and redeploy the contract
    (hint: on testnet and mainnet, once removed, a contract’s name can never be used again on the same account)
    (extra hint: delete-game-resources.cdc)
  • Poke about in the game contracts, scripts and transactions to see what they do!

If you ever get the emulator into a messy state, you can always hit the Clear Persistent Data button, which will wipe the emulator back to its blank state. This will of course lose all deployed contracts and high score and game history.

Appendix – How to convert FlowWords to run on TestNet

To modify the tutorial project to run on TestNet, only minor modifications are required.

  1. Change the network configuration to point to TestNet
  2. Replace the DevWallet provider with a more secure solution. e.g. WalletConnect
  3. Configure Account and update Text Replacements
  4. Deploy the contract to TestNet

Change the network configuration to TestNet

To change the network configuration, simply modify the start function as follows;


_18
private void Start()
_18
{
_18
if (Instance != this)
_18
{
_18
Destroy(this);
_18
}
_18
_18
// Set up SDK to access TestNet
_18
FlowConfig flowConfig = new FlowConfig()
_18
{
_18
NetworkUrl = "https://rest-testnet.onflow.org/v1", // testnet
_18
Protocol = FlowConfig.NetworkProtocol.HTTP
_18
};
_18
FlowSDK.Init(flowConfig);
_18
_18
// Register DevWallet wallet provider with SDK
_18
FlowSDK.RegisterWalletProvider(new DevWalletProvider());
_18
}

We have now replaced the emulator address with the address for the TestNet access point, and all subsequent transactions and scripts will be directed to TestNet.

Replace DevWallet with WalletConnect

To now change the wallet provider, simply modify the start function as follows;


_29
private void Start()
_29
{
_29
if (Instance != this)
_29
{
_29
Destroy(this);
_29
}
_29
_29
// Set up SDK to access TestNet
_29
FlowConfig flowConfig = new FlowConfig()
_29
{
_29
NetworkUrl = "https://rest-testnet.onflow.org/v1", // testnet
_29
Protocol = FlowConfig.NetworkProtocol.HTTP
_29
};
_29
FlowSDK.Init(flowConfig);
_29
_29
// Create WalletConnect wallet provider
_29
IWallet walletProvider = new WalletConnectProvider();
_29
walletProvider.Init(new WalletConnectConfig
_29
{
_29
ProjectId = "<YOUR PROJECT ID>", // insert Project ID from Wallet Connect dashboard
_29
ProjectDescription = "A simple word guessing game built on FLOW!",
_29
ProjectIconUrl = "https://walletconnect.com/meta/favicon.ico",
_29
ProjectName = "FlowWords",
_29
ProjectUrl = "https://dapperlabs.com"
_29
});
_29
_29
// Register WalletConnect wallet provider with SDK
_29
FlowSDK.RegisterWalletProvider(walletProvider);
_29
}

You will also need to add the following using declarations to the top of the file;


_10
using DapperLabs.Flow.Sdk.WalletConnect;
_10
using DapperLabs.Flow.Sdk.Crypto;

For this modification we have created a new WalletConnectProvider, and initialized it, and then registered our new WalletConnectProvider.

The only thing missing is a Project Id.
Each WalletConnect application requires its own project id. You can get one by going to https://cloud.walletconnect.com and signing up for an account.
You can then create a new project on the website, give it a name (we suggest FlowWords), and enter the project id provided into your code.

Finally, we need one more change to make sure our text replacement still functions correctly.

At the beginning of the OnAuthSuccess function, change the FLOW_ACCOUNT GatewayName from "Emulator" to "Flow Testnet".


_10
// get FLOW account - we are only going to use this for text replacements
_10
FLOW_ACCOUNT = new FlowControl.Account
_10
{
_10
GatewayName = "Flow Testnet",
_10
AccountConfig = new Dictionary<string, string> { { "Address", FlowSDK.GetWalletProvider().GetAuthenticatedAccount().Address } }
_10
};

Configure Account and update Text Replacements

To deploy the contract to TestNet, the only current way to do so via the FlowSDK, is to use a TestNet account to which you know the private key.

First, in the Accounts tab of the Flow Control window, create a new account by clicking the plus '+' icon at the top of the window.
Create the new account as follows, replacing the Address and Private Key with your own valid TestNet address / private key pair.

New Account Example

Switch to the Text Replacements tab of the Flow Control window now, and create a new text replacement definition as follows, replacing the given replacement text with the address to your TestNet account.

New Text Replacement Example

Now modify the existing CONTRACT_NAME text replacement, by changing the Apply to Gateways field from Emulator, to All. This will make sure this replacement also applies to TestNet transactions.

Deploy the Contract to TestNet

Now that all of the configuration is done, you can deploy the contract.

On the Tools tab of the Flow Control window, set up the Manage Contracts section as follows;

New Account Example

Where;

  • Contract Name is the name of the contract on the blockchain. This should match the text replacement configured for CONTRACT_NAME
  • Contract is the game-contract.cdc asset included with the project sample in the Assets\Samples\Flow SDK\<version>\Flow Words Tutorial Assets\Resources directory.
  • Account is the new Deploy Account that you created in the previous step.

Once you have the Manage Contracts section filled in as per the example, click Deploy Contract.

If all goes well, you will see the text 'Executing Transaction' appear below the Deploy Contract button, followed by a clickable link to the transaction result on Flowdiver.

Congratulations! You can now run FlowWords, and play the game with a WalletConnect compatible wallet!

NOTE: TestNet requires that all contracts deployed to an account have a unique name, does not allow contract removal without authorisation, and only allows contract updates that do not break interfaces or data structures or introduce undefined data to existing resources.

Due to these limitations, iterative development should always be done on Emulator before attempting to push anything to a live network.