Room Visibility & Access

Which rooms a player can discover, and which they can actually enter, are two different questions. Three flags answer them.

Matchmaking Properties

Three boolean flags control who can find and join a room: locked, private, and unlisted. They sound similar but behave differently on each join path:

• locked: no new clients can join, on any path. Set automatically when the room fills up (maxClients reached, releases itself when a seat frees), or explicitly via lock(). Reconnections still work: a reconnecting client returns to the seat it already owned.
• private: invite-only. Never matched by join()/joinOrCreate() and never shown in listings, but anyone holding the room ID can enter through joinById(). Use it for invite links and party codes. Set via setPrivate() or setMatchmaking({ private: true }).
• unlisted: hidden, but still matchmade. The room doesn’t show up in lobby/listing queries, yet join()/joinOrCreate() keep filling it normally. Use it to keep rooms out of your room browser without pulling them from matchmaking. Set via setMatchmaking({ unlisted: true }).

setMatchmaking(updates)

Updates multiple matchmaking/listing properties at once, with a single persist operation. This method is the recommended way to update room listing properties.

• metadata (optional): room metadata (replaces the existing value)
• private (optional): whether the room should be private
• locked (optional): whether the room should be locked
• maxClients (optional): maximum number of clients allowed
• unlisted (optional): whether the room should be hidden from listing queries

// Update multiple properties at once
await this.setMatchmaking({
    metadata: { difficulty: "hard", rating: 1500 },
    private: true,
    locked: true,
    maxClients: 10
});

You can also set individual properties:

• setPrivate(bool?): toggle private (defaults to true)
• setMetadata(meta): replace metadata
• lock() / unlock(): toggle locked
• this.maxClients = N: forwards to setMatchmaking({ maxClients: N })

Lock Room

Locking removes the room from matchmaking: join()/joinOrCreate() skip it, and joinById() rejects with a room "<roomId>" is locked error. No new clients can join until it’s unlocked.

this.lock();

The room also locks automatically when it reaches maxClients. The two differ in how they release: an automatic lock releases itself as soon as a seat frees up, while an explicit lock() is sticky. The room stays locked until you call unlock().

Unlock Room

Returns the room to the pool of available rooms. New clients can join again, as long as maxClients hasn’t been reached.

this.unlock();