Roblox SDK

The server-side SDK manages ticket creation, batched heartbeats, cancellation, and reconciliation for Roblox experiences. Install it through Wally.

MatchmakingClient.new

local client = MatchmakingClient.new({
    baseUrl = "https://matchmaking.example.com",
    environment = "prod",
    heartbeatSeconds = 5,
})

Option	Type	Required	Meaning
baseUrl	string	Yes	HTTP(S) service base URL, without /api/progress, query, or fragment. Trailing slashes are removed.
environment	string	Yes	Valid environment key allowed by the service.
heartbeatSeconds	number	No	Default 5; must be finite, greater than zero, and less than 300.

Leave enough heartbeat margin for request latency and multiple batches. The SDK has no token or custom-header setting.

client:CreateSession

local session = client:CreateSession({
    players = {
        { id = "123456789" },
        { id = "987654321" },
    },
    meta = { mode = "squads", skill = 1200 },
    constraints = {
        type = "and",
        constraints = {
            { type = "playerCount", min = 4, max = 4 },
            { type = "fieldEqualsDeep", field = "mode" },
        },
    },
})

Option	Type	Required	Meaning
players	Player[]	Yes	A nonempty party with unique player IDs.
constraints	Constraint	No	The ticket’s matching rule tree.
meta	string-keyed table	No	JSON-compatible ticket metadata used by field rules.

A player has a string id and optional JSON-compatible meta. IDs must contain 1–32 UTF-16 code units; use tostring(player.UserId).

This method does not yield. It validates synchronously, copies options, and defers network work. Invalid input throws without creating a session. An environment field in session options is rejected; configure it on the client.

Session properties

Property	Type	Meaning
State	SessionState	Current local lifecycle state.
TicketId	string	GUID assigned before submission; retained for correlation.
Match	Match?	Retained successful outcome.
Error	SDKError?	Retained terminal failure.

Treat properties as read-only. TicketId does not prove service acceptance. SessionState is one of pending, matching, canceling, matched, canceled, and failed.

Events

session.Matched

Fires with a validated Match. The SDK stores session.Match before firing the event and sends terminal StateChanged afterward.

session.Matched:Connect(function(match)
    for _, ticket in match.tickets do
        for _, player in ticket.players do
            print("Matched player", player.id)
        end
    end
end)

session.Failed

Fires with the terminal SDKError, after it is stored in session.Error and before terminal StateChanged.

session.StateChanged

Fires on state transitions. The initial pending state is available as a property but is not emitted as an event. Terminal states are matched, canceled, and failed.

client.Error

Reports request and protocol errors. A retryable error can leave sessions active while the SDK reconciles or retries work. It is different from a session’s terminal Failed event.

Connect immediately after creation. Events do not replay for late listeners. Session signals are disconnected after terminal delivery, and callback completion is not awaited between events.

Cancellation and destruction

session:Cancel() requests cancellation and is idempotent. It may finish an unsent session locally or enter canceling while awaiting the service. A match can still win.

client:Destroy() abandons the client immediately. Active sessions end as failed with client_destroyed; new work stops. It is not a graceful cancel/drain operation. See ticket lifecycle.

Match and ticket types

export type Match = {
    id: string,
    environment: string?,
    tickets: { Ticket },
    meta: { [string]: any }?,
}

export type Ticket = {
    id: string,
    environment: string?,
    players: { Player },
    createdAt: number,
    status: number,
    matchId: string?,
    constraints: Constraint?,
    meta: { [string]: any }?,
    traceparent: string?,
}

createdAt is an epoch timestamp in milliseconds. Environments are optional in response types for legacy results. Use session lifecycle states for normal integration logic; raw ticket status values are described in the HTTP reference.

Exported types

The module exports Constraint, Player, Ticket, Match, CreateOptions, SessionState, Session, ClientConfig, MatchmakingClient, and SDKError.

SDKError contains code, message, retryable, optional statusCode, and optional details. Response details can include submitted data and are not automatically logged. See errors and recovery.