Connect wallet to view library

examples

Examples

Complete, working examples for common use cases with the Arcadia Game SDK.

Basic Integration
Wallet Integration
Pay-to-Play
In-Game Purchases
Complete Game Example
TypeScript Example
Error Handling

Basic Integration

Minimal example showing SDK initialization and wallet address retrieval.

<!DOCTYPE html>
<html>
<head>
  <title>Basic SDK Integration</title>
  <script src="https://cdn.jsdelivr.net/npm/@arcadiasol/sdk@latest/dist/umd/arcadia-game-sdk.js"></script>
</head>
<body>
  <div id="status">Initializing...</div>
  <div id="wallet"></div>

  <script>
    async function init() {
      try {
        // Initialize SDK
        const arcadia = new ArcadiaGameSDK({
          gameId: 'your-game-id',
        });

        await arcadia.init();

        // Get wallet address
        const walletAddress = await arcadia.getWalletAddress();

        if (walletAddress) {
          document.getElementById('status').textContent = 'Ready!';
          document.getElementById('wallet').textContent = `Wallet: ${walletAddress}`;
        } else {
          document.getElementById('status').textContent = 'Please connect your wallet';
        }
      } catch (error) {
        document.getElementById('status').textContent = 'Error: ' + error.message;
      }
    }

    window.addEventListener('DOMContentLoaded', init);
  </script>
</body>
</html>

Wallet Integration

Complete wallet integration with change listeners.

import { ArcadiaSDK, WalletNotConnectedError } from '@arcadiasol/sdk';

class WalletManager {
  private arcadia: ArcadiaSDK;
  private walletAddress: string | null = null;
  private onConnectCallbacks: Array<(address: string) => void> = [];
  private onDisconnectCallbacks: Array<() => void> = [];

  constructor(gameId: string) {
    this.arcadia = new ArcadiaSDK({ gameId });
  }

  async initialize() {
    await this.arcadia.init();

    // Get initial wallet address
    this.walletAddress = await this.arcadia.getWalletAddress();

    // Listen for wallet changes
    this.arcadia.onWalletChange((connected, address) => {
      if (connected && address) {
        this.handleConnect(address);
      } else {
        this.handleDisconnect();
      }
    });

    return this.walletAddress;
  }

  private handleConnect(address: string) {
    const wasConnected = this.walletAddress !== null;
    this.walletAddress = address;

    if (!wasConnected) {
      // First connection
      this.onConnectCallbacks.forEach(cb => cb(address));
    } else if (this.walletAddress !== address) {
      // Wallet changed
      this.onDisconnectCallbacks.forEach(cb => cb());
      this.onConnectCallbacks.forEach(cb => cb(address));
    }
  }

  private handleDisconnect() {
    if (this.walletAddress) {
      this.walletAddress = null;
      this.onDisconnectCallbacks.forEach(cb => cb());
    }
  }

  onConnect(callback: (address: string) => void) {
    this.onConnectCallbacks.push(callback);
  }

  onDisconnect(callback: () => void) {
    this.onDisconnectCallbacks.push(callback);
  }

  getAddress(): string | null {
    return this.walletAddress;
  }
}

// Usage
const walletManager = new WalletManager('your-game-id');
await walletManager.initialize();

walletManager.onConnect((address) => {
  console.log('Wallet connected:', address);
  loadPlayerData(address);
});

walletManager.onDisconnect(() => {
  console.log('Wallet disconnected');
  saveGameState();
  pauseGame();
});

Pay-to-Play

Complete pay-to-play implementation with verification.

import { ArcadiaSDK, PaymentFailedError, WalletNotConnectedError } from '@arcadiasol/sdk';

class PayToPlayManager {
  private arcadia: ArcadiaSDK;
  private walletAddress: string | null = null;
  private hasPaid: boolean = false;

  constructor(gameId: string) {
    this.arcadia = new ArcadiaSDK({ gameId });
  }

  async initialize() {
    await this.arcadia.init();
    this.walletAddress = await this.arcadia.getWalletAddress();

    if (!this.walletAddress) {
      throw new WalletNotConnectedError();
    }

    // Check if already paid
    this.hasPaid = await this.checkPaymentStatus(this.walletAddress);
  }

  async checkPaymentRequired(): Promise<boolean> {
    return !this.hasPaid;
  }

  async processPayment(amount: number, token: 'SOL' | 'USDC'): Promise<boolean> {
    if (!this.walletAddress) {
      throw new WalletNotConnectedError();
    }

    try {
      showLoading('Processing payment...');

      const result = await this.arcadia.payment.payToPlay(amount, token);

      // Verify payment
      if (!result.success || result.amount !== amount) {
        throw new PaymentFailedError('Payment verification failed');
      }

      // Mark as paid
      await this.markAsPaid(this.walletAddress, result);
      this.hasPaid = true;

      // Log payment
      await this.logPayment(result);

      return true;
    } catch (error) {
      if (error instanceof PaymentFailedError) {
        showError('Payment failed: ' + error.message);
      } else if (error instanceof WalletNotConnectedError) {
        showError('Please connect your wallet');
      } else {
        showError('An error occurred');
      }
      return false;
    } finally {
      hideLoading();
    }
  }

  private async checkPaymentStatus(walletAddress: string): Promise<boolean> {
    const response = await fetch(`/api/payment-status?wallet=${walletAddress}`);
    const data = await response.json();
    return data.hasPaid || false;
  }

  private async markAsPaid(walletAddress: string, result: PaymentResult) {
    await fetch('/api/mark-paid', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        walletAddress,
        txSignature: result.txSignature,
        amount: result.amount,
        token: result.token,
        timestamp: result.timestamp,
      }),
    });
  }

  private async logPayment(result: PaymentResult) {
    await fetch('/api/analytics/payment', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(result),
    });
  }
}

// Usage
const paymentManager = new PayToPlayManager('your-game-id');
await paymentManager.initialize();

if (await paymentManager.checkPaymentRequired()) {
  const paid = await paymentManager.processPayment(0.5, 'SOL');
  if (paid) {
    startGame();
  }
} else {
  startGame();
}

In-Game Purchases

Complete item shop implementation.

import { ArcadiaSDK, PaymentFailedError } from '@arcadiasol/sdk';

interface ShopItem {
  id: string;
  name: string;
  price: number;
  token: 'SOL' | 'USDC';
  description: string;
}

class ItemShop {
  private arcadia: ArcadiaSDK;
  private walletAddress: string | null = null;
  private inventory: string[] = [];

  constructor(gameId: string) {
    this.arcadia = new ArcadiaSDK({ gameId });
  }

  async initialize() {
    await this.arcadia.init();
    this.walletAddress = await this.arcadia.getWalletAddress();
    this.inventory = await this.loadInventory(this.walletAddress!);
  }

  async purchaseItem(item: ShopItem): Promise<boolean> {
    if (!this.walletAddress) {
      showError('Please connect your wallet');
      return false;
    }

    try {
      showLoading(`Purchasing ${item.name}...`);

      const result = await this.arcadia.payment.purchaseItem(
        item.id,
        item.price,
        item.token
      );

      // Verify purchase
      if (!result.success || 
          result.amount !== item.price || 
          result.token !== item.token) {
        throw new PaymentFailedError('Purchase verification failed');
      }

      // Add to inventory
      this.inventory.push(item.id);
      await this.saveInventory(this.walletAddress, this.inventory);

      // Log purchase
      await this.logPurchase(item, result);

      showSuccess(`${item.name} purchased!`);
      return true;
    } catch (error) {
      if (error instanceof PaymentFailedError) {
        showError('Purchase failed: ' + error.message);
      } else {
        showError('An error occurred');
      }
      return false;
    } finally {
      hideLoading();
    }
  }

  hasItem(itemId: string): boolean {
    return this.inventory.includes(itemId);
  }

  private async loadInventory(walletAddress: string): Promise<string[]> {
    const response = await fetch(`/api/inventory?wallet=${walletAddress}`);
    const data = await response.json();
    return data.inventory || [];
  }

  private async saveInventory(walletAddress: string, inventory: string[]) {
    await fetch('/api/inventory', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ walletAddress, inventory }),
    });
  }

  private async logPurchase(item: ShopItem, result: PaymentResult) {
    await fetch('/api/analytics/purchase', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        itemId: item.id,
        itemName: item.name,
        ...result,
      }),
    });
  }
}

// Usage
const shop = new ItemShop('your-game-id');
await shop.initialize();

const item: ShopItem = {
  id: 'sword-001',
  name: 'Legendary Sword',
  price: 1.0,
  token: 'SOL',
  description: 'A powerful sword',
};

const purchased = await shop.purchaseItem(item);
if (purchased) {
  console.log('Item added to inventory!');
}

Complete Game Example

Full game integration with wallet, payments, and save data.

import { ArcadiaSDK, WalletNotConnectedError, PaymentFailedError } from '@arcadiasol/sdk';

class Game {
  private arcadia: ArcadiaSDK;
  private walletAddress: string | null = null;
  private playerData: any = null;
  private shop: ItemShop;

  constructor(gameId: string) {
    this.arcadia = new ArcadiaSDK({ gameId });
    this.shop = new ItemShop(gameId);
  }

  async initialize() {
    // Initialize SDK
    await this.arcadia.init();

    // Get wallet address
    this.walletAddress = await this.arcadia.getWalletAddress();
    if (!this.walletAddress) {
      throw new WalletNotConnectedError();
    }

    // Load or create player data
    this.playerData = await this.loadOrCreatePlayerData(this.walletAddress);

    // Initialize shop
    await this.shop.initialize();

    // Set up wallet change listener
    this.arcadia.onWalletChange((connected, address) => {
      this.handleWalletChange(connected, address);
    });

    // Check payment requirement
    if (this.gameRequiresPayment() && !this.playerData.hasPaid) {
      await this.handlePayToPlay();
    }

    // Start game
    this.start();
  }

  private async handlePayToPlay() {
    const amount = 0.5;
    const token = 'SOL';

    try {
      const result = await this.arcadia.payment.payToPlay(amount, token);
      
      if (result.success && result.amount === amount) {
        this.playerData.hasPaid = true;
        await this.savePlayerData(this.walletAddress!, this.playerData);
        showSuccess('Payment successful!');
      }
    } catch (error) {
      if (error instanceof PaymentFailedError) {
        showError('Payment failed: ' + error.message);
      }
      throw error;
    }
  }

  private handleWalletChange(connected: boolean, address: string | null) {
    if (!connected) {
      this.saveGameState();
      this.pause();
      showMessage('Wallet disconnected. Please reconnect.');
    } else if (address && address !== this.walletAddress) {
      // Different wallet
      this.saveGameState();
      this.walletAddress = address;
      this.loadPlayerData(address);
    }
  }

  private async loadOrCreatePlayerData(walletAddress: string) {
    const existing = await this.loadPlayerData(walletAddress);
    if (existing) {
      return existing;
    }

    const newData = {
      walletAddress,
      level: 1,
      score: 0,
      inventory: [],
      hasPaid: false,
    };

    await this.savePlayerData(walletAddress, newData);
    return newData;
  }

  private async loadPlayerData(walletAddress: string) {
    const response = await fetch(`/api/player-data?wallet=${walletAddress}`);
    if (response.ok) {
      return response.json();
    }
    return null;
  }

  private async savePlayerData(walletAddress: string, data: any) {
    await fetch('/api/player-data', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ walletAddress, data }),
    });
  }

  private saveGameState() {
    if (this.walletAddress && this.playerData) {
      this.savePlayerData(this.walletAddress, this.playerData);
    }
  }

  private gameRequiresPayment(): boolean {
    return true; // Your logic
  }

  private start() {
    console.log('Game started!');
  }

  private pause() {
    console.log('Game paused');
  }
}

// Initialize game
const game = new Game('your-game-id');
game.initialize().catch(error => {
  console.error('Game initialization failed:', error);
});

TypeScript Example

Type-safe implementation with full TypeScript support.

import {
  ArcadiaSDK,
  SDKConfig,
  PaymentResult,
  WalletNotConnectedError,
  PaymentFailedError,
} from '@arcadiasol/sdk';

interface PlayerData {
  walletAddress: string;
  level: number;
  score: number;
  inventory: string[];
  hasPaid: boolean;
}

class TypedGameManager {
  private arcadia: ArcadiaSDK;
  private walletAddress: string | null = null;
  private playerData: PlayerData | null = null;

  constructor(config: SDKConfig) {
    this.arcadia = new ArcadiaSDK(config);
  }

  async initialize(): Promise<void> {
    await this.arcadia.init();
    this.walletAddress = await this.arcadia.getWalletAddress();
    
    if (!this.walletAddress) {
      throw new WalletNotConnectedError();
    }

    this.playerData = await this.loadPlayerData(this.walletAddress);
  }

  async processPayment(amount: number, token: 'SOL' | 'USDC'): Promise<PaymentResult> {
    if (!this.walletAddress) {
      throw new WalletNotConnectedError();
    }

    try {
      const result: PaymentResult = await this.arcadia.payment.payToPlay(amount, token);
      
      if (!result.success || result.amount !== amount) {
        throw new PaymentFailedError('Payment verification failed');
      }

      return result;
    } catch (error) {
      if (error instanceof PaymentFailedError) {
        throw error;
      }
      throw new PaymentFailedError('Payment failed');
    }
  }

  private async loadPlayerData(walletAddress: string): Promise<PlayerData> {
    // Implementation
    return {
      walletAddress,
      level: 1,
      score: 0,
      inventory: [],
      hasPaid: false,
    };
  }
}

Error Handling

Complete error handling example.

import {
  ArcadiaSDK,
  WalletNotConnectedError,
  PaymentFailedError,
  TimeoutError,
  InvalidAmountError,
  InvalidTokenError,
} from '@arcadiasol/sdk';

class ErrorHandlingExample {
  private arcadia: ArcadiaSDK;

  constructor(gameId: string) {
    this.arcadia = new ArcadiaSDK({ gameId });
  }

  async safeGetWalletAddress(): Promise<string | null> {
    try {
      return await this.arcadia.getWalletAddress();
    } catch (error) {
      if (error instanceof TimeoutError) {
        console.warn('Request timed out, retrying...');
        // Retry logic
        return await this.arcadia.getWalletAddress();
      }
      console.error('Failed to get wallet address:', error);
      return null;
    }
  }

  async safePayment(amount: number, token: 'SOL' | 'USDC'): Promise<PaymentResult | null> {
    try {
      return await this.arcadia.payment.payToPlay(amount, token);
    } catch (error) {
      if (error instanceof WalletNotConnectedError) {
        showError('Please connect your wallet');
      } else if (error instanceof PaymentFailedError) {
        showError('Payment failed: ' + error.message);
      } else if (error instanceof InvalidAmountError) {
        showError('Invalid payment amount');
      } else if (error instanceof InvalidTokenError) {
        showError('Invalid token type');
      } else if (error instanceof TimeoutError) {
        showError('Request timed out. Please try again.');
      } else {
        showError('An unexpected error occurred');
        console.error('Unknown error:', error);
      }
      return null;
    }
  }
}

Next Steps

See Getting Started for basic setup
Review API Reference for complete documentation
Check Error Handling for error handling patterns

examples

Examples

Complete, working examples for common use cases with the Arcadia Game SDK.

Basic Integration
Wallet Integration
Pay-to-Play
In-Game Purchases
Complete Game Example
TypeScript Example
Error Handling

Basic Integration

Minimal example showing SDK initialization and wallet address retrieval.

<!DOCTYPE html>
<html>
<head>
  <title>Basic SDK Integration</title>
  <script src="https://cdn.jsdelivr.net/npm/@arcadiasol/sdk@latest/dist/umd/arcadia-game-sdk.js"></script>
</head>
<body>
  <div id="status">Initializing...</div>
  <div id="wallet"></div>

  <script>
    async function init() {
      try {
        // Initialize SDK
        const arcadia = new ArcadiaGameSDK({
          gameId: 'your-game-id',
        });

        await arcadia.init();

        // Get wallet address
        const walletAddress = await arcadia.getWalletAddress();

        if (walletAddress) {
          document.getElementById('status').textContent = 'Ready!';
          document.getElementById('wallet').textContent = `Wallet: ${walletAddress}`;
        } else {
          document.getElementById('status').textContent = 'Please connect your wallet';
        }
      } catch (error) {
        document.getElementById('status').textContent = 'Error: ' + error.message;
      }
    }

    window.addEventListener('DOMContentLoaded', init);
  </script>
</body>
</html>

Wallet Integration

Complete wallet integration with change listeners.

import { ArcadiaSDK, WalletNotConnectedError } from '@arcadiasol/sdk';

class WalletManager {
  private arcadia: ArcadiaSDK;
  private walletAddress: string | null = null;
  private onConnectCallbacks: Array<(address: string) => void> = [];
  private onDisconnectCallbacks: Array<() => void> = [];

  constructor(gameId: string) {
    this.arcadia = new ArcadiaSDK({ gameId });
  }

  async initialize() {
    await this.arcadia.init();

    // Get initial wallet address
    this.walletAddress = await this.arcadia.getWalletAddress();

    // Listen for wallet changes
    this.arcadia.onWalletChange((connected, address) => {
      if (connected && address) {
        this.handleConnect(address);
      } else {
        this.handleDisconnect();
      }
    });

    return this.walletAddress;
  }

  private handleConnect(address: string) {
    const wasConnected = this.walletAddress !== null;
    this.walletAddress = address;

    if (!wasConnected) {
      // First connection
      this.onConnectCallbacks.forEach(cb => cb(address));
    } else if (this.walletAddress !== address) {
      // Wallet changed
      this.onDisconnectCallbacks.forEach(cb => cb());
      this.onConnectCallbacks.forEach(cb => cb(address));
    }
  }

  private handleDisconnect() {
    if (this.walletAddress) {
      this.walletAddress = null;
      this.onDisconnectCallbacks.forEach(cb => cb());
    }
  }

  onConnect(callback: (address: string) => void) {
    this.onConnectCallbacks.push(callback);
  }

  onDisconnect(callback: () => void) {
    this.onDisconnectCallbacks.push(callback);
  }

  getAddress(): string | null {
    return this.walletAddress;
  }
}

// Usage
const walletManager = new WalletManager('your-game-id');
await walletManager.initialize();

walletManager.onConnect((address) => {
  console.log('Wallet connected:', address);
  loadPlayerData(address);
});

walletManager.onDisconnect(() => {
  console.log('Wallet disconnected');
  saveGameState();
  pauseGame();
});

Pay-to-Play

Complete pay-to-play implementation with verification.

import { ArcadiaSDK, PaymentFailedError, WalletNotConnectedError } from '@arcadiasol/sdk';

class PayToPlayManager {
  private arcadia: ArcadiaSDK;
  private walletAddress: string | null = null;
  private hasPaid: boolean = false;

  constructor(gameId: string) {
    this.arcadia = new ArcadiaSDK({ gameId });
  }

  async initialize() {
    await this.arcadia.init();
    this.walletAddress = await this.arcadia.getWalletAddress();

    if (!this.walletAddress) {
      throw new WalletNotConnectedError();
    }

    // Check if already paid
    this.hasPaid = await this.checkPaymentStatus(this.walletAddress);
  }

  async checkPaymentRequired(): Promise<boolean> {
    return !this.hasPaid;
  }

  async processPayment(amount: number, token: 'SOL' | 'USDC'): Promise<boolean> {
    if (!this.walletAddress) {
      throw new WalletNotConnectedError();
    }

    try {
      showLoading('Processing payment...');

      const result = await this.arcadia.payment.payToPlay(amount, token);

      // Verify payment
      if (!result.success || result.amount !== amount) {
        throw new PaymentFailedError('Payment verification failed');
      }

      // Mark as paid
      await this.markAsPaid(this.walletAddress, result);
      this.hasPaid = true;

      // Log payment
      await this.logPayment(result);

      return true;
    } catch (error) {
      if (error instanceof PaymentFailedError) {
        showError('Payment failed: ' + error.message);
      } else if (error instanceof WalletNotConnectedError) {
        showError('Please connect your wallet');
      } else {
        showError('An error occurred');
      }
      return false;
    } finally {
      hideLoading();
    }
  }

  private async checkPaymentStatus(walletAddress: string): Promise<boolean> {
    const response = await fetch(`/api/payment-status?wallet=${walletAddress}`);
    const data = await response.json();
    return data.hasPaid || false;
  }

  private async markAsPaid(walletAddress: string, result: PaymentResult) {
    await fetch('/api/mark-paid', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        walletAddress,
        txSignature: result.txSignature,
        amount: result.amount,
        token: result.token,
        timestamp: result.timestamp,
      }),
    });
  }

  private async logPayment(result: PaymentResult) {
    await fetch('/api/analytics/payment', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(result),
    });
  }
}

// Usage
const paymentManager = new PayToPlayManager('your-game-id');
await paymentManager.initialize();

if (await paymentManager.checkPaymentRequired()) {
  const paid = await paymentManager.processPayment(0.5, 'SOL');
  if (paid) {
    startGame();
  }
} else {
  startGame();
}

In-Game Purchases

Complete item shop implementation.

import { ArcadiaSDK, PaymentFailedError } from '@arcadiasol/sdk';

interface ShopItem {
  id: string;
  name: string;
  price: number;
  token: 'SOL' | 'USDC';
  description: string;
}

class ItemShop {
  private arcadia: ArcadiaSDK;
  private walletAddress: string | null = null;
  private inventory: string[] = [];

  constructor(gameId: string) {
    this.arcadia = new ArcadiaSDK({ gameId });
  }

  async initialize() {
    await this.arcadia.init();
    this.walletAddress = await this.arcadia.getWalletAddress();
    this.inventory = await this.loadInventory(this.walletAddress!);
  }

  async purchaseItem(item: ShopItem): Promise<boolean> {
    if (!this.walletAddress) {
      showError('Please connect your wallet');
      return false;
    }

    try {
      showLoading(`Purchasing ${item.name}...`);

      const result = await this.arcadia.payment.purchaseItem(
        item.id,
        item.price,
        item.token
      );

      // Verify purchase
      if (!result.success || 
          result.amount !== item.price || 
          result.token !== item.token) {
        throw new PaymentFailedError('Purchase verification failed');
      }

      // Add to inventory
      this.inventory.push(item.id);
      await this.saveInventory(this.walletAddress, this.inventory);

      // Log purchase
      await this.logPurchase(item, result);

      showSuccess(`${item.name} purchased!`);
      return true;
    } catch (error) {
      if (error instanceof PaymentFailedError) {
        showError('Purchase failed: ' + error.message);
      } else {
        showError('An error occurred');
      }
      return false;
    } finally {
      hideLoading();
    }
  }

  hasItem(itemId: string): boolean {
    return this.inventory.includes(itemId);
  }

  private async loadInventory(walletAddress: string): Promise<string[]> {
    const response = await fetch(`/api/inventory?wallet=${walletAddress}`);
    const data = await response.json();
    return data.inventory || [];
  }

  private async saveInventory(walletAddress: string, inventory: string[]) {
    await fetch('/api/inventory', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ walletAddress, inventory }),
    });
  }

  private async logPurchase(item: ShopItem, result: PaymentResult) {
    await fetch('/api/analytics/purchase', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        itemId: item.id,
        itemName: item.name,
        ...result,
      }),
    });
  }
}

// Usage
const shop = new ItemShop('your-game-id');
await shop.initialize();

const item: ShopItem = {
  id: 'sword-001',
  name: 'Legendary Sword',
  price: 1.0,
  token: 'SOL',
  description: 'A powerful sword',
};

const purchased = await shop.purchaseItem(item);
if (purchased) {
  console.log('Item added to inventory!');
}

Complete Game Example

Full game integration with wallet, payments, and save data.

import { ArcadiaSDK, WalletNotConnectedError, PaymentFailedError } from '@arcadiasol/sdk';

class Game {
  private arcadia: ArcadiaSDK;
  private walletAddress: string | null = null;
  private playerData: any = null;
  private shop: ItemShop;

  constructor(gameId: string) {
    this.arcadia = new ArcadiaSDK({ gameId });
    this.shop = new ItemShop(gameId);
  }

  async initialize() {
    // Initialize SDK
    await this.arcadia.init();

    // Get wallet address
    this.walletAddress = await this.arcadia.getWalletAddress();
    if (!this.walletAddress) {
      throw new WalletNotConnectedError();
    }

    // Load or create player data
    this.playerData = await this.loadOrCreatePlayerData(this.walletAddress);

    // Initialize shop
    await this.shop.initialize();

    // Set up wallet change listener
    this.arcadia.onWalletChange((connected, address) => {
      this.handleWalletChange(connected, address);
    });

    // Check payment requirement
    if (this.gameRequiresPayment() && !this.playerData.hasPaid) {
      await this.handlePayToPlay();
    }

    // Start game
    this.start();
  }

  private async handlePayToPlay() {
    const amount = 0.5;
    const token = 'SOL';

    try {
      const result = await this.arcadia.payment.payToPlay(amount, token);
      
      if (result.success && result.amount === amount) {
        this.playerData.hasPaid = true;
        await this.savePlayerData(this.walletAddress!, this.playerData);
        showSuccess('Payment successful!');
      }
    } catch (error) {
      if (error instanceof PaymentFailedError) {
        showError('Payment failed: ' + error.message);
      }
      throw error;
    }
  }

  private handleWalletChange(connected: boolean, address: string | null) {
    if (!connected) {
      this.saveGameState();
      this.pause();
      showMessage('Wallet disconnected. Please reconnect.');
    } else if (address && address !== this.walletAddress) {
      // Different wallet
      this.saveGameState();
      this.walletAddress = address;
      this.loadPlayerData(address);
    }
  }

  private async loadOrCreatePlayerData(walletAddress: string) {
    const existing = await this.loadPlayerData(walletAddress);
    if (existing) {
      return existing;
    }

    const newData = {
      walletAddress,
      level: 1,
      score: 0,
      inventory: [],
      hasPaid: false,
    };

    await this.savePlayerData(walletAddress, newData);
    return newData;
  }

  private async loadPlayerData(walletAddress: string) {
    const response = await fetch(`/api/player-data?wallet=${walletAddress}`);
    if (response.ok) {
      return response.json();
    }
    return null;
  }

  private async savePlayerData(walletAddress: string, data: any) {
    await fetch('/api/player-data', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ walletAddress, data }),
    });
  }

  private saveGameState() {
    if (this.walletAddress && this.playerData) {
      this.savePlayerData(this.walletAddress, this.playerData);
    }
  }

  private gameRequiresPayment(): boolean {
    return true; // Your logic
  }

  private start() {
    console.log('Game started!');
  }

  private pause() {
    console.log('Game paused');
  }
}

// Initialize game
const game = new Game('your-game-id');
game.initialize().catch(error => {
  console.error('Game initialization failed:', error);
});

TypeScript Example

Type-safe implementation with full TypeScript support.

import {
  ArcadiaSDK,
  SDKConfig,
  PaymentResult,
  WalletNotConnectedError,
  PaymentFailedError,
} from '@arcadiasol/sdk';

interface PlayerData {
  walletAddress: string;
  level: number;
  score: number;
  inventory: string[];
  hasPaid: boolean;
}

class TypedGameManager {
  private arcadia: ArcadiaSDK;
  private walletAddress: string | null = null;
  private playerData: PlayerData | null = null;

  constructor(config: SDKConfig) {
    this.arcadia = new ArcadiaSDK(config);
  }

  async initialize(): Promise<void> {
    await this.arcadia.init();
    this.walletAddress = await this.arcadia.getWalletAddress();
    
    if (!this.walletAddress) {
      throw new WalletNotConnectedError();
    }

    this.playerData = await this.loadPlayerData(this.walletAddress);
  }

  async processPayment(amount: number, token: 'SOL' | 'USDC'): Promise<PaymentResult> {
    if (!this.walletAddress) {
      throw new WalletNotConnectedError();
    }

    try {
      const result: PaymentResult = await this.arcadia.payment.payToPlay(amount, token);
      
      if (!result.success || result.amount !== amount) {
        throw new PaymentFailedError('Payment verification failed');
      }

      return result;
    } catch (error) {
      if (error instanceof PaymentFailedError) {
        throw error;
      }
      throw new PaymentFailedError('Payment failed');
    }
  }

  private async loadPlayerData(walletAddress: string): Promise<PlayerData> {
    // Implementation
    return {
      walletAddress,
      level: 1,
      score: 0,
      inventory: [],
      hasPaid: false,
    };
  }
}

Error Handling

Complete error handling example.

import {
  ArcadiaSDK,
  WalletNotConnectedError,
  PaymentFailedError,
  TimeoutError,
  InvalidAmountError,
  InvalidTokenError,
} from '@arcadiasol/sdk';

class ErrorHandlingExample {
  private arcadia: ArcadiaSDK;

  constructor(gameId: string) {
    this.arcadia = new ArcadiaSDK({ gameId });
  }

  async safeGetWalletAddress(): Promise<string | null> {
    try {
      return await this.arcadia.getWalletAddress();
    } catch (error) {
      if (error instanceof TimeoutError) {
        console.warn('Request timed out, retrying...');
        // Retry logic
        return await this.arcadia.getWalletAddress();
      }
      console.error('Failed to get wallet address:', error);
      return null;
    }
  }

  async safePayment(amount: number, token: 'SOL' | 'USDC'): Promise<PaymentResult | null> {
    try {
      return await this.arcadia.payment.payToPlay(amount, token);
    } catch (error) {
      if (error instanceof WalletNotConnectedError) {
        showError('Please connect your wallet');
      } else if (error instanceof PaymentFailedError) {
        showError('Payment failed: ' + error.message);
      } else if (error instanceof InvalidAmountError) {
        showError('Invalid payment amount');
      } else if (error instanceof InvalidTokenError) {
        showError('Invalid token type');
      } else if (error instanceof TimeoutError) {
        showError('Request timed out. Please try again.');
      } else {
        showError('An unexpected error occurred');
        console.error('Unknown error:', error);
      }
      return null;
    }
  }
}

Next Steps

See Getting Started for basic setup
Review API Reference for complete documentation
Check Error Handling for error handling patterns

examples

Examples

Table of Contents

Basic Integration

Wallet Integration

Pay-to-Play

In-Game Purchases

Complete Game Example

TypeScript Example

Error Handling

Next Steps

examples

Examples

Table of Contents

Basic Integration

Wallet Integration

Pay-to-Play

In-Game Purchases

Complete Game Example

TypeScript Example

Error Handling

Next Steps