Installation

The Roblox SDK is a server-realm Luau package named floque/matchmaking. The BirdHouse product name and the existing package identifier refer to the same integration.

Availability. Matchmaking is in early access. This guide is written for SDK version 0.4.0. Installation requires access to a private registry and a released package, and running the SDK requires a service endpoint; these are arranged with the team. This page does not confirm that a package is published or a service is hosted. Apply for early access.

Package access

The package is distributed through a private Wally registry. You need registry access and a released package version before installation will succeed. This guide is written for version 0.4.0; it does not assert that 0.4.0 has been published to the registry.

Your access instructions provide the registry URL and available package version. Contact support@birdhouse.tech if you need help with those instructions.

Add the dependency

Merge these entries into your project’s existing wally.toml:

[package]
registry = "<registry-url-provided-with-access>"

[place]
shared-packages = "game.ReplicatedStorage.Packages"
server-packages = "game.ServerScriptService.ServerPackages"

[server-dependencies]
Matchmaking = "floque/matchmaking@0.4.0"

Replace the registry placeholder with the URL provided with your access, and confirm that the package version is available. Keep the rest of your package metadata and dependencies. Then install:

wally install

Map the generated packages

Merge both generated directories into your Rojo project’s tree:

{
  "ReplicatedStorage": {
    "Packages": {
      "$path": "Packages"
    }
  },
  "ServerScriptService": {
    "ServerPackages": {
      "$path": "ServerPackages"
    }
  }
}

The client runs on the server. Require it from ServerScriptService.ServerPackages, not from a LocalScript.

Enable HTTP requests

In Roblox Studio, open File → Experience Settings → Security and enable Allow HTTP Requests. Supply the service base URL for your deployment and an environment allowed by that service.

local ServerScriptService = game:GetService("ServerScriptService")
local MatchmakingClient = require(ServerScriptService.ServerPackages.Matchmaking)

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

Access-token authentication is unavailable in the current contract. The SDK does not accept API keys or personal access tokens.

Verify your setup

Create two compatible solo sessions using the quickstart. Confirm that they reach matching, receive a match, and stop producing heartbeat actions once terminal.

If installation fails, check registry access and the released version first. If requests fail, check that HTTP requests are enabled, the URL points to your matchmaking service endpoint, and the environment is allowed. See errors and recovery for runtime behavior.

Upgrading an existing integration

SDK 0.4.0 requires environment in every client configuration. The service and game servers need a coordinated upgrade so that all workers enforce environment isolation. Follow the migration guide before changing a production integration.