Connect wallet to view library

quick start

Quick Start - Step by Step Integration

Get your game integrated with Arcadia in 5 simple steps. Each step includes only the minimal code needed.

Prerequisites

Your game hosted and accessible via URL
Your game ID from Arcadia (you'll get this when you register your game)
Basic HTML/JavaScript knowledge

Step 1: Include the SDK

Add the SDK to your HTML file using CDN:

<script src="https://cdn.jsdelivr.net/npm/@arcadiasol/sdk@latest/dist/umd/arcadia-game-sdk.js"></script>

Or use NPM:

npm install @arcadiasol/sdk

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

Step 2: Initialize the SDK

Create and initialize the SDK instance:

// Get SDK class (for CDN usage)
const SDKClass = window.ArcadiaGameSDK?.default || 
                window.ArcadiaGameSDK?.ArcadiaSDK || 
                window.ArcadiaGameSDK;

// Create instance
const arcadia = new SDKClass({
  gameId: 'your-game-id', // Replace with your game ID
});

// Initialize
await arcadia.init();

NPM usage:

const arcadia = new ArcadiaSDK({
  gameId: 'your-game-id',
});

await arcadia.init();

Step 3: Get Wallet Address

Retrieve the player's wallet address (your primary user identifier):

const walletAddress = await arcadia.getWalletAddress();

if (!walletAddress) {
  // Player hasn't connected wallet in Arcadia
  console.log('Please connect wallet');
  return;
}

// Use wallet address as user ID
console.log('Player:', walletAddress);

Step 4: Load Player Data (Optional)

Use the wallet address to load or create player save data:

async function loadPlayerData(walletAddress) {
  // Load from your backend API
  const response = await fetch(`https://your-api.com/player/${walletAddress}`);
  const data = await response.json();
  return data;
}

// Or create new player data
function createNewPlayer(walletAddress) {
  return {
    walletAddress,
    level: 1,
    score: 0,
    inventory: [],
  };
}

Step 5: Handle Payments (Optional)

Pay-to-Play

try {
  const result = await arcadia.payment.payToPlay(0.1, 'SOL');
  
  if (result.success) {
    console.log('Payment successful!', result.txSignature);
    // Start your game
    startGame();
  }
} catch (error) {
  console.error('Payment failed:', error.message);
}

In-Game Purchase

try {
  const result = await arcadia.payment.purchaseItem('item-id', 0.05, 'SOL');
  
  if (result.success) {
    console.log('Purchase successful!', result.txSignature);
    // Add item to inventory
    addItemToInventory('item-id');
  }
} catch (error) {
  console.error('Purchase failed:', error.message);
}

Complete Minimal Example

Here's everything combined in the smallest possible working example:

<!DOCTYPE html>
<html>
<head>
  <title>My Game</title>
  <script src="https://cdn.jsdelivr.net/npm/@arcadiasol/sdk@latest/dist/umd/arcadia-game-sdk.js"></script>
</head>
<body>
  <div id="status">Loading...</div>
  
  <script>
    (async function() {
      try {
        // Step 1 & 2: Initialize SDK
        const SDKClass = window.ArcadiaGameSDK?.default || window.ArcadiaGameSDK;
        const arcadia = new SDKClass({ gameId: 'your-game-id' });
        await arcadia.init();
        
        // Step 3: Get wallet
        const walletAddress = await arcadia.getWalletAddress();
        if (!walletAddress) {
          document.getElementById('status').textContent = 'Connect wallet in Arcadia';
          return;
        }
        
        // Step 4: Load data (your implementation)
        console.log('Player:', walletAddress);
        
        // Step 5: Payment (if needed)
        // const result = await arcadia.payment.payToPlay(0.1, 'SOL');
        
        document.getElementById('status').textContent = 'Ready!';
      } catch (error) {
        console.error('Error:', error);
      }
    })();
  </script>
</body>
</html>

What Each Step Does

Step 1: Include SDK

Loads the Arcadia Game SDK library into your page.

Step 2: Initialize SDK

Sets up communication between your game and Arcadia's platform. Must be called before using any SDK features.

Step 3: Get Wallet Address

Retrieves the player's Solana wallet address. This is your universal user identifier - use it to:

Link save data
Track player progress
Identify returning players

Step 4: Load Player Data

Use the wallet address to fetch or create player data from your backend. This is where you implement your save system.

Step 5: Handle Payments

Process pay-to-play or in-game purchases. The SDK handles all blockchain complexity - you just call the method and get a result.

Next Steps

Once you have the basics working:

Add wallet change listener - Handle wallet disconnection:

arcadia.onWalletChange((connected, address) => {
  if (connected) {
    console.log('Wallet connected:', address);
  } else {
    console.log('Wallet disconnected');
  }
});

Implement your save system - Connect Step 4 to your backend API
Add payment UI - Create buttons/UI for pay-to-play and purchases
Handle errors - Add user-friendly error messages
Test thoroughly - Test wallet connection, payments, and data loading

Common Issues

SDK Not Loading

Check internet connection
Verify CDN URL is correct
Check browser console for errors

Wallet Returns Null

Game must be running inside Arcadia's iframe
Player must connect wallet in Arcadia first
Ensure init() completed successfully

Payment Fails

Verify wallet has sufficient balance
Check game ID is correct
Ensure game is in Arcadia's iframe
Check console for detailed error

Need More Details?

Installation options: See Installation Guide
Wallet features: See Wallet Integration
Payment details: See Payments Guide
Complete examples: See Examples
API reference: See API Reference

quick start

Quick Start - Step by Step Integration

Get your game integrated with Arcadia in 5 simple steps. Each step includes only the minimal code needed.

Prerequisites

Your game hosted and accessible via URL
Your game ID from Arcadia (you'll get this when you register your game)
Basic HTML/JavaScript knowledge

Step 1: Include the SDK

Add the SDK to your HTML file using CDN:

<script src="https://cdn.jsdelivr.net/npm/@arcadiasol/sdk@latest/dist/umd/arcadia-game-sdk.js"></script>

Or use NPM:

npm install @arcadiasol/sdk

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

Step 2: Initialize the SDK

Create and initialize the SDK instance:

// Get SDK class (for CDN usage)
const SDKClass = window.ArcadiaGameSDK?.default || 
                window.ArcadiaGameSDK?.ArcadiaSDK || 
                window.ArcadiaGameSDK;

// Create instance
const arcadia = new SDKClass({
  gameId: 'your-game-id', // Replace with your game ID
});

// Initialize
await arcadia.init();

NPM usage:

const arcadia = new ArcadiaSDK({
  gameId: 'your-game-id',
});

await arcadia.init();

Step 3: Get Wallet Address

Retrieve the player's wallet address (your primary user identifier):

const walletAddress = await arcadia.getWalletAddress();

if (!walletAddress) {
  // Player hasn't connected wallet in Arcadia
  console.log('Please connect wallet');
  return;
}

// Use wallet address as user ID
console.log('Player:', walletAddress);

Step 4: Load Player Data (Optional)

Use the wallet address to load or create player save data:

async function loadPlayerData(walletAddress) {
  // Load from your backend API
  const response = await fetch(`https://your-api.com/player/${walletAddress}`);
  const data = await response.json();
  return data;
}

// Or create new player data
function createNewPlayer(walletAddress) {
  return {
    walletAddress,
    level: 1,
    score: 0,
    inventory: [],
  };
}

Step 5: Handle Payments (Optional)

Pay-to-Play

try {
  const result = await arcadia.payment.payToPlay(0.1, 'SOL');
  
  if (result.success) {
    console.log('Payment successful!', result.txSignature);
    // Start your game
    startGame();
  }
} catch (error) {
  console.error('Payment failed:', error.message);
}

In-Game Purchase

try {
  const result = await arcadia.payment.purchaseItem('item-id', 0.05, 'SOL');
  
  if (result.success) {
    console.log('Purchase successful!', result.txSignature);
    // Add item to inventory
    addItemToInventory('item-id');
  }
} catch (error) {
  console.error('Purchase failed:', error.message);
}

Complete Minimal Example

Here's everything combined in the smallest possible working example:

<!DOCTYPE html>
<html>
<head>
  <title>My Game</title>
  <script src="https://cdn.jsdelivr.net/npm/@arcadiasol/sdk@latest/dist/umd/arcadia-game-sdk.js"></script>
</head>
<body>
  <div id="status">Loading...</div>
  
  <script>
    (async function() {
      try {
        // Step 1 & 2: Initialize SDK
        const SDKClass = window.ArcadiaGameSDK?.default || window.ArcadiaGameSDK;
        const arcadia = new SDKClass({ gameId: 'your-game-id' });
        await arcadia.init();
        
        // Step 3: Get wallet
        const walletAddress = await arcadia.getWalletAddress();
        if (!walletAddress) {
          document.getElementById('status').textContent = 'Connect wallet in Arcadia';
          return;
        }
        
        // Step 4: Load data (your implementation)
        console.log('Player:', walletAddress);
        
        // Step 5: Payment (if needed)
        // const result = await arcadia.payment.payToPlay(0.1, 'SOL');
        
        document.getElementById('status').textContent = 'Ready!';
      } catch (error) {
        console.error('Error:', error);
      }
    })();
  </script>
</body>
</html>

What Each Step Does

Step 1: Include SDK

Loads the Arcadia Game SDK library into your page.

Step 2: Initialize SDK

Sets up communication between your game and Arcadia's platform. Must be called before using any SDK features.

Step 3: Get Wallet Address

Retrieves the player's Solana wallet address. This is your universal user identifier - use it to:

Link save data
Track player progress
Identify returning players

Step 4: Load Player Data

Use the wallet address to fetch or create player data from your backend. This is where you implement your save system.

Step 5: Handle Payments

Process pay-to-play or in-game purchases. The SDK handles all blockchain complexity - you just call the method and get a result.

Next Steps

Once you have the basics working:

Add wallet change listener - Handle wallet disconnection:

arcadia.onWalletChange((connected, address) => {
  if (connected) {
    console.log('Wallet connected:', address);
  } else {
    console.log('Wallet disconnected');
  }
});

Implement your save system - Connect Step 4 to your backend API
Add payment UI - Create buttons/UI for pay-to-play and purchases
Handle errors - Add user-friendly error messages
Test thoroughly - Test wallet connection, payments, and data loading

Common Issues

SDK Not Loading

Check internet connection
Verify CDN URL is correct
Check browser console for errors

Wallet Returns Null

Game must be running inside Arcadia's iframe
Player must connect wallet in Arcadia first
Ensure init() completed successfully

Payment Fails

Verify wallet has sufficient balance
Check game ID is correct
Ensure game is in Arcadia's iframe
Check console for detailed error

Need More Details?

Installation options: See Installation Guide
Wallet features: See Wallet Integration
Payment details: See Payments Guide
Complete examples: See Examples
API reference: See API Reference