Skip to main content

Godot API Reference

Complete API reference for the Vidya Godot SDK.

Core Classes​

VidyaSDK​

The main singleton for interacting with Vidya in Godot.

extends Node

class_name VidyaSDK

# Singleton access
static var instance: VidyaSDK

# Properties
var auth: AuthModule
var inventory: InventoryModule
var marketplace: MarketplaceModule
var crafting: CraftingModule
var gacha: GachaModule
var leaderboard: LeaderboardModule
var social: SocialModule
var npc: NPCModule
var currency: CurrencyModule
var quest: QuestModule
var stats: StatsModule

# Methods
func initialize(config: Dictionary) -> void
func get_project() -> Dictionary
func get_session() -> Dictionary
func set_session(session: Dictionary) -> void
func clear_session() -> void

# Signals
signal session_changed(session)
signal error_occurred(error)
signal initialized()

Player​

Represents a player with full type safety in GDScript.

extends Resource

class_name Player

# Static factory methods
static func from_session(session: Dictionary) -> Player
static func from_wallet(wallet: String) -> Player

# Properties
export var id: String
export var wallet: String
export var can_write: bool

# Methods
func require_write() -> void
func get_profile() -> Dictionary
func get_stats() -> Dictionary
func get_achievements() -> Array

# Comparison
func equals(other: Player) -> bool

Item​

Represents an in-game item with Godot integration.

extends Resource

class_name Item

# Properties
export var id: int
export var name: String
export var description: String
export var image: String
export var attributes: Array  # Array of dictionaries
export var owner: String
export var balance: int
export var equipped: bool
export var tradeable: bool
export var consumable: bool
export var stackable: bool
export var max_stack: int
export var character_slot: int  # CharacterSlot enum

# Godot-specific
export var texture: Texture
export var scene: PackedScene

# Methods
func transfer(to: Player, quantity: int = 1) -> void
func equip() -> void
func unequip() -> void
func consume(quantity: int = 1) -> void
func list(price: String, quantity: int = 1) -> Dictionary  # Returns Listing
func get_listings() -> Array
func burn(quantity: int = 1) -> void

# Godot helpers
func load_texture(callback: FuncRef) -> void
func instantiate(parent: Node = null) -> Node

Modules​

AuthModule​

Handles authentication in Godot.

extends Node

class_name AuthModule

# Methods
func login(options: Dictionary) -> Dictionary  # Returns Session
func logout() -> void
func refresh_session() -> Dictionary
func get_session() -> Dictionary

# OAuth providers
func login_with_google() -> Dictionary
func login_with_discord() -> Dictionary
func login_with_twitter() -> Dictionary

# Wallet authentication
func login_with_wallet(options: Dictionary) -> Dictionary
func connect_wallet(type: String) -> String

# Signals
signal logged_in(session)
signal logged_out()
signal session_refreshed(session)

InventoryModule​

Manages player inventory with Godot nodes.

extends Node

class_name InventoryModule

# Item retrieval
func get_items(player: Player) -> Array  # Array of Items
func get_item(player: Player, predicate: FuncRef) -> Item
func get_item_by_id(player: Player, id: int) -> Item
func get_equipped_items(player: Player) -> Array

# Item operations
func equip_item(params: Dictionary) -> void
func unequip_item(params: Dictionary) -> void
func transfer_item(params: Dictionary) -> void
func consume_item(params: Dictionary) -> void

# Batch operations
func transfer_batch(params: Dictionary) -> void
func equip_batch(params: Dictionary) -> void

# Godot-specific
func create_inventory_ui() -> Control
func bind_to_slot(slot: Control, item: Item) -> void

# Signals
signal items_changed(items)
signal item_equipped(item)
signal item_unequipped(item)
signal item_consumed(item, quantity)

MarketplaceModule​

Marketplace integration for Godot.

extends Node

class_name MarketplaceModule

# Listing management
func create_listing(params: Dictionary) -> Dictionary  # Returns Listing
func cancel_listing(listing_id: String) -> void
func get_listings(filter: Dictionary = {}) -> Array
func get_player_listings(player: Player) -> Array

# Trading
func buy_listing(listing_id: String, quantity: int = 1) -> void
func make_offer(params: Dictionary) -> Dictionary  # Returns Offer
func accept_offer(offer_id: String) -> void
func reject_offer(offer_id: String) -> void
func get_offers(player: Player) -> Array

# Price data
func get_item_price_history(item_id: int) -> Array
func get_floor_price(item_id: int) -> String
func get_market_stats(item_id: int) -> Dictionary

# Godot UI
func create_marketplace_ui() -> Control
func create_listing_card(listing: Dictionary) -> Control

# Signals
signal listing_created(listing)
signal listing_sold(sale)
signal listing_cancelled(listing)

CraftingModule​

Crafting system for Godot.

extends Node

class_name CraftingModule

# Recipe management
func get_recipes() -> Array
func get_recipe(recipe_id: int) -> Dictionary
func get_available_recipes(player: Player) -> Array

# Crafting
func craft(player: Player, recipe_id: int, quantity: int = 1) -> Array
func get_crafting_cost(recipe_id: int, quantity: int = 1) -> Dictionary
func can_craft(player: Player, recipe_id: int, quantity: int = 1) -> bool

# Batch crafting
func craft_batch(player: Player, recipes: Array) -> Array

# Godot UI
func create_crafting_ui() -> Control
func show_crafting_animation(recipe: Dictionary, callback: FuncRef) -> void

# Signals
signal item_crafted(result)
signal recipe_unlocked(recipe)

GachaModule​

Gacha/loot box system for Godot.

extends Node

class_name GachaModule

# Gacha pools
func get_pools() -> Array
func get_pool(pool_id: String) -> Dictionary

# Rolling
func roll(player: Player, pool_id: String, count: int = 1) -> Dictionary
func get_roll_cost(pool_id: String, count: int = 1) -> Dictionary
func get_pity_status(player: Player, pool_id: String) -> Dictionary

# History
func get_roll_history(player: Player, pool_id: String = "") -> Array
func get_drop_rates(pool_id: String) -> Array

# Godot animations
func play_gacha_animation(result: Dictionary, callback: FuncRef) -> void
func create_gacha_effect(rarity: int) -> Node2D

# Signals
signal roll_completed(result)
signal pity_triggered(pity)

LeaderboardModule​

Leaderboard system with Godot UI.

extends Node

class_name LeaderboardModule

# Leaderboard access
func get_leaderboards() -> Array
func get_leaderboard(leaderboard_id: String) -> Dictionary
func get_player_rank(player: Player, leaderboard_id: String) -> Dictionary

# Rankings
func get_top_players(leaderboard_id: String, limit: int = 100) -> Array
func get_nearby_players(player: Player, leaderboard_id: String, range: int = 10) -> Array
func get_friend_rankings(player: Player, leaderboard_id: String) -> Array

# Score submission
func submit_score(player: Player, leaderboard_id: String, score: int) -> void

# Godot UI
func create_leaderboard_ui() -> Control
func show_rank_change_animation(change: Dictionary, position: Vector2) -> void

# Signals
signal rank_changed(change)
signal leaderboard_updated(data)

SocialModule​

Social features for Godot games.

extends Node

class_name SocialModule

# Friends
func get_friends(player: Player) -> Array
func send_friend_request(from: Player, to: Player) -> void
func accept_friend_request(player: Player, request_id: String) -> void
func remove_friend(player: Player, friend_id: String) -> void
func block_player(player: Player, target_id: String) -> void

# Guilds
func create_guild(player: Player, params: Dictionary) -> Dictionary
func join_guild(player: Player, guild_id: String) -> void
func leave_guild(player: Player) -> void
func get_guild(guild_id: String) -> Dictionary
func get_guild_members(guild_id: String) -> Array

# Messaging
func send_message(from: Player, to: Player, message: String) -> void
func get_messages(player: Player) -> Array

# Godot UI
func create_friends_list_ui() -> Control
func create_guild_ui() -> Control
func create_chat_ui() -> Control

# Signals
signal friend_request_received(request)
signal message_received(message)
signal guild_invite_received(invite)

NPCModule​

AI-powered NPCs for Godot.

extends Node

class_name NPCModule

# NPC interactions
func get_npcs() -> Array
func get_npc(npc_id: String) -> Dictionary
func talk_to_npc(player: Player, npc_id: String, message: String) -> Dictionary

# NPC state
func get_npc_relationship(player: Player, npc_id: String) -> Dictionary
func get_npc_inventory(npc_id: String) -> Array

# Trading with NPCs
func trade_with_npc(player: Player, npc_id: String, params: Dictionary) -> void
func get_npc_shop(npc_id: String) -> Dictionary

# Godot integration
func create_npc_controller(npc_node: Node2D) -> Node
func show_dialogue(response: Dictionary, dialogue_ui: Control) -> void

# Signals
signal npc_interaction(interaction)
signal relationship_changed(change)

Godot-Specific Nodes​

Custom Nodes​

# Inventory slot node
extends Control

class_name InventorySlot

export var item: Item setget set_item
signal item_clicked(item)
signal item_dropped(item)

func set_item(new_item: Item) -> void
func clear() -> void
func highlight(active: bool) -> void
# Item display node
extends Control

class_name ItemDisplay

export(NodePath) var icon_path
export(NodePath) var name_label_path
export(NodePath) var quantity_label_path
export(NodePath) var equipped_indicator_path

func set_item(item: Item) -> void
func update_quantity(quantity: int) -> void
# Marketplace listing card
extends Control

class_name ListingCard

export(NodePath) var item_icon_path
export(NodePath) var item_name_path
export(NodePath) var price_label_path
export(NodePath) var seller_label_path
export(NodePath) var buy_button_path

signal buy_clicked(listing)

func set_listing(listing: Dictionary) -> void

Resources​

# Vidya configuration resource
extends Resource

class_name VidyaConfig

export var project_id: String
export(String, "development", "staging", "production") var environment = "production"
export var api_url: String
export var debug: bool = false
# Item template resource
extends Resource

class_name ItemTemplate

export var item_id: int
export var icon: Texture
export var scene: PackedScene
export var use_sound: AudioStream
export var use_effect: PackedScene

Types and Enums​

Core Enums​

# Character slots
enum CharacterSlot {
    NONE = 0,
    HEAD = 1,
    BODY = 2,
    LEGS = 3,
    FEET = 4,
    HANDS = 5,
    WEAPON = 6,
    SHIELD = 7,
    ACCESSORY = 8
}

# Rarity levels
enum Rarity {
    COMMON = 1,
    UNCOMMON = 2,
    RARE = 3,
    EPIC = 4,
    LEGENDARY = 5
}

# Auth providers
enum AuthProvider {
    GOOGLE,
    DISCORD,
    TWITTER,
    WALLET
}

# Wallet types
enum WalletType {
    METAMASK,
    WALLETCONNECT,
    PHANTOM,
    COINBASE
}

Type Definitions​

# Session dictionary structure
# {
#     "id": String,
#     "player": Dictionary,
#     "wallet": String,
#     "expires_at": int (timestamp),
#     "refresh_token": String
# }

# Item attribute dictionary
# {
#     "id": int,
#     "name": String,
#     "value": Variant,
#     "display_value": String
# }

# Listing dictionary
# {
#     "id": String,
#     "seller": String,
#     "item": Dictionary,
#     "price": String,
#     "quantity": int,
#     "created_at": int,
#     "expires_at": int (optional)
# }

# Recipe dictionary
# {
#     "id": int,
#     "name": String,
#     "description": String,
#     "requirements": Array,
#     "outputs": Array,
#     "crafting_time": int (optional),
#     "cooldown": int (optional)
# }

Error Handling​

# Vidya error class
extends Reference

class_name VidyaError

enum ErrorCode {
    # Authentication
    UNAUTHENTICATED,
    UNAUTHORIZED,
    SESSION_EXPIRED,
    
    # Validation
    INVALID_PARAMETER,
    INSUFFICIENT_BALANCE,
    ITEM_NOT_FOUND,
    
    # Operations
    OPERATION_FAILED,
    TRANSACTION_FAILED,
    RATE_LIMITED,
    
    # Network
    NETWORK_ERROR,
    TIMEOUT
}

var message: String
var code: int
var details: Dictionary

func _init(msg: String, error_code: int, error_details: Dictionary = {}):
    message = msg
    code = error_code
    details = error_details

Autoload Scripts​

# Vidya autoload singleton
extends Node

# Called when added to scene tree
func _ready():
    # Initialize Vidya SDK
    var config = preload("res://vidya_config.tres")
    VidyaSDK.instance.initialize({
        "project_id": config.project_id,
        "environment": config.environment,
        "api_url": config.api_url,
        "debug": config.debug
    })

# Handle authentication state
func _on_session_changed(session):
    if session:
        print("Player logged in: ", session.player.name)
    else:
        print("Player logged out")

Editor Plugin​

# Vidya editor plugin
tool
extends EditorPlugin

const VIDYA_MENU = "Vidya"

func _enter_tree():
    # Add custom menu items
    add_tool_menu_item("Vidya Setup Wizard", self, "_show_setup_wizard")
    add_tool_menu_item("Vidya Item Browser", self, "_show_item_browser")
    add_tool_menu_item("Vidya Documentation", self, "_open_documentation")
    
    # Add custom types
    add_custom_type(
        "VidyaInventorySlot",
        "Control",
        preload("res://addons/vidya/nodes/inventory_slot.gd"),
        preload("res://addons/vidya/icons/inventory_slot.svg")
    )

func _exit_tree():
    remove_tool_menu_item("Vidya Setup Wizard")
    remove_tool_menu_item("Vidya Item Browser")
    remove_tool_menu_item("Vidya Documentation")
    remove_custom_type("VidyaInventorySlot")

func _show_setup_wizard():
    var wizard = preload("res://addons/vidya/wizard/setup_wizard.tscn").instance()
    get_editor_interface().get_base_control().add_child(wizard)
    wizard.popup_centered()

func _show_item_browser():
    var browser = preload("res://addons/vidya/browser/item_browser.tscn").instance()
    get_editor_interface().get_base_control().add_child(browser)
    browser.popup_centered()

func _open_documentation():
    OS.shell_open("https://docs.vidya.game")

Utilities​

# BigInteger utilities for GDScript
static func wei_to_ether(wei: String, decimals: int = 18) -> String
static func ether_to_wei(ether: float, decimals: int = 18) -> String
static func format_currency(amount: String, decimals: int = 18) -> String

# Texture loading utilities
static func load_texture_from_url(url: String, callback: FuncRef) -> void
static func create_sprite_from_texture(texture: Texture) -> Sprite

# Async helpers
static func await_signal(signal_obj: Object, signal_name: String) -> Array
static func await_all(tasks: Array) -> Array

# Item sorting and filtering
static func sort_items(items: Array, sort_by: String = "name") -> Array
static func filter_items(items: Array, filter: Dictionary) -> Array
static func group_items_by_id(items: Array) -> Dictionary

Signals Reference​

# Global signals (via autoload)
signal player_logged_in(player)
signal player_logged_out()
signal inventory_updated(items)
signal item_acquired(item)
signal quest_completed(quest)
signal achievement_unlocked(achievement)
signal error_occurred(error)

# Module-specific signals
# AuthModule
signal login_success(session)
signal login_failed(error)
signal session_expired()

# InventoryModule
signal item_equipped(item, slot)
signal item_unequipped(item, slot)
signal item_transferred(item, from, to, quantity)
signal item_consumed(item, quantity)

# MarketplaceModule
signal listing_created(listing)
signal listing_purchased(listing, buyer)
signal offer_received(offer)
signal offer_accepted(offer)

# SocialModule
signal friend_added(friend)
signal friend_removed(friend)
signal message_received(message)
signal guild_joined(guild)