Skip to main content

Unity への BlsquiSDK 組み込みガイド|手数料0%のゲーム内決済&Web3ウォレット連携

Updated Markdown
Part of seriesMeta-Developers Labo

Unity製のゲームにブロックチェーンアイテムやeスポーツ賞金配布、ゲーム内決済を組み込む際、複雑な暗号処理やプレイヤーに手間を強いるブラウザ拡張機能はもう必要ありません。 本記事では、公式リポジトリ BlsquiSDK-Unity(https://github.com/blsqui/BlsquiSDK-Unity )をUnityプロジェクトにインポートし、初期セットアップからWebRTCによるリアルタイム連携までを行う手順をわかりやすく解説します。


まず最初にUnity プロジェクトを開きます。

以下を参考にしてSDKを追加します。

URLと表示されているところにこのURLを入力します。

https://github.com/blsqui/BlsquiSDK-Unity.git

Installボタンをクリックします。


自動的にビルドが走ります。

ここでSDKのコードの中身について紹介します。

Unity開発者がスマートコントラクトの難解な仕様や暗号署名の実装を意識することなく、普段通りのC#(async / await やイベント購読)の感覚で組み込めるよう、SDKは以下の4つのスクリプトに分けて設計しています。

  • BlsquiCurrentUser(セッション&インベントリ管理シングルトン)DontDestroyOnLoad 付きのシングルトン MonoBehaviour として動作し、シーン遷移を跨いでもプレイヤーのログイン状態やウォレットアドレスを維持します。ダッシュボードの起動(OpenDashboard)やゲーム側からのアイテム使用トリガー(RequestUseItem)、さらに外部Webダッシュボードから飛んでくる装備変更・アイテム使用イベント(OnItemUseRequested)の受信を一手に担います。
  • BlsquiSDK(トランザクション実行&非同期ポーリングエンジン)await BlsquiSDK.RequestTransaction(options) を1行呼ぶだけで、改ざん防止用の署名付きセッショントークンの発行からブラウザゲートウェイの起動、ブロック確定(SEALED)までの非同期ポーリングをメインスレッド(FPS)を止めずに自動実行し、結果(TxResult)を返します。外部JSONライブラリに依存しない軽量なシリアライズ設計を採用しています。
  • BlsquiWebRTCPresence(ゼロラグP2P通信ブリッジ) Unity公式の Unity.WebRTC パッケージをラップし、ゲームクライアントとWebウォレット(ダッシュボード)をWebRTC DataChannelで直接つなぎます。Webダッシュボード側で武器スロットを付け替えたりアイテム使用ボタンを押したりした瞬間に、ミリ秒単位の低遅延でゲーム画面へリアルタイム同期されます。
  • BlsquiStageSlot(オンチェーン装備スロット照会・スカウター機能) FlowのAccess Node REST APIへCadenceスクリプトを直接送信し、任意のプレイヤーが装備しているNFTアイテムスロット(StageSlotItem)を取得するユーティリティです。ウォレット接続や署名なしで他プレイヤーの装備構成をリアルタイムに参照できるため、対戦前のロードアウト表示やスカウター機能の実装にそのまま使えます。

次にプロジェクトにBlsquiSDKを組み込んでいきます。

SDKを使用するファイルに以下の2つのインポートを行います。

using System.Collections.Generic;
using Blsqui.SDK;

ダッシュボードの表示や、装備スロットの状態取得のみを行う場合は、using Blsqui.SDK; を追加するだけで十分です。


特定のブロックチェーンアカウントの装備スロットの状態を取得する

BlsquiStageSlot.GetStageSlotsを呼び出します。

using System.Text;
using UnityEngine;
using TMPro;
using Blsqui.SDK;

public class ScoutButtonHandler : MonoBehaviour
{
    private const string TARGET_ADDRESS = "0x2f13c512df0b0ad7";
    private const string PUBLISHER_ADDRESS = "0x2f13c512df0b0ad7";
    private const string APP_ID = "valkyrie_vanguard";

    [Header("UI Dialog References")]
    [SerializeField] private GameObject tournamentDialog;
    [SerializeField] private TMP_Text titleText;
    [SerializeField] private TMP_Text messageText;
    [SerializeField] private GameObject cancelButton; // Will be hidden for Scout modal

    public async void ScoutOpponentSlots()
    {
        Debug.Log($"[Scout] Querying equipped slots for: {TARGET_ADDRESS}");

        // 1. Show immediate loading feedback on the dialog
        if (tournamentDialog != null)
        {
            if (cancelButton != null) cancelButton.SetActive(false);
            if (titleText != null) titleText.text = "Scouting Opponent...";
            if (messageText != null) messageText.text = $"Connecting to Flow Access Node...\nTarget: {TARGET_ADDRESS}";
            tournamentDialog.SetActive(true);
        }

        // 2. Fetch equipped slots from Flow Testnet
        var slots = await BlsquiStageSlot.GetStageSlots(new StageSlotOptions
        {
            targetAddress = TARGET_ADDRESS,
            publisherAddress = PUBLISHER_ADDRESS,
            appId = APP_ID,
            isTestnet = true,
            verbose = true
        });

        // 3. Format and display the scouted results
        if (tournamentDialog != null && messageText != null)
        {
            if (titleText != null) titleText.text = "Opponent Loadout";

            int maxSlotsToShow = 3;
            var sb = new StringBuilder();
            sb.AppendLine($"Target: {TARGET_ADDRESS}");
            sb.AppendLine("Equipped Item Slots:\n");

            bool hasAnyEquipped = false;
            int count = 0;

            foreach (var slot in slots)
            {
                if (count >= maxSlotsToShow)
                {
                    break;
                }

                if (!string.IsNullOrWhiteSpace(slot.itemId))
                {
                    hasAnyEquipped = true;
                    sb.AppendLine($"• Slot {slot.slotIndex}: {slot.itemId}");
                }
                else
                {
                    sb.AppendLine($"• Slot {slot.slotIndex}: (Empty)");
                }

                count++;
            }

            if (!hasAnyEquipped)
            {
                sb.AppendLine("No items equipped in stage slots.");
            }

            messageText.text = sb.ToString();
        }
    }

    // Hooked to ConfirmButton.onClick to dismiss the modal
    public void OnCloseScoutDialog()
    {
        if (tournamentDialog != null)
        {
            tournamentDialog.SetActive(false);
        }
    }
}

このコードをあるボタンのクリックイベントとして結びつけます。

イベントを実行すると以下のように指定したアドレスのスロット情報を取得できます。


ダッシュボードを開く。ダッシュボードに表示されるスロットの情報を取得する。

BlsquiCurrentUser.Instance.OpenDashboardを呼び出します。

using System.Collections.Generic;
using UnityEngine;
using Blsqui.SDK;

public class HubButtonHandler : MonoBehaviour
{
    [Header("App Config")]
    [SerializeField] private string appId = "valkyrie_vanguard";
    [SerializeField] private string publisherAddress = "0x2f13c512df0b0ad7";
    [SerializeField] private string network = "testnet";

    private void Start()
    {
        // Ensure BlsquiCurrentUser manager exists in scene
        if (BlsquiCurrentUser.Instance == null)
        {
            var userGo = new GameObject("BlsquiCurrentUser");
            var user = userGo.AddComponent<BlsquiCurrentUser>();
            user.Configure(appId, publisherAddress, network);
        }
        else
        {
            BlsquiCurrentUser.Instance.Configure(appId, publisherAddress, network);
        }

        // Subscribe to real-time user profile & equipped slot updates from the dashboard
        BlsquiCurrentUser.Instance.OnUserUpdated += HandleUserUpdated;
        BlsquiCurrentUser.Instance.OnSlotsUpdated += HandleSlotsUpdated;
    }

    private void OnDestroy()
    {
        if (BlsquiCurrentUser.Instance != null)
        {
            BlsquiCurrentUser.Instance.OnUserUpdated -= HandleUserUpdated;
            BlsquiCurrentUser.Instance.OnSlotsUpdated -= HandleSlotsUpdated;
        }
    }

    public void OnHubClicked()
    {
        Debug.Log("[Hub] Opening Blsqui Dashboard...");
        BlsquiCurrentUser.Instance.OpenDashboard();
    }

    private void HandleUserUpdated(CurrentUserState user)
    {
        if (user.loggedIn)
        {
            Debug.Log($"[Hub] Dashboard Connected | Player: {user.addr} | Name: {user.userName}");
        }
        else
        {
            Debug.Log("[Hub] Player logged out from Dashboard.");
        }
    }

    private void HandleSlotsUpdated(List<StageSlotItem> slots)
    {
        Debug.Log($"[Hub] Synced {slots.Count} equipped slot(s) from Dashboard:");
        foreach (var slot in slots)
        {
            Debug.Log($"  - Slot {slot.slotIndex}: {slot.itemId}");
        }
    }
}

OpenDashboard() を呼び出すと、ブラウザでダッシュボードが開くと同時にバックグラウンドでWebRTC DataChannelが確立されます。

OnUserUpdated と OnSlotsUpdated イベントを購読しておくことで、ダッシュボード側でログインしたプレイヤーのウォレットアドレスや装備中のアイテムスロット情報がリアルタイムにUnity側へ同期されます。

このコードをあるボタンのクリックイベントとして結びつけます。

イベントを実行すると以下のようにダッシュボードが開きます。

同時にUnityにはプレイヤーの情報とスロットの情報が伝えられます。


アイテム購入

BlsquiSDK.RequestTransactionを呼び出します。

using System.Collections.Generic;
using UnityEngine;
using TMPro;
using Blsqui.SDK;

public class ShopButtonHandler : MonoBehaviour
{
    private const string WEAPON_SHOP_FLIX_ID = "351d9d6f23ebe5ddbe9bf5b4f937a352c5caaa6a4439b5e464f3b16c1d671472";

    [Header("UI Dialog References")]
    [SerializeField] private GameObject tournamentDialog;
    [SerializeField] private TMP_Text titleText;
    [SerializeField] private TMP_Text messageText;
    [SerializeField] private GameObject cancelButton;

    public async void OnShopButtonClicked()
    {
        Debug.Log("[Shop] Opening purchase transaction...");

        // Show transaction feedback in the dialog
        if (tournamentDialog != null)
        {
            if (cancelButton != null) cancelButton.SetActive(false);
            if (titleText != null) titleText.text = "Processing Shop Item...";
            if (messageText != null) messageText.text = "Authorizing transaction on Flow...\nPlease complete payment in the browser.";
            tournamentDialog.SetActive(true);
        }

        
        var options = new TxOptions
        {
            isTestnet = true,
            verbose = true,
            flixId = "351d9d6f23ebe5ddbe9bf5b4f937a352c5caaa6a4439b5e464f3b16c1d671472",
            args = new Dictionary<string, string>()
        };

        TxResult result = await BlsquiSDK.RequestTransaction(options);

        // Update dialog state upon completion
        if (result.status == "SEALED")
        {
            Debug.Log($"Shop purchase succeeded! TX ID: {result.txId}");
            if (titleText != null) titleText.text = "Purchase Successful!";
            if (messageText != null) messageText.text = $"Item purchase sealed !!!\n\nTX ID:\n{result.txId}";
        }
        else
        {
            string err = !string.IsNullOrEmpty(result.errorMessage) ? result.errorMessage : result.error;
            Debug.LogWarning($"[Shop] Purchase incomplete. Status: {result.status} | Error: {err}");
            if (titleText != null) titleText.text = "Transaction Cancelled";
            if (messageText != null) messageText.text = $"Status: {result.status}\n{err}";
        }
    }
}

このコードをあるボタンのクリックイベントとして結びつけます。

イベントを実行するとSDKのトランザクション画面が開きます。アイテムが購入されるとアイテムを登録したアカウントに代金の全額が振り込まれます。


ブロックチェーンアイテムの使用を促す

BlsquiCurrentUser.Instance.RequestUseItemを呼び出します。

using System.Collections.Generic;
using System.Threading.Tasks;
using UnityEngine;
using TMPro;
using Blsqui.SDK;

public class ActionButtonsController : MonoBehaviour
{
    private const string WEAPON_ITEM_ID = "wpn_dragon_piercer_b";
    private const string SHIELD_ITEM_ID = "shd_valkyrie_aegis_b";

    [Header("DEF Button (Button2)")]
    [SerializeField] private SpriteRenderer defRenderer;
    [SerializeField] private Collider2D defCollider;

    [Header("ATK Button (Button5)")]
    [SerializeField] private SpriteRenderer atkRenderer;
    [SerializeField] private Collider2D atkCollider;

    [Header("UI Dialog References")]
    [SerializeField] private GameObject tournamentDialog;
    [SerializeField] private TMP_Text titleText;
    [SerializeField] private TMP_Text messageText;
    [SerializeField] private GameObject cancelButton;

    private const float DISABLED_ALPHA = 0.2f;
    private const float ENABLED_ALPHA = 1.0f;
    private bool isSubscribed = false;

    private void Awake()
    {
        // Force initial disabled visual
        SetButtonVisualState(defRenderer, defCollider, false);
        SetButtonVisualState(atkRenderer, atkCollider, false);
    }

    private void Start()
    {
        TrySubscribe();
    }

    private void Update()
    {
        // Fallback: If BlsquiCurrentUser spawned after Start(), catch it here
        if (!isSubscribed)
        {
            TrySubscribe();
        }
    }

    private void TrySubscribe()
    {
        if (BlsquiCurrentUser.Instance != null && !isSubscribed)
        {
            BlsquiCurrentUser.Instance.OnSlotsUpdated += UpdateEquipmentButtons;
            BlsquiCurrentUser.Instance.OnItemUseRequested += HandleItemUseRequested;
            isSubscribed = true;
            Debug.Log(" ActionButtonsController successfully subscribed to BlsquiCurrentUser.OnSlotsUpdated!");
        }
    }

    private void OnDestroy()
    {
        if (BlsquiCurrentUser.Instance != null && isSubscribed)
        {
            BlsquiCurrentUser.Instance.OnSlotsUpdated -= UpdateEquipmentButtons;
            BlsquiCurrentUser.Instance.OnItemUseRequested -= HandleItemUseRequested;
            isSubscribed = false;
        }
    }

    public void UpdateEquipmentButtons(List<StageSlotItem> equippedSlots)
    {
        int slotCount = equippedSlots?.Count ?? 0;
        Debug.Log($"[ActionButtons] Received slots update! Count: {slotCount}");

        bool hasShield = false;
        bool hasWeapon = false;

        if (equippedSlots != null)
        {
            foreach (var slot in equippedSlots)
            {
                if (slot == null) continue;

                Debug.Log($"[ActionButtons] Slot {slot.slotIndex}: {slot.itemId}");

                if (string.IsNullOrEmpty(slot.itemId)) continue;

                if (slot.itemId == SHIELD_ITEM_ID)
                {
                    hasShield = true;
                }
                else if (slot.itemId == WEAPON_ITEM_ID)
                {
                    hasWeapon = true;
                }
            }
        }

        Debug.Log($"[ActionButtons] Applying state -> Shield: {hasShield}, Weapon: {hasWeapon}");
        SetButtonVisualState(defRenderer, defCollider, hasShield);
        SetButtonVisualState(atkRenderer, atkCollider, hasWeapon);
    }

    private void SetButtonVisualState(SpriteRenderer sr, Collider2D col, bool isEnabled)
    {
        if (sr != null)
        {
            Color c = sr.color;
            c.a = isEnabled ? ENABLED_ALPHA : DISABLED_ALPHA;
            sr.color = c;
        }

        if (col != null)
        {
            col.enabled = isEnabled;
        }
    }

    public void OnDefButtonClicked()
    {
        Debug.Log("[ActionButtons] DEF Button clicked -> Requesting shd_valkyrie_aegis_b");
        if (BlsquiCurrentUser.Instance != null)
        {
            BlsquiCurrentUser.Instance.RequestUseItem(SHIELD_ITEM_ID);
        }
    }

    public void OnAtkButtonClicked()
    {
        Debug.Log("[ActionButtons] ATK Button clicked -> Requesting wpn_dragon_piercer_b");
        if (BlsquiCurrentUser.Instance != null)
        {
            BlsquiCurrentUser.Instance.RequestUseItem(WEAPON_ITEM_ID);
        }
    }

    private async void HandleItemUseRequested(ItemUseRequestPayload payload)
    {
        Debug.Log($"[ActionButtons] Received execution request for {payload.itemId} #{payload.serialNumber} (FLIX: {payload.flixId})");

        // Show immediate progress dialog
        if (tournamentDialog != null)
        {
            if (cancelButton != null) cancelButton.SetActive(false);
            if (titleText != null) titleText.text = "Executing Action...";
            if (messageText != null) messageText.text = $"Authorizing transaction on Flow...\nItem: {payload.itemId} (Serial #{payload.serialNumber})";
            tournamentDialog.SetActive(true);
        }

        // Prepare transaction arguments matching FLIX template parameter requirements
        var txArgs = new Dictionary<string, string>
        {
            { "publisherAddress", payload.publisherAddress },
            { "appId", payload.appId },
            { "itemId", payload.itemId },
            { "serialNumber", payload.serialNumber.ToString() }
        };

        var options = new TxOptions
        {
            isTestnet = true,
            verbose = true,
            flixId = payload.flixId,
            args = txArgs
        };

        // 3. Request signed transaction session via Blsqui SDK gateway
        TxResult result = await BlsquiSDK.RequestTransaction(options);

        // 4. Update the dialog with final state
        if (result.status == "SEALED")
        {
            Debug.Log($"🎉 Item action sealed! TX ID: {result.txId}");
            if (titleText != null) titleText.text = "Action Complete!";
            if (messageText != null) messageText.text = $"[GAME] ITEM USED SUCCESSFULLY !!!\n{payload.itemId} (Serial #{payload.serialNumber})\n\nTX: {result.txId}";
        }
        else
        {
            string err = !string.IsNullOrEmpty(result.errorMessage) ? result.errorMessage : result.error;
            Debug.LogWarning($"Action failed: {result.status} | {err}");
            if (titleText != null) titleText.text = "Action Cancelled";
            if (messageText != null) messageText.text = $"Status: {result.status}\n{err}";
        }
    }

}

OnDefButtonClicked / OnAtkButtonClicked ボタン押下時に対象の ItemId をセットして RequestUseItem を呼び出し、ダッシュボードへアイテム使用を促すメッセージを送信しています。

OnSlotsUpdated を購読して装備中のアイテムのみボタンを有効化しています。

後半の HandleItemUseRequested は、ユーザーがダッシュボード上でアイテム使用を確定した際に自動で実行されるハンドラです。

Publisher Address、App ID、Item ID、Serial Number を TxOptions.args に渡して一意のアイテム使用トランザクションを BlsquiSDK.RequestTransaction に送信し、確定(SEALED)後に結果をUIへ反映しています。

ダッシュボードが開いている状態でこのイベントを実行すると、アイテムの使用を促すことができます。

Try it out!

  1. モニターを2つ並べてゲームからダッシュボードを呼び出します。
  1. アイテムを使用して欲しい時にアイテムの使用を促します。

事前にダッシュボードを開いていると、このように指定したアイテムが光ります。一定時間以内にボタンを押すとゲームに通知されます。

  1. アイテム使用のトランザクションが実行されます。
  1. ゲーム側でトランザクション結果を受け取ります。

About the author

  • Founder & Architect of Blsqui. Building the cloud-native infrastructure layer that transforms standard video games into instant Web3 eSports platforms. Passionate about democratizing global revenue networks for the next generation of independent, AI-driven creators. Creating plug-and-play, no-code backend frameworks for Unity and Godot that integrate frictionless stablecoin microtransactions without client-side execution overhead.

No comments yet. Be the first to comment.