Roblox Integration Guide¶

local IVX = require(game.ServerScriptService.IntelliVerseX)

IVX.configure({
    game_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",  -- from your dashboard
    server_key = "your-server-key",                      -- from your dashboard
    debug = true,                                        -- set false in production
})

-- Automatically authenticate every player on join
-- and clean up sessions on leave
IVX.enable_auto_auth()

-- Listen for auth events
IVX.on("auth_success", function(player, session)
    print(player.Name .. " authenticated -> Nakama user " .. session.user_id)
end)

IVX.on("auth_error", function(player, err)
    warn("Auth failed for " .. player.Name .. ": " .. err)
end)

local IVX = require(game.ServerScriptService.IntelliVerseX)

-- Define NPC personalities
local NPCS = {
    shopkeeper = {
        npc_id = "shopkeeper_01",
        persona_id = "friendly_merchant",
        name = "Elara the Merchant",
        system_prompt = "You are Elara, a friendly merchant in a fantasy RPG. "
            .. "You sell potions, weapons, and armor. Be helpful but try to upsell. "
            .. "Keep responses under 3 sentences. Use the player's name when possible.",
        max_turns = 20,
    },
    guard = {
        npc_id = "gate_guard",
        persona_id = "stern_guard",
        name = "Captain Thorne",
        system_prompt = "You are Captain Thorne, the stern but fair castle gate guard. "
            .. "Only let players through if they can prove they have a quest. "
            .. "You speak in short, military sentences.",
        max_turns = 10,
    },
}

-- Track active dialogs
local activeDialogs = {}

IVX.Remotes.on_server_event("IVX_StartNPCDialog", function(player, npcKey)
    local npcConfig = NPCS[npcKey]
    if not npcConfig then return end

    -- End existing dialog if any
    if activeDialogs[player.UserId] then
        IVX.AI.NPC.end_dialog(activeDialogs[player.UserId])
    end

    local session, err = IVX.AI.NPC.start_dialog(npcConfig, tostring(player.UserId))
    if session then
        activeDialogs[player.UserId] = session.dialog_id
        IVX.Remotes.fire_client("IVX_NPCResponse", player, {
            npc_name = npcConfig.name,
            message = session.greeting or "Hello, traveler!",
            dialog_id = session.dialog_id,
        })
    else
        warn("[NPC] Start failed: " .. (err or "unknown"))
    end
end)

IVX.Remotes.on_server_event("IVX_SendNPCMessage", function(player, message)
    local dialogId = activeDialogs[player.UserId]
    if not dialogId then return end

    -- Moderate input first
    local modResult = IVX.AI.Moderator.check_text(message)
    if modResult and modResult.flagged then
        IVX.Remotes.fire_client("IVX_NPCResponse", player, {
            message = "[Message blocked by moderation]",
        })
        return
    end

    local response, err = IVX.AI.NPC.send_message(dialogId, message)
    if response then
        IVX.Remotes.fire_client("IVX_NPCResponse", player, {
            message = response.text or response.message or "",
        })
    end
end)

IVX.Remotes.on_server_event("IVX_EndNPCDialog", function(player)
    local dialogId = activeDialogs[player.UserId]
    if dialogId then
        IVX.AI.NPC.end_dialog(dialogId)
        activeDialogs[player.UserId] = nil
    end
end)

game.Players.PlayerRemoving:Connect(function(player)
    local dialogId = activeDialogs[player.UserId]
    if dialogId then
        IVX.AI.NPC.end_dialog(dialogId)
        activeDialogs[player.UserId] = nil
    end
end)

local ReplicatedStorage = game:GetService("ReplicatedStorage")
local Players = game:GetService("Players")
local player = Players.LocalPlayer

-- Wait for SDK remotes to be created
local remotes = ReplicatedStorage:WaitForChild("IntelliVerseXRemotes")
local startDialog = remotes:WaitForChild("IVX_StartNPCDialog")
local sendMessage = remotes:WaitForChild("IVX_SendNPCMessage")
local endDialog = remotes:WaitForChild("IVX_EndNPCDialog")
local npcResponse = remotes:WaitForChild("IVX_NPCResponse")

-- Listen for NPC responses
npcResponse.OnClientEvent:Connect(function(data)
    -- Display in your UI (chat bubble, dialog box, etc.)
    print("[NPC] " .. (data.npc_name or "NPC") .. ": " .. data.message)
end)

-- Example: trigger when player clicks an NPC model
local function onNPCClicked(npcModel)
    local npcKey = npcModel:GetAttribute("IVXNpcKey") -- e.g., "shopkeeper"
    if npcKey then
        startDialog:FireServer(npcKey)
    end
end

-- Example: send a player message
local function sendPlayerMessage(text)
    sendMessage:FireServer(text)
end

local IVX = require(game.ServerScriptService.IntelliVerseX)

-- Daily reward status (client calls this on join to update UI)
IVX.Remotes.on_server_invoke("IVX_GetDailyRewards", function(player)
    local status, err = IVX.Hiro.DailyRewards.get_status(player)
    if status then
        return { ok = true, data = status }
    end
    return { ok = false, error = err }
end)

-- Claim daily reward
IVX.Remotes.on_server_invoke("IVX_ClaimDailyReward", function(player)
    local result, err = IVX.Hiro.DailyRewards.claim(player)
    if result then
        IVX.Hiro.Streaks.update(player)
        return { ok = true, data = result }
    end
    return { ok = false, error = err }
end)

-- Streak info
IVX.Remotes.on_server_invoke("IVX_GetStreaks", function(player)
    local data, err = IVX.Hiro.Streaks.get(player)
    return { ok = data ~= nil, data = data, error = err }
end)

-- Get current season pass state
IVX.Remotes.on_server_invoke("IVX_GetSeasonPass", function(player)
    local data, err = IVX.Hiro.SeasonPass.get(player)
    return { ok = data ~= nil, data = data, error = err }
end)

-- Award XP when player completes a game action
local function awardSeasonXP(player, amount)
    IVX.Hiro.SeasonPass.add_xp(player, amount)
end

-- Claim a tier reward
IVX.Remotes.on_server_invoke("IVX_ClaimSeasonTier", function(player, tier)
    if type(tier) ~= "number" then return { ok = false, error = "Invalid tier" } end
    local data, err = IVX.Hiro.SeasonPass.claim_tier(player, tier)
    return { ok = data ~= nil, data = data, error = err }
end)

IVX.Remotes.on_server_invoke("IVX_SpinWheel", function(player)
    local result, err = IVX.Hiro.SpinWheel.spin(player)
    return { ok = result ~= nil, data = result, error = err }
end)

IVX.Remotes.on_server_invoke("IVX_SpinFortuneWheel", function(player)
    local result, err = IVX.Hiro.FortuneWheel.spin(player)
    return { ok = result ~= nil, data = result, error = err }
end)

-- Submit score to league
IVX.Remotes.on_server_invoke("IVX_SubmitLeagueScore", function(player, score)
    if type(score) ~= "number" then return { ok = false } end
    local data, err = IVX.Hiro.Leagues.submit_score(player, score)
    return { ok = data ~= nil, data = data, error = err }
end)

-- Join a tournament
IVX.Remotes.on_server_invoke("IVX_JoinTournament", function(player, tournamentId)
    if type(tournamentId) ~= "string" then return { ok = false } end
    local data, err = IVX.Hiro.Tournaments.join(player, tournamentId)
    return { ok = data ~= nil, data = data, error = err }
end)

local IVX = require(game.ServerScriptService.IntelliVerseX)

-- Fetch cross-game profile (display name, avatar, metadata from ANY game)
IVX.Remotes.on_server_invoke("IVX_GetProfile", function(player)
    local profile, err = IVX.Identity.fetch_profile(player)
    return { ok = profile ~= nil, data = profile, error = err }
end)

-- Update display name (synced everywhere)
IVX.Remotes.on_server_invoke("IVX_UpdateDisplayName", function(player, name)
    if type(name) ~= "string" or #name < 1 or #name > 50 then
        return { ok = false, error = "Invalid name" }
    end
    local ok, err = IVX.Identity.update_profile(player, { display_name = name })
    return { ok = ok, error = err }
end)

-- Cross-game wallet (shared currency across all your games)
IVX.Remotes.on_server_invoke("IVX_GetWallet", function(player)
    local data, err = IVX.Identity.fetch_wallet(player)
    return { ok = data ~= nil, data = data, error = err }
end)

-- Save progress (accessible from any game using IntelliVerseX)
IVX.Remotes.on_server_invoke("IVX_SaveProgress", function(player, data)
    if type(data) ~= "table" then return { ok = false, error = "Invalid data" } end
    local ok, err = IVX.Identity.write_storage(player, "game_progress", "main", data)
    return { ok = ok, error = err }
end)

-- Load progress
IVX.Remotes.on_server_invoke("IVX_LoadProgress", function(player)
    local data, err = IVX.Identity.read_storage(player, "game_progress", "main")
    return { ok = data ~= nil, data = data, error = err }
end)

IVX.Remotes.on_server_invoke("IVX_UpdateProfile", function(player, fields)
    -- Validate types
    if type(fields) ~= "table" then
        return { ok = false, error = "Invalid input" }
    end

    -- Whitelist allowed fields
    local safe = {}
    if type(fields.display_name) == "string" and #fields.display_name <= 50 then
        safe.display_name = fields.display_name
    end
    if type(fields.avatar_url) == "string" and #fields.avatar_url <= 500 then
        safe.avatar_url = fields.avatar_url
    end

    local ok, err = IVX.Identity.update_profile(player, safe)
    return { ok = ok, error = err }
end)

local lastRequest = {}
local COOLDOWN = 1 -- seconds

IVX.Remotes.on_server_invoke("IVX_SpinWheel", function(player)
    local now = os.clock()
    if lastRequest[player.UserId] and now - lastRequest[player.UserId] < COOLDOWN then
        return { ok = false, error = "Too fast" }
    end
    lastRequest[player.UserId] = now

    local result, err = IVX.Hiro.SpinWheel.spin(player)
    return { ok = result ~= nil, data = result, error = err }
end)

local function safeSdkCall(fn, ...)
    local ok, result, err = pcall(fn, ...)
    if not ok then
        warn("[IVX] pcall error: " .. tostring(result))
        return nil, "Internal error"
    end
    return result, err
end

-- Usage
IVX.Remotes.on_server_invoke("IVX_ClaimDaily", function(player)
    local data, err = safeSdkCall(IVX.Hiro.DailyRewards.claim, player)
    return { ok = data ~= nil, data = data, error = err }
end)

local result, err = IVX.call_rpc(player, "my_custom_rpc", '{"key": "value"}')