Matchmaking environments: dev, staging, and prod

Every new ticket has a canonical environment. Tickets from different environments never match, even when they have identical metadata, no constraints, or fully relaxed timeout rules.

Configure the client

Set the environment once when creating a Roblox client:

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

The SDK copies this setting and puts it in every create action’s options.environment. A session cannot override it. Use a separate client for a different environment.

Environment names

Keys contain 1–32 lowercase ASCII letters, digits, underscores, or hyphens and must begin with a letter. Examples include dev, staging, prod, and playtest-2.

The SDK validates the format. The service separately validates its configured allowlist. The service’s default list is dev, staging, and prod; a deployment can configure 1–20 distinct keys through MATCHMAKING_ENVIRONMENTS.

An environment with a valid name can still be rejected when that deployment does not allow it.

Direct HTTP requests

The environment belongs at the top level of create options:

{
  "actions": [
    {
      "type": "create",
      "options": {
        "environment": "dev",
        "players": [{ "id": "123456789" }],
        "meta": { "mode": "duel" },
        "constraints": { "type": "playerCount", "min": 2, "max": 2 }
      }
    }
  ]
}

meta.environment is ordinary metadata and cannot select or override the canonical environment. Confirm and cancel actions continue to use the ticket ID without an environment argument.

Isolation and grouping

Environment isolation is an unconditional service boundary. Mode, region, role, and other metadata need their own matching rules when they must restrict a match.

An environment is not an authentication credential or an authorization boundary. Access-token authentication is unavailable in this phase; configure access to your deployment separately.

Existing tickets and upgrades

Legacy tickets without an environment remain in a reserved _unlabeled group. They are not assigned to prod. The SDK accepts missing environments and _unlabeled in legacy responses, but neither is a valid client setting for creating new tickets.

The environment-aware API service, workers, monitoring, and SDK callers require a coordinated rollout. All old workers must stop before relying on isolation. Keep legacy ticket and match records available for their original retry window. See release notes and migration.