Godot SDK

Build Web3 games with GDScript - no blockchain knowledge required.

SDK Not Yet Released

The Godot SDK is currently under development and has not been released yet. The Vidya SDK addon is not available on the Godot Asset Library at this time. This documentation serves as a specification and preview of the upcoming SDK. Stay tuned for the official release!

Installation

1. Download the latest Vidya SDK addon from the Godot Asset Library
2. Extract the addon to your project's addons/vidya-sdk/ folder
3. Enable the plugin in Project Settings > Plugins

Getting Started

Setup & Authentication

extends Node

var vidya: VidyaSDK
var player: Player

func _ready():
    # Initialize with your project ID
    vidya = VidyaSDK.new({
        "project_id": "your-project-id", # Get from dashboard.vidya.game
        "environment": VidyaSDK.Environment.PRODUCTION # PRODUCTION | TESTNET | LOCAL
    })
    
    # Authenticate player (creates a session)
    var session = await vidya.auth.login({
        "provider": VidyaSDK.AuthProvider.GOOGLE # GOOGLE | DISCORD | EMAIL | APPLE
    })
    
    # Get the authenticated player object from the session
    player = Player.from_session(session)
    
    # Now use the player object throughout your game
    var items = await vidya.inventory.get_items(player)

Core Configuration

var vidya = VidyaSDK.new({
    "project_id": "your-project-id",    # Required: Your Vidya project ID
    "environment": VidyaSDK.Environment.PRODUCTION, # Required: PRODUCTION | TESTNET | LOCAL
    
    # Optional: Advanced configuration
    "chain": "polygon",               # Default: "polygon"
    "sponsor_gas": true,              # Default: true - Users don't pay gas
    
    # Optional: Custom contract addresses (rarely needed)
    "contracts": {
        "inventory": "0x...",
        "marketplace": "0x...",
        "fabricator": "0x..."
    }
})

The Player Object

The Vidya SDK uses a Player object to represent users throughout the system. This provides type safety and clear permission management.

Creating Player Objects

There are only two ways to create a Player object:

1. Authenticated Player (Full Access)

# After authentication, create player from session
var player = Player.from_session(session)

# This player can read and write
print(player.can_write) # true

2. Read-Only Player (View Only)

# Create a read-only player from a wallet address
var readonly_player = Player.from_wallet("0x742d35Cc6634C0532925a3b844Bc9e7595f5b123")

# This player can only read data
print(readonly_player.can_write) # false
print(readonly_player.is_readonly) # true

Finding Players

When you need to interact with other players, use the lookup methods:

# Find player by username
var other_player = await vidya.player.find_by_username("CoolGamer123")

# Find player by wallet address
var wallet_player = await vidya.player.find_by_wallet("0x742d35Cc6634C0532925a3b844Bc9e7595f5b123")

# Find player by ENS name
var ens_player = await vidya.player.find_by_ens("coolplayer.eth")

# Find multiple players at once
var players = await vidya.player.find_multiple({
    "usernames": ["Player1", "Player2"],
    "wallets": ["0x123...", "0x456..."]
})

Authentication

Login Methods

# Social login (recommended)
var session = await vidya.auth.login({
    "provider": VidyaSDK.AuthProvider.GOOGLE # GOOGLE | DISCORD | EMAIL | APPLE
})

# Email/password authentication
var session = await vidya.auth.login({
    "provider": VidyaSDK.AuthProvider.EMAIL,
    "email": "player@example.com",
    "password": "secure-password"
})

# Guest mode (instant play)
var session = await vidya.auth.login_as_guest()

# After login, always create the player object from session
var player = Player.from_session(session)

Session Management

# Check authentication status
if vidya.auth.is_authenticated():
    var session = vidya.auth.get_session()
    var player = Player.from_session(session)
    var profile = await vidya.auth.get_profile()
    print("Welcome back, %s!" % profile.username)

# Listen to auth events
vidya.auth.connect("login", _on_login)
vidya.auth.connect("logout", _on_logout)

func _on_login(session):
    var player = Player.from_session(session)
    print("Player logged in: ", player.player_id)

func _on_logout():
    print("Player logged out")

# Logout
await vidya.auth.logout()

Core Systems

Inventory System

All inventory operations use Player objects:

# Get current player's inventory
var session = vidya.auth.get_session()
var player = Player.from_session(session)
var items = await vidya.inventory.get_items(player)

# Get another player's inventory (read-only)
var other_player = await vidya.player.find_by_username("FriendName")
var friend_items = await vidya.inventory.get_items(other_player)

# Get a specific item by ID
var sword = await vidya.inventory.get_item(player, "sword-001")

# Get a specific item by predicate
var legendary_weapon = await vidya.inventory.get_item(player, 
    func(item): return item.name == "Legendary Sword" and not item.equipped
)

# Find all consumables
var consumables = await vidya.inventory.find_items(player,
    func(item): return item.slot == Item.Slot.CONSUMABLE
)

# Transfer an item using the item's method
var recipient = await vidya.player.find_by_wallet("0x456...")
if sword:
    await sword.transfer(recipient, 1)

# Batch transfer (still on inventory module)
var potion = await vidya.inventory.get_item(player, func(item): return item.name == "Health Potion")
await vidya.inventory.transfer_batch({
    "to": recipient,
    "items": [
        {"item": sword, "quantity": 1},
        {"item": potion, "quantity": 5}
    ]
})

# Equipment management using item methods
var weapon = await vidya.inventory.get_item(player, 
    func(item): return item.slot == Item.Slot.WEAPON and not item.equipped
)
if weapon:
    await weapon.equip()
    # Later...
    await weapon.unequip()

# Consume an item
var health_potion = await vidya.inventory.get_my_item(
    func(item): return item.name == "Health Potion" and item.quantity > 0
)
if health_potion:
    await health_potion.consume(1)

# List an item on marketplace
var rare_item = await vidya.inventory.get_my_item("rare-sword-001")
if rare_item:
    var listing = await rare_item.list(50, 1, 7) # price, quantity, duration

# Get equipped items
var equipped = await vidya.inventory.get_equipped_items(player)

Marketplace System

# Browse marketplace
var listings = await vidya.marketplace.get_listings({
    "category": "weapons",
    "min_price": 10,
    "max_price": 100,
    "sort": "price_asc",
    "limit": 20
})

# Filter by specific seller
var seller = await vidya.player.find_by_username("MerchantKing")
var seller_listings = await vidya.marketplace.get_listings({
    "seller": seller,
    "category": "rare-items"
})

# Buy items (requires authentication)
var all_listings = await vidya.marketplace.get_listings()
var sword_listing = all_listings.find(func(l): return l.item.name == "Rare Sword")

var purchase = await vidya.marketplace.buy_item({
    "listing": sword_listing,
    "quantity": 2
})

# Create listing using item method
var item_to_sell = await vidya.inventory.get_my_item(
    func(item): return item.name == "Rare Sword" and item.tradeable and not item.equipped
)

if item_to_sell:
    var listing = await item_to_sell.list(50, 1, 7) # price, quantity, duration

# Or use marketplace module directly
var listing = await vidya.marketplace.create_listing({
    "item": item_to_sell,
    "price": 50,              # USD
    "quantity": 1,
    "duration": 7             # Days
})

# Get player stats
var my_stats = await vidya.marketplace.get_stats(player)

Crafting System

# Get craftable recipes for current player
var session = vidya.auth.get_session()
var player = Player.from_session(session)
var recipes = await vidya.crafting.get_craftable_recipes(player)

# Get available recipes
var recipes = await vidya.crafting.get_craftable_recipes(player)
var sword_recipe = recipes.find(func(r): return r.name == "Epic Sword")

# Check requirements
var can_craft = await vidya.crafting.check_requirements(player, sword_recipe)
if not can_craft.success:
    # Get missing items
    for missing in can_craft.missing:
        print("Need %d more %s" % [missing.required - missing.have, missing.item.name])

# Check if you have materials using item methods
var iron_ore = await vidya.inventory.get_my_item("iron-ore-001")
if iron_ore and iron_ore.can_craft_with(sword_recipe):
    print("You have iron ore for this recipe!")

# Craft item
var result = await vidya.crafting.craft_item({
    "player": player,
    "recipe": sword_recipe
})

# Batch crafting
var potion_recipe = recipes.find(func(r): return r.name == "Health Potion")
var mana_recipe = recipes.find(func(r): return r.name == "Mana Potion")

var results = await vidya.crafting.craft_batch(player, [
    {"recipe": potion_recipe, "quantity": 10},
    {"recipe": mana_recipe, "quantity": 5}
])

# Get crafting history
var history = await vidya.crafting.get_history(player)

Gacha System

# Get available gacha boxes
var boxes = await vidya.gacha.get_boxes()
var premium_box = boxes.find(func(box): return box.name == "Premium Box")

# Open loot box
var session = vidya.auth.get_session()
var player = Player.from_session(session)
var reward = await vidya.gacha.open_box({
    "player": player,
    "box": premium_box
})

# Multi-pull
var rewards = await vidya.gacha.open_multiple({
    "player": player,
    "box": premium_box,
    "count": 10
})

# Check pity status
var pity = await vidya.gacha.get_pity_status(player, premium_box)
print("%d/%d until guaranteed rare" % [pity.current_count, pity.guaranteed])

Leaderboards

# Submit score
await vidya.leaderboard.submit_score({
    "leaderboard_id": "weekly-score",
    "score": 15000,
    "metadata": {"level": 45, "character": "warrior"}
})

# Get leaderboard
var leaderboard = await vidya.leaderboard.get_leaderboard("weekly-score", {
    "type": "weekly",
    "limit": 100
})

# Get player rank
var session = vidya.auth.get_session()
var player = Player.from_session(session)
var rank = await vidya.leaderboard.get_player_rank("weekly-score", player)
print("Rank: %d of %d" % [rank.rank, rank.total_players])

# Friends leaderboard
var friends_scores = await vidya.leaderboard.get_friends_leaderboard("weekly-score")

# Nearby players
var nearby = await vidya.leaderboard.get_nearby_players("weekly-score", player, 5)

Social System

# Get social profile
var session = vidya.auth.get_session()
var player = Player.from_session(session)
var profile = await vidya.social.get_profile(player)

# Send friend request
var new_friend = await vidya.player.find_by_username("CoolPlayer")
await vidya.social.send_friend_request(new_friend, "Let's team up!")

# Accept friend request
var pending_requests = await vidya.social.get_pending_friend_requests()
if pending_requests.size() > 0:
    await vidya.social.accept_friend_request(pending_requests[0].from)

# Create guild
var guild = await vidya.social.create_guild({
    "name": "Elite Warriors",
    "tag": "ELITE",
    "description": "Top players only",
    "max_members": 100
})

# Invite to guild
var member = await vidya.player.find_by_wallet("0x789...")
await vidya.social.invite_to_guild(guild.id, member)

AI NPCs

# Spawn NPC
var npc = await vidya.npc.spawn_npc({
    "definition_id": "merchant-001",
    "location": Vector3(100, 0, 50)
})

# Interact with NPC
var dialogue = await vidya.npc.interact({
    "npc_id": npc.definition.id,
    "action": "talk"
})

# Trade with NPC
var wolf_pelt = await vidya.inventory.get_my_item(
    func(item): return item.name == "Wolf Pelt" and item.quantity >= 10
)
var health_potion = npc.inventory.find(func(item): return item.name == "Health Potion")

if wolf_pelt and health_potion:
    var trade_result = await vidya.npc.trade({
        "npc": npc,
        "buying": [{"item": health_potion, "quantity": 5}],
        "selling": [{"item": wolf_pelt, "quantity": 10}]
    })

# Give gift to improve relationship
var rare_gem = await vidya.inventory.get_my_item("rare-gem-001")
if rare_gem:
    await vidya.npc.give_gift(npc, rare_gem, 1)

# Check relationship
var session = vidya.auth.get_session()
var player = Player.from_session(session)
var relationship = await vidya.npc.get_relationship(npc.definition.id, player)

Currency System

# Get balances
var session = vidya.auth.get_session()
var player = Player.from_session(session)
var balances = await vidya.currency.get_balances(player)

# Transfer currency to another player
var recipient = await vidya.player.find_by_username("TeamMate")
await vidya.currency.transfer({
    "from": player,
    "to": recipient,
    "currency": "gold",
    "amount": 100
})

# Grant rewards (requires permissions)
await vidya.currency.grant(player, {
    "gold": 500,
    "gems": 10
})

# Spend currency
await vidya.currency.spend(player, {
    "currency": "gems",
    "amount": 20,
    "reason": "speed-boost-purchase"
})

Advanced Features

Error Handling

# Using match for error handling
var result = await vidya.marketplace.buy_item({"listing": listing, "quantity": 1})
if result.has("error"):
    match result.error.code:
        "INSUFFICIENT_BALANCE":
            print(result.error.message)
        "PLAYER_NOT_AUTHENTICATED":
            await vidya.auth.login({"provider": VidyaSDK.AuthProvider.GOOGLE})
        "READ_ONLY_PLAYER":
            print("Please sign in to perform this action")
        _:
            print("Unexpected error: ", result.error.message)

Event System

# Module events
vidya.inventory.connect("item_received", _on_item_received)
vidya.marketplace.connect("item_purchased", _on_item_purchased)

func _on_item_received(event):
    print("%s received %s" % [event.player.player_id, event.item.name])

func _on_item_purchased(event):
    print("Purchase complete: %s" % event.listing.item.name)

# Global events
vidya.connect("transaction", _on_transaction)

func _on_transaction(tx):
    print("Transaction %s: %s" % [tx.id, tx.status])

Complete Example

extends Node

class_name GameClient

var vidya: VidyaSDK
var player: Player

func _ready():
    await initialize()

func initialize():
    # Initialize SDK
    vidya = VidyaSDK.new({
        "project_id": "your-project-id",
        "environment": VidyaSDK.Environment.PRODUCTION
    })
    
    # Authenticate
    var session = await vidya.auth.login({"provider": VidyaSDK.AuthProvider.DISCORD})
    player = Player.from_session(session)
    
    # Setup event listeners
    setup_event_listeners()

func send_gift_to_friend(friend_username: String, item_name: String):
    # Find friend
    var friend = await vidya.player.find_by_username(friend_username)
    
    # Find item using predicate
    var item = await vidya.inventory.get_my_item(
        func(i): return i.name == item_name and i.tradeable and i.quantity > 0
    )
    
    if not item:
        push_error("Tradeable item '%s' not found in inventory" % item_name)
        return
    
    # Transfer using item method
    await item.transfer(friend, 1)
    
    # Send friend request if not already friends
    var friends = await vidya.social.get_friends()
    var is_friend = friends.any(func(f): return f.player.player_id == friend.player_id)
    
    if not is_friend:
        await vidya.social.send_friend_request(friend, "Thanks for playing!")

func participate_in_guild_event(guild_id: String):
    # Contribute to guild
    await vidya.social.contribute_to_guild(guild_id, {
        "currency": "gold",
        "amount": 100
    })
    
    # Update leaderboard
    await vidya.leaderboard.submit_score({
        "leaderboard_id": "guild-contribution",
        "score": 100,
        "metadata": {"guild_id": guild_id}
    })

func setup_event_listeners():
    vidya.inventory.connect("item_received", _on_item_received)
    vidya.social.connect("friend_request_received", _on_friend_request_received)

func _on_item_received(event):
    if event.player.player_id == player.player_id:
        show_notification("Received %s!" % event.item.name)

func _on_friend_request_received(event):
    show_notification("Friend request from %s" % event.from.player_id)

func show_notification(message: String):
    print("[Notification] %s" % message)
    # Show UI notification

API Reference

For detailed API documentation, see the SDK documentation.

Godot-Specific Features

Scene Integration

The SDK includes ready-to-use scenes:

• Authentication Panel (social logins)
• Inventory Display Grid
• Marketplace Browser
• Crafting Station UI
• Leaderboard Display
• Social/Friends List
• NPC Interaction Dialog

Signal-Based Architecture

All SDK modules emit Godot signals for seamless integration:

# Connect to signals in the editor or via code
vidya.inventory.item_received.connect(_on_item_received)
vidya.auth.session_expired.connect(_on_session_expired)

Mobile Optimization

# Configure for mobile
vidya.configure_mobile({
    "auto_manage_session": true,
    "biometric_auth": true,
    "low_bandwidth_mode": true
})

GDScript Support

The SDK provides full GDScript integration with type hints and autocompletion:

# Type hints for better IDE support
func process_item(item: Item) -> void:
    print("%s: %dx" % [item.name, item.quantity])

# Typed arrays
func process_items(items: Array[Item]) -> void:
    for item in items:
        process_item(item)