---

Trigger API Reference\DCEI Functions\AsyncPvp

void AsyncPvp.GetCurrentSeasonInfo(TypedCallback<object> callback)

void AsyncPvp.GetCurrentSeasonInfo(TypedCallback<object> callback)

Description

Returns the latest season information in a Lua table, formatted as:

{
  id = string,
  status = number, -- 0 => not started, 1 => running, 2 => finished
  start_time = seconds since unix epoch,
  end_time = seconds since unix epoch,
  next_season_start_time = seconds since unix epoch, -- set when status is 2.
}

You can use Lua “os.time” to get the current time in seconds from unix epoch and compare it against the start/end time to know how long the season has started and how long it will end. Use Lua “os.date” to format the time into human-readable strings.

The season “id” returned from this API is required for all following AsyncPvp API calls

Parameters

• TypedCallback<object> callback the callback function to handle the returned season info.

Callback Parameters

• Object result

Example Usage

Demo map with source code: https://platform.wildsky.dev/arcade/game/775

DCEI.AsyncPvp.GetCurrentSeasonInfo(function(result)
    season = result
    season_info:SetSeasonInfo(season)
    DCEI.AsyncPvp.GetCurrentUserInfo(season.id, function(result)
        user_info:SetUserInfo(result)
        if result.board == nil or #result.board == 0 then
            DCEI.AsyncPvp.SetDefenseBoard(season.id, string.format("b%s", DCEI.GetUserTag()), function()
                self:Refresh()
            end)
        else
            DCEI.AsyncPvp.GetLeaderBoard(season.id, "season", function(result)
                season_leader_board:SetLeaderBoard("season", result.players)
            end)
            DCEI.AsyncPvp.GetLeaderBoard(season.id, "today", function(result)
                daily_leader_board:SetLeaderBoard("today", result.players)
            end)
        end
    end)
    session_info:ClearSessionInfo()
end)

void AsyncPvp.GetCurrentUserInfo(string season, TypedCallback<object> callback)

void AsyncPvp.GetCurrentUserInfo(string season, TypedCallback<object> callback)

Description

The season id from AsyncPvp.GetCurrentSeasonInfo is required. This API returns the info about the current user in the specified season:

{
  elo = number,
  board = string, -- You may want to check if board is empty or not
  season_rank = number,
  daily_rank = number,
}

Each user belongs to a group; both season rank and daily rank are for that group. The group info is transparent to the users, and client APIs do not include that info.

Parameters

• string season The season id from AsyncPvp.GetCurrentSeasonInfo.
• TypedCallback<object> callback the callback function to handle the returned user info.

Callback Parameters

• Object result

Example Usage

Demo map with source code: https://platform.wildsky.dev/arcade/game/775

DCEI.AsyncPvp.GetCurrentSeasonInfo(function(result)
    season = result
    season_info:SetSeasonInfo(season)
    DCEI.AsyncPvp.GetCurrentUserInfo(season.id, function(result)
        user_info:SetUserInfo(result)
        if result.board == nil or #result.board == 0 then
            DCEI.AsyncPvp.SetDefenseBoard(season.id, string.format("b%s", DCEI.GetUserTag()), function()
                self:Refresh()
            end)
        else
            DCEI.AsyncPvp.GetLeaderBoard(season.id, "season", function(result)
                season_leader_board:SetLeaderBoard("season", result.players)
            end)
            DCEI.AsyncPvp.GetLeaderBoard(season.id, "today", function(result)
                daily_leader_board:SetLeaderBoard("today", result.players)
            end)
        end
    end)
    session_info:ClearSessionInfo()
end)

void AsyncPvp.SetDefenseBoard(string season, string board, TypedCallback<object> callback)

void AsyncPvp.SetDefenseBoard(string season, string board, TypedCallback<object> callback)

Description

Set the defense board of the user. The API returns an empty table when successful.

A new user can only start to participate in async-pvp after they set a defense board. Before that, they can’t start async-pvp sessions, can’t be attacked by others, and won’t appear in the leaderboards.

Parameters

• string season The season id from AsyncPvp.GetCurrentSeasonInfo
• string board An arbitrary string to assign to the player; the server doesn't do anything with this besides return it with the other player info in other APIs. Use this to store player-specific info that your own Lua script interprets, such as a players card collection, army layout, or board arrangement.
• TypedCallback<object> callback the callback function to handle the returned user info. Results parameter includes next_season_start_time field if the current season has finished.

Callback Parameters

• Object result

Example Usage

Demo map with source code: https://platform.wildsky.dev/arcade/game/775

DCEI.AsyncPvp.GetCurrentSeasonInfo(function(result)
    season = result
    season_info:SetSeasonInfo(season)
    DCEI.AsyncPvp.GetCurrentUserInfo(season.id, function(result)
        user_info:SetUserInfo(result)
        if result.board == nil or #result.board == 0 then
            DCEI.AsyncPvp.SetDefenseBoard(season.id, string.format("b%s", DCEI.GetUserTag()), function()
                self:Refresh()
            end)
        else
            DCEI.AsyncPvp.GetLeaderBoard(season.id, "season", function(result)
                season_leader_board:SetLeaderBoard("season", result.players)
            end)
            DCEI.AsyncPvp.GetLeaderBoard(season.id, "today", function(result)
                daily_leader_board:SetLeaderBoard("today", result.players)
            end)
        end
    end)
    session_info:ClearSessionInfo()
end)

void AsyncPvp.GetDefenseHistory(string season, TypedCallback<object> callback)

void AsyncPvp.GetDefenseHistory(string season, TypedCallback<object> callback)

Description

Retrieves the defense history for the season.

Parameters

• string season The season id from AsyncPvp.GetCurrentSeasonInfo.
• TypedCallback<object> callback the callback function to handle the returned data.

Callback Parameters

• Object result

Example Usage

Demo map with source code: https://platform.wildsky.dev/arcade/game/775

DCEI.AsyncPvp.GetCurrentSeasonInfo(function(result)
    season = result
    season_info:SetSeasonInfo(season)
    DCEI.AsyncPvp.GetCurrentUserInfo(season.id, function(result)
        user_info:SetUserInfo(result)
        if result.board == nil or #result.board == 0 then
            DCEI.AsyncPvp.SetDefenseBoard(season.id, string.format("b%s", DCEI.GetUserTag()), function()
                self:Refresh()
            end)
        else
            DCEI.AsyncPvp.GetDefenseHistory(season.id, function(result)
                defense_history:SetDefenseHistory(result.entries)
            end)
        end
    end)
    session_info:ClearSessionInfo()
end)

-- DefenseHistory
function controller:SetDefenseHistory(entries)
    DCEI.SetListFrameItemCount(list, #entries)
    DCEI.SetListFrameItemDataCallback(list, function(item, index)
        local entry = entries[index]
        local player = entry.attacker
        local text = DCEI.GetChildFrameById(item, "text")
        DCEI.SetTextFrameText(
            text,
            string.format(
                "%s, %s, %s, %d, %s",
                entry.session_id,
                os.date("%x %X", entry.time),
                player.tag,
                entry.result,
                entry.payload
            )
        )
    end)
    DCEI.RefreshListFrameItems(list, 1, #entries)
end

void AsyncPvp.SetDefenseProtectionTime(string season, int timestamp, TypedCallback<object> callback)

void AsyncPvp.SetDefenseProtectionTime(string season, int timestamp, TypedCallback<object> callback)

Description

Experimental API: Not intended for wide use

Parameters

• string season The season id from AsyncPvp.GetCurrentSeasonInfo.
• int timestamp The current time.
• TypedCallback<object> callback the callback function to handle the returned data.

Callback Parameters

• Object result

Example Usage

-- Placeholder example
DCEI.AsyncPvp.SetDefenseProtectionTime(season.id, 0, function(result)
    -- Handle the result here
    end)

void AsyncPvp.NewSession(string season, TypedCallback<object> callback)

void AsyncPvp.NewSession(string season, TypedCallback<object> callback)

Description

This API should only be called when the season is still active.

Start a new async-pvp session. This API returns the following:

{
  id = string,
  start_time = seconds since unix epoch,
  finished_opponents = number,
  current_opponent = {
    uuid = string, tag = string, name = string, elo = number, board = string
  }
}

The server will create a new session and find the first opponent to return in the “current_opponent” field. The opponent will be selected based on the server’s async-pvp configuration and the position of the opponent. If no opponent can be found, the “current_opponent” field will be nil.

NOTE: if a session hasn’t been finished with the FinishSeason API, NewSession() will return that session instead of creating a new one. The “finished_opponents” field will be set to the number of finished matches so the client knows how many matches are left.

Parameters

• string season The season id from AsyncPvp.GetCurrentSeasonInfo.
• TypedCallback<object> callback the callback function to handle the returned session data.

Callback Parameters

• Object result

Example Usage

Demo map with source code: https://platform.wildsky.dev/arcade/game/775

DCEI.SetOnClickCallback(refresh_button, function()
    self:Refresh()
end)
session_info:SetCallbacks(function()
    DCEI.AsyncPvp.NewSession(season.id, function(result)
        session = result
        session_info:SetSessionInfo(session)
    end)
end, function()
    DCEI.AsyncPvp.FinishSession(session.id, {1, 1, 1, -1, 0}, function(result)
        session_info:ClearSessionInfo()
        self:Refresh()
    end)
end)
self:Refresh()

void AsyncPvp.NewSession(string season, int relativeRankMin, int relativeRankMax, TypedCallback<object> callback)

void AsyncPvp.NewSession(string season, int relativeRankMin, int relativeRankMax, TypedCallback<object> callback)

Description

Parameters

Callback Parameters

• Object result

Example Usage

void AsyncPvp.SwitchOpponent(string session, TypedCallback<object> callback)

void AsyncPvp.SwitchOpponent(string session, TypedCallback<object> callback)

Description

If the player doesn’t like the current selected opponent, the client can call this API to select a different opponent.

{
  opponent = {
    uuid = string, tag = string, name = string, elo = number, board = string
  }
}

Similar to NewSession, the “opponent” field may be nil if the server can’t find a match (e.g., the client has called this API many times and all available opponents have been skipped).

Parameters

• string session The session id.
• TypedCallback<object> callback the callback function to handle the returned session data.

Callback Parameters

• Object result

Example Usage

DCEI.AsyncPvp.SwitchOpponent(
    session_info.id,
    function(result)
        session_info.current_opponent = result.opponent
        controller:SetSessionInfo(session_info)
    end
)

void AsyncPvp.SwitchOpponent(string session, int relativeRankMin, int relativeRankMax, TypedCallback<object> callback)

void AsyncPvp.SwitchOpponent(string session, int relativeRankMin, int relativeRankMax, TypedCallback<object> callback)

Description

Parameters

Callback Parameters

• Object result

Example Usage

void AsyncPvp.FinishOpponent(string session, int result, string payload, TypedCallback<object> callback)

void AsyncPvp.FinishOpponent(string session, int result, string payload, TypedCallback<object> callback)

Description

Use this API to send the result of a match. This should only be called if the current opponent is not nil. The “result” parameter is a number. 1 = win, -1 = lose, 0 = other.

The server will return the following in the callback:

{
  next_opponent = {
    uuid = string, tag = string, name = string, elo = number, board = string
  }
}

If there are no more matches or no opponents can be found, "next_opponent" will be nil.

Parameters

• string session The session id.
• int result The result of the match. 1 = win, -1 = lose, 0 = other.
• string payload The payload data.
• TypedCallback<object> callback the callback function to handle the returned session data.

Callback Parameters

• Object result

Example Usage

DCEI.SetOnClickCallback(
    win_button,
    function()
        DCEI.AsyncPvp.FinishOpponent(
            session_info.id,
            1,
            "win",
            function(result)
                session_info.finished_opponents = session_info.finished_opponents + 1
                session_info.current_opponent = result.next_opponent
                session_info.elo = result.elo
                controller:SetSessionInfo(session_info)
            end
        )
    end
)

void AsyncPvp.UseBotOpponent(string session, AsyncPvpBot bot, TypedCallback<object> callback)

void AsyncPvp.UseBotOpponent(string session, AsyncPvpBot bot, TypedCallback<object> callback)

Description

If the server cannot find an opponent for the player, the client should generate a bot and use this API to send the bot info to the server. The “bot” parameter should be a Lua table in the following format:

{
   uuid = string, tag = string, name = string, elo = number, board = string
}

The “uuid” field must have the prefix “bot:” for the server to distinguish the generated bot from actual players.

Parameters

• string session The session id
• AsyncPvpBot bot The bot table of info: { uuid = string, tag = string, name = string, elo = number, board = string }
• TypedCallback<object> callback the callback function to handle the returned session data.

Callback Parameters

• Object result

Example Usage

DCEI.SetOnClickCallback(
    use_bot_button,
    function()
        local bot = {uuid = "bot:1234", tag = "bx", name = "bx", elo = 0, board = "bb", board_win_count = 0, board_lose_count = 0, board_time = os.time()}
        DCEI.AsyncPvp.UseBotOpponent(
            session_info.id,
            bot,
            function(result)
                if not result then
                    return
                end
                session_info.current_opponent = bot
                controller:SetSessionInfo(session_info)
            end
        )
    end
)

void AsyncPvp.FinishSession(string session, TypedCallback<object> callback)

void AsyncPvp.FinishSession(string session, TypedCallback<object> callback)

Description

This API should only be called when the season is still active.

Finish a session and apply elo rating changes. This can be called anytime as long as the session and season are both active. Usually you will call it after finishing 5 matches, but it can also be called sooner (e.g., when the user decide to quit the remaining matches).

The API will returned a Lua table with the updated elo for the current user: { elo = number }.

NOTE: if a session has timed out, it’s up to the client to report the result with FinishSession. The server doesn’t enforce any session timeout rules (except that when the season has finished).

Parameters

• string session The session id
• TypedCallback<object> callback the callback function to handle the returned session data.

Callback Parameters

• Object result

Example Usage

DCEI.AsyncPvp.FinishSession(session.id, function()
    session_info:ClearSessionInfo()
    self:Refresh()
end)

void AsyncPvp.GetLeaderBoard(string season, string type, TypedCallback<object> callback)

void AsyncPvp.GetLeaderBoard(string season, string type, TypedCallback<object> callback)

Description

Get the top 50 players of the season that belong to the same group as the current user. type can be either “season” or “today” to get the season leaderboard or daily leaderboard. Note that the daily leaderboard resets at the same time as the season start time (e.g., if each season starts at 7:00 AM, the daily leaderboard will reset 7:00 AM everyday).

The API returns the following format:

{
  players = {
    {uuid = string, tag = string, name = string, elo = number, board = string},
    {uuid = string, tag = string, name = string, elo = number, board = string},
    {uuid = string, tag = string, name = string, elo = number, board = string},
    ... up to 50 ...
  }
}

NOTE: order of players with the same elo is undefined.

Parameters

• string season the season id from AsyncPvp.GetCurrentSeasonInfo
• string type an be either “season” or “today” to get the season leaderboard or daily leaderboard
• TypedCallback<object> callback the callback function to handle the returned data

Callback Parameters

• Object result

Example Usage

Demo map with source code: https://platform.wildsky.dev/arcade/game/775

function controller:Refresh()
    DCEI.AsyncPvp.GetCurrentSeasonInfo(function(result)
        season = result
        season_info:SetSeasonInfo(season)
        DCEI.AsyncPvp.GetCurrentUserInfo(season.id, function(result)
            user_info:SetUserInfo(result)
            if result.board == nil or #result.board == 0 then
                DCEI.AsyncPvp.SetDefenseBoard(season.id, string.format("b%s", DCEI.GetUserTag()), function()
                    self:Refresh()
                end)
            else
                DCEI.AsyncPvp.GetLeaderBoard(season.id, "season", function(result)
                    season_leader_board:SetLeaderBoard("season", result.players)
                end)
                DCEI.AsyncPvp.GetLeaderBoard(season.id, "today", function(result)
                    daily_leader_board:SetLeaderBoard("today", result.players)
                end)
            end
        end)
        session_info:ClearSessionInfo()
    end)
end

void AsyncPvp.GetSurroundingPlayers(string season, TypedCallback<object> callback)

void AsyncPvp.GetSurroundingPlayers(string season, TypedCallback<object> callback)

Description

Get surrounding players from the leaderboard.

Parameters

• string season season index to get surrounding players for
• TypedCallback<object> callback lua function to handle the returned data

Callback Parameters

• Object result

Example Usage

local function GetPlayersCallback(result)
    for k, v in data do
        DCEI.LogMessage(k .. ": " .. tostring(v))
    end
end
DCEI.AsyncPvp.GetSurroundingPlayers("season_1", GetPlayersCallback)

void AsyncPvp.GetDailyRankHistory(string season, TypedCallback<object> callback)

void AsyncPvp.GetDailyRankHistory(string season, TypedCallback<object> callback)

Description

Retrieves the daily rank history for the season.

Parameters

• string season The season id from AsyncPvp.GetCurrentSeasonInfo
• TypedCallback<object> callback the callback function to handle the returned data

Callback Parameters

• Object result

Example Usage

Demo map with source code: https://platform.wildsky.dev/arcade/game/775

DCEI.AsyncPvp.GetCurrentSeasonInfo(function(result)
    season = result
    season_info:SetSeasonInfo(season)
    DCEI.AsyncPvp.GetCurrentUserInfo(season.id, function(result)
        user_info:SetUserInfo(result)
        if result.board == nil or #result.board == 0 then
            if season.status == 1 then
                DCEI.AsyncPvp.SetDefenseBoard(season.id, string.format("b%s", DCEI.GetUserTag()), function()
                    self:Refresh()
                end)
            end
        else
            DCEI.AsyncPvp.GetDailyRankHistory(season.id, function(result)
                daily_rank_history:SetDailyRankHistory(result.entries)
            end)
        end
    end)
    session_info:ClearSessionInfo()
end)

-- Daily Rank History
function controller:SetDailyRankHistory(entries)
    DCEI.SetListFrameItemCount(list, #entries)
    DCEI.SetListFrameItemDataCallback(list, function(item, index)
        local entry = entries[index]
        local text = DCEI.GetChildFrameById(item, "text")
        DCEI.SetTextFrameText(text, string.format("%s, %d, %f", os.date("%x %X", entry.day), entry.rank, entry.elo))
    end)
    DCEI.RefreshListFrameItems(list, 1, #entries)
end