Releases and migration

This documentation is written for Roblox SDK version 0.4.0. The package name remains floque/matchmaking, and it is distributed through a private Wally registry.

Source changes become installable only after a package release. Registry publication and hosted deployment status are not established by this documentation. Confirm both before upgrading.

SDK 0.4.0: environments

Version 0.4.0 requires an environment when constructing a client:

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

The client stamps every new session with this canonical environment. Session-level overrides are rejected. The corresponding service enforces isolation outside the constraint tree, so relaxed rules cannot mix environments.

Coordinated upgrade

1. Prepare the environment-aware API service, workers, monitoring, and game-server callers together. Configure the same environment allowlist across the service.
2. Pause new searches and drain or cancel old waiting work. Stop every old worker before relying on isolation.
3. Deploy the compatible service and update callers to SDK 0.4.0 with an explicit environment before resuming creates.
4. Keep existing ticket and match records available for their original retention windows. Legacy unlabeled work must stay separate from named environments.
5. Verify that same-environment tickets can match, cross-environment tickets cannot mix, and invalid or disallowed environments are rejected.

Do not mix old unrestricted workers with environment-aware workers. An older API service can discard the new field, while the new one rejects missing environments.

Legacy responses

Ticket.environment and Match.environment are optional because previously created results may omit them. The SDK also accepts the reserved _unlabeled value in responses. Neither missing values nor _unlabeled can be used as a new client environment.

Confirm and cancel continue to use only the ticket ID. Per-environment counters begin with this release and cannot reconstruct historical activity whose source records have expired.

Moving from SDK 0.2.0 to 0.3.0

The 0.3.0 lifecycle and retry changes remain part of the 0.4.0 contract:

• Client-generated ticket GUIDs require a compatible API service; deploy that support before upgrading the SDK.
• canceling is nonterminal. Use canceled for completed cancellation.
• TicketId is assigned immediately and no longer proves service acceptance.
• Invalid CreateSession input throws synchronously.
• Failed and retained Error report terminal failures.
• Destroy() ends active sessions with client_destroyed.
• Match delivery requires no acknowledgement. Retain the match for your game’s own handoff retries.

Deploy fixed matched-ticket retention with the service so completed results remain available for the ten-minute retry window. Review lifecycle and errors when updating existing handlers.

Integration references

Use these public references to review the documented integration contract:

Contract	Documentation
Package identity and version	Installation
SDK integration guide	Quickstart
Client options and data shapes	Roblox SDK
HTTP requests and responses	HTTP API
Matching behavior	Constraints

Verify the version deployed by your service operator instead of inferring release status from the documentation alone. Contact support@birdhouse.tech if you need help confirming compatibility or package access.