Skip to main content

Unity API Reference

Complete API reference for the Vidya Unity SDK.

Core Classes​

VidyaSDK​

The main entry point for interacting with Vidya in Unity.

public class VidyaSDK : MonoBehaviour
{
    // Singleton instance
    public static VidyaSDK Instance { get; }
    
    // Properties
    public AuthModule Auth { get; }
    public InventoryModule Inventory { get; }
    public MarketplaceModule Marketplace { get; }
    public CraftingModule Crafting { get; }
    public GachaModule Gacha { get; }
    public LeaderboardModule Leaderboard { get; }
    public SocialModule Social { get; }
    public NPCModule NPC { get; }
    public CurrencyModule Currency { get; }
    public QuestModule Quest { get; }
    public StatsModule Stats { get; }
    
    // Methods
    public async Task Initialize(VidyaConfig config)
    public async Task<Project> GetProject()
    public Session GetSession()
    public void SetSession(Session session)
    public void ClearSession()
    
    // Events
    public event Action<Session> OnSessionChanged;
    public event Action<VidyaError> OnError;
}

Player​

Represents a player in the game with full type safety.

public class Player
{
    // Static factory methods
    public static Player FromSession(Session session)
    public static Player FromWallet(string wallet)
    
    // Properties
    public string Id { get; }
    public string Wallet { get; }
    public bool CanWrite { get; }
    
    // Methods
    public void RequireWrite()
    public async Task<PlayerProfile> GetProfile()
    public async Task<PlayerStats> GetStats()
    public async Task<Achievement[]> GetAchievements()
    
    // Equality
    public bool Equals(Player other)
    public override int GetHashCode()
}

Item​

Represents an in-game item with Unity-specific features.

public class Item
{
    // Properties
    public int Id { get; }
    public string Name { get; }
    public string Description { get; }
    public string Image { get; }
    public ItemAttribute[] Attributes { get; }
    public string Owner { get; }
    public int Balance { get; }
    public bool Equipped { get; }
    public bool Tradeable { get; }
    public bool Consumable { get; }
    public bool Stackable { get; }
    public int MaxStack { get; }
    public CharacterSlot CharacterSlot { get; }
    
    // Unity-specific
    public Sprite Sprite { get; }
    public GameObject Prefab { get; }
    
    // Methods
    public async Task Transfer(Player to, int quantity = 1)
    public async Task Equip()
    public async Task Unequip()
    public async Task Consume(int quantity = 1)
    public async Task<Listing> List(BigInteger price, int quantity = 1)
    public async Task<Listing[]> GetListings()
    public async Task Burn(int quantity = 1)
    
    // Unity helpers
    public void LoadSprite(Action<Sprite> callback)
    public GameObject Instantiate(Transform parent = null)
}

Modules​

AuthModule​

Handles authentication in Unity.

public class AuthModule
{
    // Methods
    public async Task<Session> Login(LoginOptions options)
    public async Task Logout()
    public async Task<Session> RefreshSession()
    public Session GetSession()
    
    // OAuth providers
    public async Task<Session> LoginWithGoogle()
    public async Task<Session> LoginWithDiscord()
    public async Task<Session> LoginWithTwitter()
    
    // Wallet authentication
    public async Task<Session> LoginWithWallet(WalletLoginOptions options)
    public async Task<string> ConnectWallet(WalletType type)
    
    // Events
    public event Action<Session> OnLogin;
    public event Action OnLogout;
    public event Action<Session> OnSessionRefreshed;
}

InventoryModule​

Manages player inventory with Unity integration.

public class InventoryModule
{
    // Item retrieval
    public async Task<Item[]> GetItems(Player player)
    public async Task<Item> GetItem(Player player, Func<Item, bool> predicate)
    public async Task<Item> GetItem(Player player, int id)
    public async Task<Item[]> GetEquippedItems(Player player)
    
    // Item operations
    public async Task EquipItem(EquipParams parameters)
    public async Task UnequipItem(UnequipParams parameters)
    public async Task TransferItem(TransferParams parameters)
    public async Task ConsumeItem(ConsumeParams parameters)
    
    // Batch operations
    public async Task TransferBatch(BatchTransferParams parameters)
    public async Task EquipBatch(BatchEquipParams parameters)
    
    // Unity-specific
    public InventoryUI CreateInventoryUI(Canvas canvas)
    public void BindToSlot(InventorySlot slot, Item item)
    
    // Events
    public event Action<Item[]> OnItemsChanged;
    public event Action<Item> OnItemEquipped;
    public event Action<Item> OnItemUnequipped;
    public event Action<Item, int> OnItemConsumed;
}

MarketplaceModule​

Unity marketplace integration.

public class MarketplaceModule
{
    // Listing management
    public async Task<Listing> CreateListing(CreateListingParams parameters)
    public async Task CancelListing(string listingId)
    public async Task<Listing[]> GetListings(ListingFilter filter = null)
    public async Task<Listing[]> GetPlayerListings(Player player)
    
    // Trading
    public async Task BuyListing(string listingId, int quantity = 1)
    public async Task<Offer> MakeOffer(OfferParams parameters)
    public async Task AcceptOffer(string offerId)
    public async Task RejectOffer(string offerId)
    public async Task<Offer[]> GetOffers(Player player)
    
    // Price data
    public async Task<PricePoint[]> GetItemPriceHistory(int itemId)
    public async Task<BigInteger> GetFloorPrice(int itemId)
    public async Task<MarketStats> GetMarketStats(int itemId)
    
    // Unity UI
    public MarketplaceUI CreateMarketplaceUI(Canvas canvas)
    public ListingCard CreateListingCard(Listing listing, Transform parent)
    
    // Events
    public event Action<Listing> OnListingCreated;
    public event Action<Sale> OnListingSold;
    public event Action<Listing> OnListingCancelled;
}

CraftingModule​

Crafting system for Unity.

public class CraftingModule
{
    // Recipe management
    public async Task<Recipe[]> GetRecipes()
    public async Task<Recipe> GetRecipe(int recipeId)
    public async Task<Recipe[]> GetAvailableRecipes(Player player)
    
    // Crafting
    public async Task<Item[]> Craft(Player player, int recipeId, int quantity = 1)
    public async Task<CraftingCost> GetCraftingCost(int recipeId, int quantity = 1)
    public async Task<bool> CanCraft(Player player, int recipeId, int quantity = 1)
    
    // Batch crafting
    public async Task<Item[]> CraftBatch(Player player, CraftBatchParams[] recipes)
    
    // Unity UI
    public CraftingUI CreateCraftingUI(Canvas canvas)
    public void ShowCraftingAnimation(Recipe recipe, Action onComplete)
    
    // Events
    public event Action<CraftResult> OnItemCrafted;
    public event Action<Recipe> OnRecipeUnlocked;
}

GachaModule​

Gacha/loot box system for Unity.

public class GachaModule
{
    // Gacha pools
    public async Task<GachaPool[]> GetPools()
    public async Task<GachaPool> GetPool(string poolId)
    
    // Rolling
    public async Task<GachaResult> Roll(Player player, string poolId, int count = 1)
    public async Task<RollCost> GetRollCost(string poolId, int count = 1)
    public async Task<PityStatus> GetPityStatus(Player player, string poolId)
    
    // History
    public async Task<RollHistory[]> GetRollHistory(Player player, string poolId = null)
    public async Task<DropRate[]> GetDropRates(string poolId)
    
    // Unity animations
    public void PlayGachaAnimation(GachaResult result, Canvas canvas, Action onComplete)
    public GameObject CreateGachaEffect(Rarity rarity)
    
    // Events
    public event Action<GachaResult> OnRoll;
    public event Action<PityTrigger> OnPityTriggered;
}

LeaderboardModule​

Leaderboard system with Unity UI.

public class LeaderboardModule
{
    // Leaderboard access
    public async Task<Leaderboard[]> GetLeaderboards()
    public async Task<LeaderboardData> GetLeaderboard(string leaderboardId)
    public async Task<RankData> GetPlayerRank(Player player, string leaderboardId)
    
    // Rankings
    public async Task<LeaderboardEntry[]> GetTopPlayers(string leaderboardId, int limit = 100)
    public async Task<LeaderboardEntry[]> GetNearbyPlayers(Player player, string leaderboardId, int range = 10)
    public async Task<LeaderboardEntry[]> GetFriendRankings(Player player, string leaderboardId)
    
    // Score submission
    public async Task SubmitScore(Player player, string leaderboardId, int score)
    
    // Unity UI
    public LeaderboardUI CreateLeaderboardUI(Canvas canvas)
    public void ShowRankChangeAnimation(RankChange change, Vector3 position)
    
    // Events
    public event Action<RankChange> OnRankChanged;
    public event Action<LeaderboardData> OnLeaderboardUpdated;
}

SocialModule​

Social features for Unity games.

public class SocialModule
{
    // Friends
    public async Task<Friend[]> GetFriends(Player player)
    public async Task SendFriendRequest(Player from, Player to)
    public async Task AcceptFriendRequest(Player player, string requestId)
    public async Task RemoveFriend(Player player, string friendId)
    public async Task BlockPlayer(Player player, string targetId)
    
    // Guilds
    public async Task<Guild> CreateGuild(Player player, CreateGuildParams parameters)
    public async Task JoinGuild(Player player, string guildId)
    public async Task LeaveGuild(Player player)
    public async Task<Guild> GetGuild(string guildId)
    public async Task<GuildMember[]> GetGuildMembers(string guildId)
    
    // Messaging
    public async Task SendMessage(Player from, Player to, string message)
    public async Task<Message[]> GetMessages(Player player)
    
    // Unity UI
    public FriendsListUI CreateFriendsListUI(Canvas canvas)
    public GuildUI CreateGuildUI(Canvas canvas)
    public ChatUI CreateChatUI(Canvas canvas)
    
    // Events
    public event Action<FriendRequest> OnFriendRequest;
    public event Action<Message> OnMessage;
    public event Action<GuildInvite> OnGuildInvite;
}

NPCModule​

AI-powered NPCs for Unity.

public class NPCModule
{
    // NPC interactions
    public async Task<NPC[]> GetNPCs()
    public async Task<NPC> GetNPC(string npcId)
    public async Task<NPCResponse> TalkToNPC(Player player, string npcId, string message)
    
    // NPC state
    public async Task<Relationship> GetNPCRelationship(Player player, string npcId)
    public async Task<Item[]> GetNPCInventory(string npcId)
    
    // Trading with NPCs
    public async Task TradeWithNPC(Player player, string npcId, NPCTradeParams parameters)
    public async Task<NPCShop> GetNPCShop(string npcId)
    
    // Unity integration
    public NPCController CreateNPCController(GameObject npcObject)
    public void ShowDialogue(NPCResponse response, DialogueUI ui)
    
    // Events
    public event Action<NPCInteraction> OnNPCInteraction;
    public event Action<RelationshipChange> OnRelationshipChange;
}

Unity-Specific Components​

MonoBehaviour Components​

// Inventory slot component
[RequireComponent(typeof(Image))]
public class InventorySlot : MonoBehaviour
{
    public Item Item { get; set; }
    public event Action<Item> OnItemClicked;
    public event Action<Item> OnItemDropped;
    
    public void SetItem(Item item)
    public void Clear()
    public void Highlight(bool active)
}

// Item display component
public class ItemDisplay : MonoBehaviour
{
    public Image Icon;
    public Text Name;
    public Text Quantity;
    public GameObject EquippedIndicator;
    
    public void SetItem(Item item)
    public void UpdateQuantity(int quantity)
}

// Marketplace listing card
public class ListingCard : MonoBehaviour
{
    public Image ItemIcon;
    public Text ItemName;
    public Text Price;
    public Text Seller;
    public Button BuyButton;
    
    public void SetListing(Listing listing)
    public void OnBuyClicked()
}

ScriptableObjects​

// Vidya configuration asset
[CreateAssetMenu(fileName = "VidyaConfig", menuName = "Vidya/Config")]
public class VidyaConfigAsset : ScriptableObject
{
    public string ProjectId;
    public Environment Environment = Environment.Production;
    public string ApiUrl;
    public bool Debug;
}

// Item template for editor
[CreateAssetMenu(fileName = "ItemTemplate", menuName = "Vidya/Item Template")]
public class ItemTemplate : ScriptableObject
{
    public int ItemId;
    public Sprite Icon;
    public GameObject Prefab;
    public AudioClip UseSound;
    public ParticleSystem UseEffect;
}

Types and Enums​

Core Types​

public class VidyaConfig
{
    public string ProjectId { get; set; }
    public Environment Environment { get; set; }
    public string ApiUrl { get; set; }
    public string WsUrl { get; set; }
    public bool Debug { get; set; }
}

public enum Environment
{
    Development,
    Staging,
    Production
}

public enum CharacterSlot
{
    None = 0,
    Head = 1,
    Body = 2,
    Legs = 3,
    Feet = 4,
    Hands = 5,
    Weapon = 6,
    Shield = 7,
    Accessory = 8
}

Authentication Types​

public class Session
{
    public string Id { get; set; }
    public PlayerInfo Player { get; set; }
    public string Wallet { get; set; }
    public DateTime ExpiresAt { get; set; }
    public string RefreshToken { get; set; }
}

public class LoginOptions
{
    public AuthProvider Provider { get; set; }
    public string RedirectUrl { get; set; }
}

public enum AuthProvider
{
    Google,
    Discord,
    Twitter,
    Wallet
}

public enum WalletType
{
    MetaMask,
    WalletConnect,
    Phantom,
    Coinbase
}

Item Types​

public class ItemAttribute
{
    public int Id { get; set; }
    public string Name { get; set; }
    public object Value { get; set; }
    public string DisplayValue { get; set; }
}

public class EquipParams
{
    public Player Player { get; set; }
    public Item Item { get; set; }
    public CharacterSlot? Slot { get; set; }
}

public class TransferParams
{
    public Player From { get; set; }
    public Player To { get; set; }
    public Item Item { get; set; }
    public int Quantity { get; set; }
}

Marketplace Types​

public class Listing
{
    public string Id { get; set; }
    public string Seller { get; set; }
    public Item Item { get; set; }
    public BigInteger Price { get; set; }
    public int Quantity { get; set; }
    public DateTime CreatedAt { get; set; }
    public DateTime? ExpiresAt { get; set; }
}

public class ListingFilter
{
    public int? ItemId { get; set; }
    public string Seller { get; set; }
    public BigInteger? MinPrice { get; set; }
    public BigInteger? MaxPrice { get; set; }
    public CharacterSlot? CharacterSlot { get; set; }
    public AttributeFilter[] Attributes { get; set; }
}

Gacha Types​

public class GachaPool
{
    public string Id { get; set; }
    public string Name { get; set; }
    public string Description { get; set; }
    public GachaItem[] Items { get; set; }
    public Cost Cost { get; set; }
    public PitySystem PitySystem { get; set; }
}

public class GachaResult
{
    public Item[] Items { get; set; }
    public Animation[] Animations { get; set; }
    public int? PityProgress { get; set; }
}

public enum Rarity
{
    Common = 1,
    Uncommon = 2,
    Rare = 3,
    Epic = 4,
    Legendary = 5
}

Error Handling​

public class VidyaException : Exception
{
    public ErrorCode Code { get; }
    public object Details { get; }
    
    public VidyaException(string message, ErrorCode code, object details = null) 
        : base(message)
    {
        Code = code;
        Details = details;
    }
}

public enum ErrorCode
{
    // Authentication
    Unauthenticated,
    Unauthorized,
    SessionExpired,
    
    // Validation
    InvalidParameter,
    InsufficientBalance,
    ItemNotFound,
    
    // Operations
    OperationFailed,
    TransactionFailed,
    RateLimited,
    
    // Network
    NetworkError,
    Timeout
}

Editor Integration​

// Custom inspector for Vidya items
[CustomEditor(typeof(ItemTemplate))]
public class ItemTemplateEditor : Editor
{
    public override void OnInspectorGUI()
    {
        // Custom inspector UI
    }
}

// Vidya menu items
public static class VidyaMenu
{
    [MenuItem("Vidya/Setup Wizard")]
    public static void ShowSetupWizard()
    {
        // Show setup wizard
    }
    
    [MenuItem("Vidya/Item Browser")]
    public static void ShowItemBrowser()
    {
        // Show item browser window
    }
    
    [MenuItem("Vidya/Documentation")]
    public static void OpenDocumentation()
    {
        Application.OpenURL("https://docs.vidya.game");
    }
}

Utilities​

// BigInteger extensions for Unity
public static class BigIntegerExtensions
{
    public static string ToEtherString(this BigInteger wei, int decimals = 18)
    public static BigInteger ToWei(this decimal ether, int decimals = 18)
}

// Sprite loading utilities
public static class SpriteLoader
{
    public static async Task<Sprite> LoadFromUrl(string url)
    public static Sprite CreateFromTexture(Texture2D texture)
}

// Coroutine helpers
public static class CoroutineHelpers
{
    public static Coroutine ToCoroutine(this Task task, MonoBehaviour behaviour)
    public static IEnumerator AsCoroutine(this Task task)
}