Asset Management

Agent8 provides a comprehensive asset management system for handling in-game currencies, points, resources, and any fungible (interchangeable) items. Assets are automatically synchronized across clients and persist between sessions.

Understanding the Asset System

The asset system should be used for any fungible resources in your game—items that are identical and interchangeable with others of the same type. Assets are automatically validated, synchronized in real-time across all clients, and persist in the server.

Assets are perfect for game currencies, experience points, resources, and any stackable items. For unique items like individual weapons or NFTs, use User State or Collections instead.

When to Use Assets

✅ Use Assets For:

Game Currencies: Gold, coins, gems, credits
Points & Scores: Experience points, skill points, loyalty points
Resources: Wood, stone, food, energy
Fungible Tokens: Any ERC-20-like tokens, tradeable items
Consumables: Potions, ammunition, fuel
Stackable Items: Items that can have quantities (arrows, materials)

❌ Don’t Use Assets For:

Unique Items: Individual weapons, NFTs, character-specific items
User Profiles: Player names, avatars, settings
Game State: Room configurations, world state
Collections: Use Collection APIs for complex data structures

Server API

Access assets through the $asset variable in server code. All operations are automatically validated and synchronized:

$asset.get(assetId: string): Promise<number> - Gets specific asset amount
$asset.getAll(): Promise<Record<string, number>> - Gets all assets for current user
$asset.has(assetId: string, amount: number): Promise<boolean> - Checks if user has sufficient assets
$asset.mint(assetId: string, amount: number): Promise<Record<string, number>> - Creates new assets
$asset.burn(assetId: string, amount: number): Promise<Record<string, number>> - Destroys assets
$asset.transfer(toAccount: string, assetId: string, amount: number): Promise<Record<string, number>> - Transfers assets between users

server.js


class Server {
  async getMyAssets() {
    return await $asset.getAll();
  }
 
  getMissionReward(missionId) {
    const rewardTable = {
      'mission_tutorial': 50,
      'mission_daily': 100,
      'mission_boss': 500
    };
    return rewardTable[missionId] || 0;
  }
 
  async completeMission(missionId) {
    const reward = this.getMissionReward(missionId);
    if (reward === 0) throw new Error('Invalid mission');
    return await $asset.mint('gold', reward);
  }
 
  async buyItem(itemId) {
    const prices = { 'sword': 100, 'shield': 80, 'potion': 25 };
    const price = prices[itemId];
    if (!price) throw new Error('Item not found');
    if (!await $asset.has('gold', price)) {
      throw new Error('Insufficient gold');
    }
    await $asset.burn('gold', price);
    return await $asset.mint(itemId, 1);
  }
}

🚫

Security Best Practice: Never expose mintAsset(assetId, amount) or burnAsset(assetId, amount) directly to clients. Always wrap asset operations in server-controlled logic where the server determines the amounts based on game rules.

⚠️

All asset operations are atomic and automatically emit change notifications to connected clients. Operations with invalid amounts (negative, non-integer, or non-finite) will throw errors.

Client API

Subscriptions

server.subscribeAsset(account: string, (assets: Record<string, number>) => {}): UnsubscribeFunction

Hooks

const { assets, getAsset, hasAsset } = useAsset()

⚠️

The useAsset hook provides read-only access to assets. All asset modifications (mint, burn, transfer) must be performed server-side through the $asset API in server.js. This ensures proper validation and prevents client-side manipulation.


// Example using the useGameServer hook:
import { useGameServer } from "@agent8/gameserver";
import { useEffect } from "react";
 
function AssetComponent() {
  const { connected, server } = useGameServer();
 
  useEffect(() => {
    if (!connected) return;
 
    const unsubscribe = server.subscribeAsset(server.account, (assets) => {
      // Handle asset updates here
      console.log("Assets updated:", assets);
    });
 
    // Cleanup subscription when component unmounts
    return () => unsubscribe();
  }, [connected, server]);
 
  return <div>Asset Component</div>;
}

Sync Assets with React Hooks

For real-time asset synchronization in React components:


import { useAsset, useGameServer } from "@agent8/gameserver";
 
function AssetDisplay() {
  const { connected, server } = useGameServer();
  const { assets, getAsset, hasAsset } = useAsset();
 
  // Asset modifications must go through server functions
  const handleBuyItem = async () => {
    try {
      const result = await server.remoteFunction("buyItem", ["sword"]);
      console.log(result.message);
    } catch (error: any) {
      console.error("Purchase failed:", error.message);
    }
  };
 
  if (!connected) return <div>Connecting...</div>;
 
  return (
    <div>
      <h2>My Assets</h2>
      {Object.entries(assets).map(([assetId, amount]) => (
        <div key={assetId}>{assetId}: {amount}</div>
      ))}
 
      <p>Gold: {getAsset("gold")}</p>
      <p>Can afford sword (100 gold): {hasAsset("gold", 100) ? "Yes" : "No"}</p>
 
      <button
        onClick={handleBuyItem}
        disabled={!hasAsset("gold", 100)}
      >
        Buy Sword (100 gold)
      </button>
    </div>
  );
}

The useAsset hook automatically handles subscriptions and provides real-time asset updates. Asset modifications (mint/burn/transfer) should be triggered through server.remoteFunction() calls to your server-side logic.

Example 1: Game Shop System

This example demonstrates a complete game shop where players can buy items using gold currency.

server.js


class Server {
  // Initialize new players with starting gold
  async initializePlayer() {
    const currentGold = await $asset.get('gold');
    if (currentGold === 0) {
      await $asset.mint('gold', 1000);
      return { message: 'Welcome! You received 1000 gold!' };
    }
    return { message: 'Welcome back!' };
  }
 
  // Shop system
  async buyItem(itemId) {
    const prices = {
      'sword': 100,
      'shield': 80,
      'potion': 25,
      'armor': 200
    };
 
    const price = prices[itemId];
    if (!price) {
      throw new Error('Item not found');
    }
 
    // Check if player has enough gold
    if (!await $asset.has('gold', price)) {
      throw new Error(`Insufficient gold. Need ${price} gold.`);
    }
 
    // Execute the purchase
    await $asset.burn('gold', price);
    await $asset.mint(itemId, 1);
 
    return { 
      success: true, 
      message: `Purchased ${itemId} for ${price} gold!`,
      remainingGold: await $asset.get('gold')
    };
  }
 
  // Sell items back to shop
  async sellItem(itemId) {
    const sellPrices = {
      'sword': 50,
      'shield': 40,
      'potion': 12,
      'armor': 100
    };
 
    const sellPrice = sellPrices[itemId];
    if (!sellPrice) {
      throw new Error('Cannot sell this item');
    }
 
    if (!await $asset.has(itemId, 1)) {
      throw new Error('You do not own this item');
    }
 
    // Execute the sale
    await $asset.burn(itemId, 1);
    await $asset.mint('gold', sellPrice);
 
    return { 
      success: true, 
      message: `Sold ${itemId} for ${sellPrice} gold!`,
      totalGold: await $asset.get('gold')
    };
  }
}

src/GameShop.tsx


import React, { useEffect, useState } from "react";
import { useGameServer, useAsset } from "@agent8/gameserver";
 
export default function GameShop() {
  const { connected, server } = useGameServer();
  const { assets, hasAsset } = useAsset();
  const [message, setMessage] = useState("");
  const [loading, setLoading] = useState(false);
 
  useEffect(() => {
    if (connected) {
      // Initialize player when they connect
      server.remoteFunction("initializePlayer")
        .then(result => setMessage(result.message))
        .catch(err => console.error(err));
    }
  }, [connected, server]);
 
  const handleBuy = async (itemId: string) => {
    setLoading(true);
    try {
      const result = await server.remoteFunction("buyItem", [itemId]);
      setMessage(result.message);
    } catch (error: any) {
      setMessage(`Error: ${error.message}`);
    } finally {
      setLoading(false);
    }
  };
 
  const handleSell = async (itemId: string) => {
    setLoading(true);
    try {
      const result = await server.remoteFunction("sellItem", [itemId]);
      setMessage(result.message);
    } catch (error: any) {
      setMessage(`Error: ${error.message}`);
    } finally {
      setLoading(false);
    }
  };
 
  if (!connected) return <p>Connecting to game server...</p>;
 
  const items = [
    { id: 'sword', name: 'Sword', price: 100 },
    { id: 'shield', name: 'Shield', price: 80 },
    { id: 'potion', name: 'Potion', price: 25 },
    { id: 'armor', name: 'Armor', price: 200 }
  ];
 
  return (
    <div style={{ padding: '20px' }}>
      <h1>Game Shop</h1>
      
      {/* Player Assets */}
      <div style={{ marginBottom: '20px', padding: '10px', background: '#f5f5f5' }}>
        <h3>Your Assets</h3>
        <p><strong>Gold:</strong> {assets.gold || 0}</p>
        <div>
          <strong>Items:</strong>
          {Object.entries(assets)
            .filter(([key]) => key !== 'gold')
            .map(([itemId, amount]) => (
              <span key={itemId} style={{ marginLeft: '10px' }}>
                {itemId}: {amount}
              </span>
            ))}
        </div>
      </div>
 
      {/* Message Display */}
      {message && (
        <div style={{ marginBottom: '20px', padding: '10px', background: '#e6f3ff' }}>
          {message}
        </div>
      )}
 
      {/* Shop Items */}
      <div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fit, minmax(200px, 1fr))', gap: '10px' }}>
        {items.map(item => (
          <div key={item.id} style={{ border: '1px solid #ccc', padding: '10px' }}>
            <h4>{item.name}</h4>
            <p>Price: {item.price} gold</p>
            <p>You own: {assets[item.id] || 0}</p>
            <div>
              <button
                onClick={() => handleBuy(item.id)}
                disabled={loading || !hasAsset("gold", item.price)}
                style={{ marginRight: '5px' }}
              >
                Buy
              </button>
              <button
                onClick={() => handleSell(item.id)}
                disabled={loading || !hasAsset(item.id, 1)}
              >
                Sell
              </button>
            </div>
          </div>
        ))}
      </div>
 
    </div>
  );
}

Example 2: Player Trading System

This example shows how to implement a trading system where players can transfer assets to each other.

server.js


class Server {
  async sendGift(targetAccount, assetId, amount, message) {
    // Validation
    if (!targetAccount || !assetId || amount <= 0) {
      throw new Error('Invalid gift parameters');
    }
 
    if (targetAccount === $sender.account) {
      throw new Error('Cannot send gifts to yourself');
    }
 
    // Check if sender has enough assets
    if (!await $asset.has(assetId, amount)) {
      throw new Error(`Insufficient ${assetId}. You need ${amount} but have ${await $asset.get(assetId)}.`);
    }
 
    // Execute the transfer
    await $asset.transfer(targetAccount, assetId, amount);
 
    // Log the transaction (you could also use Collections to store transaction history)
    console.log(`Gift sent: ${$sender.account} → ${targetAccount}: ${amount} ${assetId}`);
 
    return {
      success: true,
      message: `Successfully sent ${amount} ${assetId} to ${targetAccount}`,
      remainingBalance: await $asset.get(assetId)
    };
  }
 
  async getPlayerAssets(targetAccount) {
    // This would require access to other players' assets
    // Note: In a real application, you might want to limit this or require permission
    return await $asset.getAll();
  }
 
  // Daily reward system
  async claimDailyReward() {
    const dailyRewards = {
      'gold': 100,
      'experience_points': 50
    };
 
    // In a real implementation, you'd check if the player already claimed today
    // using global user state or collections
    
    for (const [assetId, amount] of Object.entries(dailyRewards)) {
      await $asset.mint(assetId, amount);
    }
 
    return {
      success: true,
      message: 'Daily reward claimed!',
      rewards: dailyRewards,
      totalAssets: await $asset.getAll()
    };
  }
}

src/PlayerTrading.tsx


import React, { useState } from "react";
import { useGameServer, useAsset } from "@agent8/gameserver";
 
export default function PlayerTrading() {
  const { connected, server } = useGameServer();
  const { assets, hasAsset } = useAsset();
  const [loading, setLoading] = useState(false);
  const [giftForm, setGiftForm] = useState({
    targetAccount: '',
    assetId: 'gold',
    amount: 1,
    message: ''
  });
  const [result, setResult] = useState('');
 
  const handleSendGift = async (e: React.FormEvent) => {
    e.preventDefault();
    setLoading(true);
    try {
      const response = await server.remoteFunction("sendGift", [
        giftForm.targetAccount,
        giftForm.assetId,
        parseInt(giftForm.amount.toString()),
        giftForm.message
      ]);
      setResult(response.message);
      setGiftForm(prev => ({ ...prev, targetAccount: '', amount: 1, message: '' }));
    } catch (error: any) {
      setResult(`Error: ${error.message}`);
    } finally {
      setLoading(false);
    }
  };
 
  const handleClaimDailyReward = async () => {
    setLoading(true);
    try {
      const response = await server.remoteFunction("claimDailyReward");
      setResult(response.message);
    } catch (error: any) {
      setResult(`Error: ${error.message}`);
    } finally {
      setLoading(false);
    }
  };
 
  if (!connected) return <p>Connecting...</p>;
 
  const assetOptions = Object.keys(assets).length > 0 
    ? Object.keys(assets) 
    : ['gold', 'experience_points'];
 
  return (
    <div style={{ padding: '20px', maxWidth: '600px' }}>
      <h1>Player Trading</h1>
 
      {/* Current Assets */}
      <div style={{ marginBottom: '30px', padding: '15px', background: '#f5f5f5', borderRadius: '5px' }}>
        <h3>Your Assets</h3>
        {Object.entries(assets).length > 0 ? (
          Object.entries(assets).map(([assetId, amount]) => (
            <div key={assetId}>
              <strong>{assetId}:</strong> {amount}
            </div>
          ))
        ) : (
          <p>No assets yet. Claim your daily reward!</p>
        )}
      </div>
 
      {/* Daily Reward */}
      <div style={{ marginBottom: '30px' }}>
        <button 
          onClick={handleClaimDailyReward}
          disabled={loading}
          style={{ padding: '10px 20px', fontSize: '16px' }}
        >
          {loading ? 'Processing...' : 'Claim Daily Reward'}
        </button>
      </div>
 
      {/* Gift Form */}
      <form onSubmit={handleSendGift} style={{ marginBottom: '20px' }}>
        <h3>Send Gift</h3>
        
        <div style={{ marginBottom: '10px' }}>
          <label>Target Account:</label>
          <input
            type="text"
            value={giftForm.targetAccount}
            onChange={(e) => setGiftForm(prev => ({ ...prev, targetAccount: e.target.value }))}
            placeholder="0x123..."
            style={{ width: '100%', padding: '5px', marginTop: '5px' }}
            required
          />
        </div>
 
        <div style={{ marginBottom: '10px' }}>
          <label>Asset:</label>
          <select
            value={giftForm.assetId}
            onChange={(e) => setGiftForm(prev => ({ ...prev, assetId: e.target.value }))}
            style={{ width: '100%', padding: '5px', marginTop: '5px' }}
          >
            {assetOptions.map(assetId => (
              <option key={assetId} value={assetId}>
                {assetId} (You have: {assets[assetId] || 0})
              </option>
            ))}
          </select>
        </div>
 
        <div style={{ marginBottom: '10px' }}>
          <label>Amount:</label>
          <input
            type="number"
            min="1"
            value={giftForm.amount}
            onChange={(e) => setGiftForm(prev => ({ ...prev, amount: parseInt(e.target.value) || 1 }))}
            style={{ width: '100%', padding: '5px', marginTop: '5px' }}
          />
        </div>
 
        <div style={{ marginBottom: '15px' }}>
          <label>Message (optional):</label>
          <input
            type="text"
            value={giftForm.message}
            onChange={(e) => setGiftForm(prev => ({ ...prev, message: e.target.value }))}
            placeholder="Gift message..."
            style={{ width: '100%', padding: '5px', marginTop: '5px' }}
          />
        </div>
 
        <button
          type="submit"
          disabled={loading || !giftForm.targetAccount || !hasAsset(giftForm.assetId, giftForm.amount)}
          style={{ padding: '10px 20px' }}
        >
          {loading ? 'Sending...' : 'Send Gift'}
        </button>
      </form>
 
      {/* Result Display */}
      {result && (
        <div style={{ 
          padding: '10px', 
          background: result.startsWith('Error') ? '#ffe6e6' : '#e6f3ff',
          borderRadius: '5px'
        }}>
          {result}
        </div>
      )}
    </div>
  );
}

Best Practices

Use Descriptive Asset IDs
- Use clear names like "gold", "experience_points", "crafting_materials"
- Avoid generic names like "item1" or "currency"
Always Validate Before Operations
- Use $asset.has() to check availability before spending
- Validate amounts are positive integers
- Handle insufficient balance errors gracefully
Consider Player Experience
- Provide clear feedback for asset operations
- Show loading states during transactions
- Display current balances prominently
Security Considerations
- Server-side validation prevents cheating
- All operations are atomic and consistent
- Consider rate limiting for certain operations
Performance Tips
- Assets are automatically optimized for frequent updates
- Use useAsset hook for automatic React synchronization
- Use hasAsset() for efficient balance checks before operations

⚠️

Remember that assets are designed for fungible items only. For unique items, character data, or complex game objects, use User State or Collections instead.

Web3 CrossRamp Integration

Agent8 supports seamless Web3 token exchange through CrossRamp integration. Players can purchase in-game assets using real cryptocurrencies through a simple popup interface.

How CrossRamp Works

CrossRamp provides a bridge between Web3 wallets and your game’s asset system. When players want to purchase assets with cryptocurrency, they open a popup window that handles the entire transaction process securely.


import { useGameServer } from "@agent8/gameserver";
 
function TokenPurchaseButton() {
  const { connected, server } = useGameServer();
 
  const handleOpenCrossRampShop = async () => {
    if (!connected) return;
    
    try {
      // Get the CrossRamp shop URL
      const shopUrl = await server.getCrossRampShopUrl("en");
      
      // Open in popup window
      const popupWindow = window.open(
        shopUrl,
        "CrossRampShop",
        "width=1024,height=768,scrollbars=yes,resizable=yes"
      );
      
      // Optional: Listen for popup close
      const checkClosed = setInterval(() => {
        if (popupWindow?.closed) {
          clearInterval(checkClosed);
          console.log("CrossRamp popup closed");
          // Optionally refresh player assets here
        }
      }, 1000);
    } catch (error) {
      console.error("Failed to open CrossRamp shop:", error);
    }
  };
 
  return (
    <button onClick={handleOpenCrossRampShop} disabled={!connected}>
      Buy Tokens with Crypto
    </button>
  );
}

CrossRamp Features

Popup-Based Integration: Simple URL generation and popup window - no complex SDK required
Multi-Language Support: Available in English, Korean, Chinese, Japanese, and Spanish
Secure Transactions: All cryptocurrency transactions are handled securely by CrossRamp
Automatic Asset Delivery: Purchased tokens are automatically added to the player’s assets
Real-Time Updates: Asset changes are immediately synchronized across all connected clients

Supported Languages

"en" - English
"ko" - Korean (한국어)
"zh" - Chinese (中文)
"ja" - Japanese (日本語)
"es" - Spanish (Español)

Server-Side CrossRamp URL Generation

server.js


class Server {
  async getShopUrl(language = "en") {
    // This is handled automatically by the SDK
    // The server.getCrossRampShopUrl() method manages all the details
    return await server.getCrossRampShopUrl(language);
  }
  
  async handleTokenPurchase(tokenType, amount) {
    // This would be called by CrossRamp after successful purchase
    // to mint the corresponding in-game assets
    await $asset.mint(tokenType, amount);
    return { success: true, newBalance: await $asset.get(tokenType) };
  }
}

Security & Authentication

User Account Linking: CrossRamp transactions are automatically linked to the player’s game account
Secure Token Exchange: All cryptocurrency transactions use secure, audited smart contracts
Transaction Verification: Each purchase is verified before assets are minted in-game
No Direct Wallet Access: Your game never handles cryptocurrency directly - only the resulting assets

CrossRamp integration requires proper configuration in your game server. The system automatically handles wallet connections, transaction processing, and asset delivery without requiring complex Web3 implementation in your game client.

Conclusion

The Asset Management system provides a robust foundation for handling any fungible resources in your game. By leveraging server-side validation, real-time synchronization, and convenient React hooks, you can build sophisticated in-game economies while maintaining data consistency and security.

Use assets for currencies, points, resources, and consumables, and combine them with other Agent8 features like Global State and Collections to create rich, interactive multiplayer experiences.

Asset Management

Understanding the Asset System

When to Use Assets

✅ Use Assets For:

❌ Don’t Use Assets For:

Server API

Client API

Subscriptions

Hooks

Subscribe to Asset Updates

Sync Assets with React Hooks

Example 1: Game Shop System

Example 2: Player Trading System

Best Practices

Web3 CrossRamp Integration

How CrossRamp Works

CrossRamp Features

Supported Languages

Server-Side CrossRamp URL Generation

Security & Authentication

Conclusion