Quest Module¶

public static class IVXQuestManager
{
    // ── Initialization ──
    public static void Initialize(string gameId);

    // ── Daily Quest Board ──
    public static async Task<IVXQuest[]> GetDailyQuestsAsync();
    public static async Task<IVXQuest[]> GetAllQuestsAsync(QuestFilter filter = null);
    public static async Task<IVXQuest[]> GetMilestoneQuestsAsync();
    public static async Task<IVXQuest[]> GetPvPChallengesAsync();

    // ── Progress Tracking ──
    public static async Task<IVXQuestProgress> GetProgressAsync(string questId);
    public static async Task<IVXQuestProgress> TrackProgressAsync(
        string questId, float value);
    public static async Task<IVXQuestProgress> IncrementProgressAsync(
        string questId, float delta = 1f);

    // ── Completion & Rewards ──
    public static async Task<IVXQuestCompletion> ClaimRewardAsync(string questId);
    public static async Task<RedemptionResult> RedeemXUTAsync(
        RedemptionType type, RedemptionOptions options);

    // ── Game Events (auto-progress) ──
    public static void SendEvent(string eventName, Dictionary<string, object> data);

    // ── Leaderboard ──
    public static async Task<LeaderboardEntry[]> GetQuestLeaderboardAsync(
        string questId, int limit = 50);

    // ── Events ──
    public static event Action<IVXQuest> OnQuestAvailable;
    public static event Action<IVXQuestProgress> OnQuestProgress;
    public static event Action<IVXQuestCompletion> OnQuestCompleted;
    public static event Action<IVXQuestCompletion> OnRewardClaimed;
    public static event Action<IVXQuest[]> OnDailyQuestsRefreshed;
}

using IntelliVerseX.Quest;

public class GameBootstrap : MonoBehaviour
{
    void Start()
    {
        // Initialize with your gameID from the QuestX admin panel
        IVXQuestManager.Initialize("your-game-id-here");

        // Subscribe to events
        IVXQuestManager.OnQuestCompleted += HandleQuestComplete;
        IVXQuestManager.OnDailyQuestsRefreshed += HandleDailyRefresh;
    }

    void HandleQuestComplete(IVXQuestCompletion completion)
    {
        Debug.Log($"Quest complete! Earned {completion.XUTEarned} XUT");
        ShowRewardPopup(completion);
    }

    void HandleDailyRefresh(IVXQuest[] dailies)
    {
        Debug.Log($"{dailies.Length} new daily quests available!");
    }
}

using IntelliVerseX.Quest;

public class DailyQuestUI : MonoBehaviour
{
    [SerializeField] private Transform questListParent;
    [SerializeField] private GameObject questCardPrefab;

    async void OnEnable()
    {
        var dailyQuests = await IVXQuestManager.GetDailyQuestsAsync();

        foreach (var quest in dailyQuests)
        {
            var card = Instantiate(questCardPrefab, questListParent);
            card.GetComponent<QuestCard>().Setup(quest);
        }
    }
}

using IntelliVerseX.Quest;

public class GameplayManager : MonoBehaviour
{
    void OnLevelCleared(int levelNumber)
    {
        IVXQuestManager.SendEvent("level_cleared", new Dictionary<string, object>
        {
            { "level", levelNumber },
            { "score", currentScore },
            { "time_seconds", elapsedTime }
        });
    }

    void OnMatchWon(string opponentId)
    {
        IVXQuestManager.SendEvent("match_result", new Dictionary<string, object>
        {
            { "result", "win" },
            { "opponent_id", opponentId }
        });
    }

    void OnScoreAchieved(int score)
    {
        IVXQuestManager.SendEvent("score_achieved", new Dictionary<string, object>
        {
            { "score", score }
        });
    }
}

// Increment progress (e.g., "Complete 5 surveys")
await IVXQuestManager.IncrementProgressAsync(questId);

// Set absolute progress (e.g., "Reach Level 20")
await IVXQuestManager.TrackProgressAsync(questId, currentLevel);

// Check progress
var progress = await IVXQuestManager.GetProgressAsync(questId);
Debug.Log($"Progress: {progress.Current}/{progress.Target} ({progress.Percent:P0})");

var completion = await IVXQuestManager.ClaimRewardAsync(questId);
Debug.Log($"Claimed {completion.XUTEarned} XUT! Wallet balance: {completion.NewBalance}");

public class IVXQuest
{
    public string Id { get; }
    public string Title { get; }
    public string Description { get; }
    public QuestType Type { get; }
    public QuestStatus Status { get; }

    // Goal
    public float TargetValue { get; }
    public float CurrentValue { get; }
    public float ProgressPercent { get; }

    // Reward
    public int RewardXUT { get; }
    public string RewardDescription { get; }

    // Timing
    public DateTime? ExpiresAt { get; }
    public TimeSpan? TimeRemaining { get; }
    public bool IsDaily { get; }

    // Game context
    public string GameId { get; }
    public string GameName { get; }
    public string Category { get; }
    public string Difficulty { get; } // easy, medium, hard

    // State
    public bool IsCompleted { get; }
    public bool IsClaimable { get; }
    public bool IsExpired { get; }

    // Milestone chain
    public int? MilestoneStep { get; }
    public int? TotalMilestones { get; }
    public IVXQuest NextMilestone { get; }
}

public enum QuestType
{
    DailyMission,
    Milestone,
    WinMatches,
    ReachLevel,
    AchieveScore,
    PlayStreak,
    LeaderboardRank,
    CustomEvent,
    ScratchAndWin,
    SpinAndWin,
    IntelliDraws,
    GiftCard,
    Survey,
    Referral,
    Social,
    Deal
}

public enum QuestStatus
{
    Available,
    InProgress,
    Completed,
    Claimed,
    Expired
}

public class IVXQuestProgress
{
    public string QuestId { get; }
    public float Current { get; }
    public float Target { get; }
    public float Percent { get; }
    public bool IsComplete { get; }
    public DateTime LastUpdated { get; }
    public Dictionary<string, object> Metadata { get; }
}

public class IVXQuestCompletion
{
    public string QuestId { get; }
    public string QuestTitle { get; }
    public int XUTEarned { get; }
    public int BonusXUT { get; } // streak bonus, multiplier, etc.
    public int TotalXUT { get; }
    public int NewBalance { get; }
    public DateTime CompletedAt { get; }
    public string CompletionId { get; }

    // Milestone
    public bool HasNextMilestone { get; }
    public IVXQuest NextMilestone { get; }

    // Streak
    public int CurrentStreak { get; }
    public float StreakMultiplier { get; }
}

using IntelliVerseX.Quest;

public class MilestoneUI : MonoBehaviour
{
    async void ShowMilestones()
    {
        var milestones = await IVXQuestManager.GetMilestoneQuestsAsync();

        foreach (var quest in milestones)
        {
            Debug.Log($"Step {quest.MilestoneStep}/{quest.TotalMilestones}: " +
                      $"{quest.Title} — {quest.RewardXUT} XUT " +
                      $"({quest.ProgressPercent:P0} complete)");
        }
    }
}

using IntelliVerseX.Quest;

public class PvPChallengeUI : MonoBehaviour
{
    async void ShowChallenges()
    {
        var challenges = await IVXQuestManager.GetPvPChallengesAsync();

        foreach (var challenge in challenges)
        {
            Debug.Log($"{challenge.Title} — " +
                      $"Ends: {challenge.TimeRemaining?.Hours}h " +
                      $"Prize: {challenge.RewardXUT} XUT");
        }
    }

    async void ShowLeaderboard(string questId)
    {
        var entries = await IVXQuestManager.GetQuestLeaderboardAsync(questId);

        foreach (var entry in entries)
        {
            Debug.Log($"#{entry.Rank} {entry.Username}: {entry.Score}");
        }
    }
}

using IntelliVerseX.Quest;

// Trigger scratch card after quest completion
IVXQuestManager.OnQuestCompleted += (completion) =>
{
    if (completion.HasScratchCard)
    {
        IVXQuestUI.ShowScratchCard(completion.ScratchCardId);
    }
};

// Show spin wheel (uses Hiro module integration)
var spinResult = await IVXQuestManager.TriggerSpinAsync();
Debug.Log($"Won: {spinResult.PrizeName} ({spinResult.XUTValue} XUT)");

// Enter a draw/lottery
await IVXQuestManager.EnterDrawAsync(drawId);
Debug.Log("Entered the draw! Results announced at end of week.");

using IntelliVerseX.Quest;

// Check wallet balance
int balance = await IVXQuestManager.GetWalletBalanceAsync();

// Redeem for gift card
var result = await IVXQuestManager.RedeemXUTAsync(
    RedemptionType.GiftCard,
    new RedemptionOptions
    {
        Amount = 500,
        ProductId = "amazon-10-usd"
    });

// Redeem for mobile top-up
var result = await IVXQuestManager.RedeemXUTAsync(
    RedemptionType.MobileTopUp,
    new RedemptionOptions
    {
        Amount = 300,
        PhoneNumber = "+1234567890",
        OperatorId = "t-mobile-us"
    });

// Redeem for digital merchandise (audiobooks, videos, game skins)
var result = await IVXQuestManager.RedeemXUTAsync(
    RedemptionType.DigitalMerch,
    new RedemptionOptions
    {
        Amount = 200,
        DigitalItemId = "audiobook-mystery-vol1",
        DeliveryMethod = DeliveryMethod.InAppDownload
    });

// Redeem for game skins
var result = await IVXQuestManager.RedeemXUTAsync(
    RedemptionType.DigitalMerch,
    new RedemptionOptions
    {
        Amount = 150,
        DigitalItemId = "dragon-armor-skin",
        DeliveryMethod = DeliveryMethod.InGameGrant
    });

// Redeem for in-game items (via Nakama economy)
var result = await IVXQuestManager.RedeemXUTAsync(
    RedemptionType.InGameItem,
    new RedemptionOptions
    {
        Amount = 100,
        ItemId = "legendary-sword"
    });

// Send events as they happen — don't batch
// The backend handles deduplication
void OnEnemyKilled()
{
    IVXQuestManager.SendEvent("enemy_killed", new Dictionary<string, object>
    {
        { "enemy_type", "boss" },
        { "weapon", "sword" }
    });
}

// Events are queued when offline and sent when reconnected
// Quest progress syncs automatically on reconnection
IVXQuestManager.OnReconnected += async () =>
{
    var quests = await IVXQuestManager.GetDailyQuestsAsync();
    RefreshQuestUI(quests);
};

IVXQuestManager.OnQuestProgress += (progress) =>
{
    ShowProgressToast($"{progress.Current}/{progress.Target}");

    if (progress.Percent >= 0.9f && !progress.IsComplete)
    {
        ShowAlmostThereNotification();
    }
};

IVXQuestManager.OnQuestCompleted += (completion) =>
{
    PlayConfettiEffect();
    ShowRewardPopup(completion);

    if (completion.HasNextMilestone)
    {
        ShowNextMilestoneTeaser(completion.NextMilestone);
    }
};

#if UNITY_EDITOR
[ContextMenu("Simulate Level Clear")]
void DebugLevelClear()
{
    IVXQuestManager.SendEvent("level_cleared", new Dictionary<string, object>
    {
        { "level", 20 },
        { "score", 5000 }
    });
}

[ContextMenu("Reset Daily Quests")]
void DebugResetDaily()
{
    IVXNakamaManager.RpcAsync("quest/debug_reset_daily", new { gameId = "your-game-id" });
}

[ContextMenu("Grant Test XUT")]
void DebugGrantXUT()
{
    IVXNakamaManager.RpcAsync("quest/debug_grant_xut", new { amount = 1000 });
}
#endif