Quickstart

Follow these steps to install the Tezos SDK for Unity in an existing Unity project and start using it.

These instructions cover:

Installing the SDK into an existing Unity project
Testing that the SDK works in your project
Adding objects that connect to a user's Tezos wallet

Connecting to a user's wallet is a prerequisite to working with Tezos in any application. Accessing the wallet allows your project to see the tokens in it and to prompt the user to submit transactions, but it does not give your project direct control over the wallet. Users must still confirm all transactions in their wallet application.

Using a wallet application in this way saves you from having to implement payment processing and security in your application. Game developers can also use the wallet and its account as a unique account identifier and as the user's inventory.

Make sure that you have Unity Editor version 2021.3.23f1 or later.
Install a Tezos-compatible wallet on a mobile device that has a camera and can scan QR codes. If you don't have a wallet on a mobile device, follow these steps:
1. Install a Tezos-compatible wallet app on a mobile device. Mobile wallet apps for Tezos include Temple, Kukai, and Umami.
2. Switch the wallet to use Ghostnet testnet instead of Tezos Mainnet. Ghostnet is a network for testing Tezos applications where tokens are free so you don't have to spend real currency to work with your applications.
  
  The process for changing the network is different for each wallet type. These steps are for the Temple wallet:
  1. Go to https://teztnets.xyz/, which lists Tezos testnets.
  2. Click Ghostnet.
  3. Copy one of the public RPC endpoints for Ghostnet, such as https://rpc.ghostnet.teztnets.xyz. These URLs accept Tezos transactions from wallets and other applications.
  4. In the Temple app, open the settings and then click Default node (RPC).
  5. Click the plus + symbol to add an RPC node.
  6. On the Add RPC screen, enter the URL that you copied and give the connection a name, such as "Ghostnet," as shown in this picture:
  7. Click Add.
  8. Make sure that the new RPC node is selected, as in this image:
3. From your wallet, get the address of your account, which starts with tz1. This is the address that applications use to work with your wallet.
4. Get some testnet tez for the wallet:
  1. Go to the Ghostnet faucet at https://faucet.ghostnet.teztnets.xyz. This faucet provides tez for free to use on the testnet.
  2. On the faucet page, paste your wallet address into the input field labeled "Or fund any address" and click the button for the amount of tez to add to your wallet. 20 tez is enough to work with, and you can return to the faucet later if you need more tez.
    
    It may take a few minutes for the faucet to send the tokens and for those tokens to appear in your wallet.
    
    You can use the faucet as much as you need to get tokens on the testnet, but those tokens are worthless and cannot be used on Mainnet.
Install the SDK through the Unity asset store:
1. In the Unity asset store, find the Tezos SDK for Unity.
2. Click Add to My Assets.
3. In the Unity Editor, in the Package Manager panel, find the Tezos SDK for Unity and click the Download button.
4. TODO double-check these instructions when the new package is available on the asset store.
5. Verify that the SDK is installed by opening the Project panel and expanding the Assets > TezosSDK folder.
If you see the TezosSDK folder with sub-folders including Editor, Examples, Resources, and Runtime, the SDK is installed correctly.
Verify that the SDK works in your project by running the WalletConnection example scene, which demonstrates how to connect to a Tezos wallet in a Unity project:
1. In the Unity Editor, in the Project panel, open the Assets > TezosSDK > Examples folder and click the WalletConnection folder.
2. In the WalletConnection folder, double-click the _WalletConnection scene to open it in the editor.
3. Click the Play button to run the scene.
4. Open the Simulator panel, which shows a QR code.
5. Use your wallet app to scan the barcode and confirm the connection to the Unity project. The project UI shows the address of the connected account, as in this picture:
Add the prerequisite SDK components to your scene:
1. Open a scene in your project or create a scene.
2. In the Project panel, expand Assets > TezosSDK > Runtime > Prefabs.
3. From the Prefabs folder in the Project panel, drag the MainThreadExecutor prefab to the Hierarchy panel.
4. In the same way, drag the TezosManager prefab to the Hierarchy panel. The TezosManager prefab opens in the Inspector panel.
5. In the Inspector panel, set the information for your project, including its name and URL.
  
  This prefab provides prerequisites to use Tezos in a scene. Its fields control what users see in their wallet applications before connecting to the project.
Copy the necessary objects to the scene:
1. Open the _WalletConnection scene again.
2. In the Hierarchy panel, expand the Canvas object.
3. Under Canvas, select the following objects by holding Ctrl or Cmd and clicking them:
  - ConnectedText
  - QRCode
  - LogoutButton
  - MetadataInfo
  - AccountAddress
4. Right-click the elements and then click Copy.
5. Go back to your scene and paste the objects into the scene's canvas in the Hierarchy panel. The Hierarchy panel looks like this:
6. If the objects appear outside the border of your scene, reposition them on the canvas.
7. Save the scene.
8. Click the Play button to run the scene.
9. Open the Simulator panel, which shows a QR code.
10. Use your wallet app to scan the barcode and confirm the connection to the Unity project. Note that the wallet app shows the name of the project that you set on the TezosManager prefab.
  
  The project shows the address that you used to connect.
11. Click the Logout button and then click the Play button to stop the scene.
Add text to show the account's balance in tez:
1. In the Hierarchy pane, right click the Canvas object and then click Create Empty.
2. Name the new object "AccountBalance."
3. Right-click the AccountBalance object and then click UI > Text - TextMeshPro.
4. Name the new text object "Label" and set its text to "Account balance:".
5. In the Scene panel, move the new text object to below the text "Account Address." If you can't find the text object, you can right-click the label object in the Hierarchy panel and then click Move To View.
6. In the Hierarchy pane, right-click the AccountBalance object and then click UI > Text - TextMeshPro again.
7. Name the new text object "Balance," clear its default text, and move it to the right of the Label object.
8. In the Hierarchy pane, select the AccountBalance object, not the Label or Balance sub-objects.
9. At the bottom of the Inspector pane, click Add Component.
10. Click New Script, name the script "AccountBalance," and click Create and Add.
  
  The new script appears in the Inspector pane, as in this image:
11. Double-click the AccountBalance script to open the script file in your IDE.
12. At the top of the file, add these imports:
```
using TMPro;
using TezosSDK.Tezos;
using TezosSDK.Beacon;
```
13. Inside the AccountBalance class, add this variable to represent the text in the Balance object:
```
public TMP_Text balance;
```
14. Inside the Start function, add these lines of code to add listeners:
```
TezosManager.Instance.MessageReceiver.AccountConnected += OnAccountConnected;
TezosManager.Instance.MessageReceiver.AccountDisconnected += OnAccountDisconnected;
```
  These lines of code set functions that respond to events in the Tezos SDK. In this case, they set functions that run when the user's account connects or disconnects.
15. After the Start function, add these functions:
```
private void OnAccountConnected(AccountInfo account_info)
{
   var routine = TezosManager.Instance.Tezos.GetCurrentWalletBalance(OnBalanceFetched);
   StartCoroutine(routine);
}

private void OnBalanceFetched(ulong balance)
{
   balance.text = $"{mutezBalance / 1000000f}";
}

private void OnAccountDisconnected(AccountInfo account_info)
{
   balance.text = "";
}
```
  The OnAccountConnected function runs when the account connects. It creates a routine that fetches the account balance and sets the OnBalanceFetched function as a callback. When the SDK returns the balance, the OnBalanceFetched function updates the text.
  
  The complete script file looks like this:
```
using System.Collections;
using System.Collections.Generic;
using UnityEngine;

using TMPro;
using TezosSDK.Tezos;
using TezosSDK.Beacon;

public class AccountBalance : MonoBehaviour
{
    public TMP_Text balance;

    // Start is called before the first frame update
    void Start()
    {
        TezosManager.Instance.MessageReceiver.AccountConnected += OnAccountConnected;
        TezosManager.Instance.MessageReceiver.AccountDisconnected += OnAccountDisconnected;
    }

    private void OnAccountConnected(AccountInfo account_info)
    {
        var routine = TezosManager.Instance.Tezos.GetCurrentWalletBalance(OnBalanceFetched);
        StartCoroutine(routine);
    }

    private void OnBalanceFetched(ulong mutezBalance)
    {
        balance.text = $"{mutezBalance / 1000000f}";
    }

    private void OnAccountDisconnected(AccountInfo account_info)
    {
        balance.text = "";
    }

    // Update is called once per frame
    void Update()
    {

    }
}
```
  1. Save the file.
  2. In the Unity Editor, in the Hierarchy pane, drag the Balance object to the Balance field of the Account Balance script in the Inspector pane. Now the Balance object on the canvas is bound to the balance variable in the script, as shown in this picture:
  3. Run the project, connect your wallet, and see that the UI shows the account's balance in tez.
  Now you can bind objects to variables in the code and use listeners to respond to Tezos SDK events. For the complete list of listeners, see the file Assets/TezosSDK/Runtime/Scripts/Beacon/WalletEventManager.cs in the SDK.

Now that your project can connect to a user's account, you can use this connection to identify a user's account, because Tezos addresses are unique. You can also use this connection to send transactions to Tezos on behalf of the user, such as manipulating Tezos tokens as game assets. For examples, see the scenes in the TezosSDK/Examples folder.

Note that if you stop the project while your wallet is connected and restart the project later, it remembers that your wallet is connected. The SDK uses the Beacon SDK to connect to wallets and remember connections.