rooms_plan
Read onlyWork out the rooms a game needs from its shape before rooms_configure, instead of guessing.
/api/agent/rooms/planBehavior
Work out the rooms a game needs from its shape before rooms_configure, instead of guessing. Describe one kind of room: players { min, max } (or teams { count, size }), turn_based, hidden_info, competitive, ranked or rewarded, untrusted_players (the creator wants it cheat-proof even with nothing at stake), tick_hint (updates a second), state_size_hint and view_size_hint (bytes: the simulation's state, and what one player receives per update), and how players meet: matchmaking, party, private, lobby, late_join, rejoin, backfill (only the ways given are used: a private-only game gets no matchmaking).
name makes it a named kind (unnamed, it is the game's default kind); kinds adds up to 8 more for a game that runs several (a relay overworld and authoritative battles, casual and ranked); client unity answers for the Unity C# layer. Returns each kind's mode by the platform's rule (relay only where nobody gains by cheating: co-op, players against the environment or the computer, casual play; anything competitive, ranked or rewarded, cheat-proof by request, or teams fighting each other is authoritative), room size, teams, tick rate, lobby flags and backfill, how players meet with the matchmaking size and partial start, the limits it was checked against, what rules.js must do and the SDK calls; then fits, a ready-to-send rooms_configure payload, the choices to confirm with the creator (proposed) and next steps.
A shape that does not fit gets fits false, the reason and the way forward: capped worlds of at most 32 players (like RuneScape's) instead of one MMO-sized space, competitive matches of at most 16, and for state or views over an authoritative room's limits, compaction and areas of interest in rules.js (a 4- or 8-seat RTS fits today that way; skill_read looping-large-games). The large room tier is parked: rooms_plan never proposes it.
It changes nothing; the looping-multiplayer skill says how to find the shape.
Input parameters
nameOptionalstringthe kind this shape is; unnamed, the default kind
- Pattern: ^[a-z][a-z0-9-]{0,15}$
playersOptionalobjecthow many players share one room: a match, a table, a world
Nested schema
{
"description": "how many players share one room: a match, a table, a world",
"type": "object",
"properties": {
"min": {
"type": "integer",
"minimum": 1,
"maximum": 1000000
},
"max": {
"type": "integer",
"minimum": 1,
"maximum": 1000000
}
},
"required": [
"max"
],
"additionalProperties": false
}teamsOptionalobjectteams per room and players per team, e.g. 8v8 is { count: 2, size: 8 }
Nested schema
{
"description": "teams per room and players per team, e.g. 8v8 is { count: 2, size: 8 }",
"type": "object",
"properties": {
"count": {
"type": "integer",
"minimum": 2,
"maximum": 64
},
"size": {
"type": "integer",
"minimum": 1,
"maximum": 100000
}
},
"required": [
"count",
"size"
],
"additionalProperties": false
}turn_basedOptionalbooleanhidden_infoOptionalbooleanplayers hold what others must not see: hands, fog
competitiveOptionalbooleanrankedOptionalbooleanrewardedOptionalbooleanwins earn something: prizes, items, leaderboard rewards
untrusted_playersOptionalbooleanplayers must not be able to cheat each other, even with no scores or prizes ("it shouldn't be hackable")
tick_hintOptionalintegersimulation updates a second a real-time game needs
- Minimum: 1
- Maximum: 1000
state_size_hintOptionalintegerbytes of simulation state
- Minimum: 0
- Maximum: 1073741824
view_size_hintOptionalintegerbytes one player receives per update
- Minimum: 0
- Maximum: 1073741824
matchmakingOptionalbooleanpartyOptionalbooleanfriends queue together
privateOptionalbooleaninvite-only rooms by code
lobbyOptionalbooleanrooms open in a lobby the host locks and starts
late_joinOptionalbooleanrejoinOptionalbooleanbackfillOptionalbooleanmatchmaking fills a running match when a player leaves (unset: proposed for co-op, arenas and team matches, not for duels or turn-based play)
persistOptional"named" | "owner" | "region"what players build stays after the room empties: a shared server (named), each player's own base (owner), or a big map split into regions (region)
clientOptional"js" | "unity"the game calls the JavaScript SDK (default) or the Unity C# layer
kindsOptionalobject[]more kinds of room the same game runs
- Max. items: 8
Nested schema
{
"description": "more kinds of room the same game runs",
"maxItems": 8,
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"pattern": "^[a-z][a-z0-9-]{0,15}$"
},
"players": {
"description": "how many players share one room: a match, a table, a world",
"type": "object",
"properties": {
"min": {
"type": "integer",
"minimum": 1,
"maximum": 1000000
},
"max": {
"type": "integer",
"minimum": 1,
"maximum": 1000000
}
},
"required": [
"max"
],
"additionalProperties": false
},
"teams": {
"description": "teams per room and players per team, e.g. 8v8 is { count: 2, size: 8 }",
"type": "object",
"properties": {
"count": {
"type": "integer",
"minimum": 2,
"maximum": 64
},
"size": {
"type": "integer",
"minimum": 1,
"maximum": 100000
}
},
"required": [
"count",
"size"
],
"additionalProperties": false
},
"turn_based": {
"type": "boolean"
},
"hidden_info": {
"description": "players hold what others must not see: hands, fog",
"type": "boolean"
},
"competitive": {
"type": "boolean"
},
"ranked": {
"type": "boolean"
},
"rewarded": {
"description": "wins earn something: prizes, items, leaderboard rewards",
"type": "boolean"
},
"untrusted_players": {
"description": "players must not be able to cheat each other, even with no scores or prizes (\"it shouldn't be hackable\")",
"type": "boolean"
},
"tick_hint": {
"description": "simulation updates a second a real-time game needs",
"type": "integer",
"minimum": 1,
"maximum": 1000
},
"state_size_hint": {
"description": "bytes of simulation state",
"type": "integer",
"minimum": 0,
"maximum": 1073741824
},
"view_size_hint": {
"description": "bytes one player receives per update",
"type": "integer",
"minimum": 0,
"maximum": 1073741824
},
"matchmaking": {
"type": "boolean"
},
"party": {
"description": "friends queue together",
"type": "boolean"
},
"private": {
"description": "invite-only rooms by code",
"type": "boolean"
},
"lobby": {
"description": "rooms open in a lobby the host locks and starts",
"type": "boolean"
},
"late_join": {
"type": "boolean"
},
"rejoin": {
"type": "boolean"
},
"backfill": {
"description": "matchmaking fills a running match when a player leaves (unset: proposed for co-op, arenas and team matches, not for duels or turn-based play)",
"type": "boolean"
},
"persist": {
"description": "what players build stays after the room empties: a shared server (named), each player's own base (owner), or a big map split into regions (region)",
"type": "string",
"enum": [
"named",
"owner",
"region"
]
}
},
"required": [
"name"
],
"additionalProperties": false
}
}The descriptions above include conditional requirements. The full schema below shows structural validation; runtime checks also apply.
JSON Schema
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"name": {
"description": "the kind this shape is; unnamed, the default kind",
"type": "string",
"pattern": "^[a-z][a-z0-9-]{0,15}$"
},
"players": {
"description": "how many players share one room: a match, a table, a world",
"type": "object",
"properties": {
"min": {
"type": "integer",
"minimum": 1,
"maximum": 1000000
},
"max": {
"type": "integer",
"minimum": 1,
"maximum": 1000000
}
},
"required": [
"max"
],
"additionalProperties": false
},
"teams": {
"description": "teams per room and players per team, e.g. 8v8 is { count: 2, size: 8 }",
"type": "object",
"properties": {
"count": {
"type": "integer",
"minimum": 2,
"maximum": 64
},
"size": {
"type": "integer",
"minimum": 1,
"maximum": 100000
}
},
"required": [
"count",
"size"
],
"additionalProperties": false
},
"turn_based": {
"type": "boolean"
},
"hidden_info": {
"description": "players hold what others must not see: hands, fog",
"type": "boolean"
},
"competitive": {
"type": "boolean"
},
"ranked": {
"type": "boolean"
},
"rewarded": {
"description": "wins earn something: prizes, items, leaderboard rewards",
"type": "boolean"
},
"untrusted_players": {
"description": "players must not be able to cheat each other, even with no scores or prizes (\"it shouldn't be hackable\")",
"type": "boolean"
},
"tick_hint": {
"description": "simulation updates a second a real-time game needs",
"type": "integer",
"minimum": 1,
"maximum": 1000
},
"state_size_hint": {
"description": "bytes of simulation state",
"type": "integer",
"minimum": 0,
"maximum": 1073741824
},
"view_size_hint": {
"description": "bytes one player receives per update",
"type": "integer",
"minimum": 0,
"maximum": 1073741824
},
"matchmaking": {
"type": "boolean"
},
"party": {
"description": "friends queue together",
"type": "boolean"
},
"private": {
"description": "invite-only rooms by code",
"type": "boolean"
},
"lobby": {
"description": "rooms open in a lobby the host locks and starts",
"type": "boolean"
},
"late_join": {
"type": "boolean"
},
"rejoin": {
"type": "boolean"
},
"backfill": {
"description": "matchmaking fills a running match when a player leaves (unset: proposed for co-op, arenas and team matches, not for duels or turn-based play)",
"type": "boolean"
},
"persist": {
"description": "what players build stays after the room empties: a shared server (named), each player's own base (owner), or a big map split into regions (region)",
"type": "string",
"enum": [
"named",
"owner",
"region"
]
},
"client": {
"description": "the game calls the JavaScript SDK (default) or the Unity C# layer",
"type": "string",
"enum": [
"js",
"unity"
]
},
"kinds": {
"description": "more kinds of room the same game runs",
"maxItems": 8,
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"pattern": "^[a-z][a-z0-9-]{0,15}$"
},
"players": {
"description": "how many players share one room: a match, a table, a world",
"type": "object",
"properties": {
"min": {
"type": "integer",
"minimum": 1,
"maximum": 1000000
},
"max": {
"type": "integer",
"minimum": 1,
"maximum": 1000000
}
},
"required": [
"max"
],
"additionalProperties": false
},
"teams": {
"description": "teams per room and players per team, e.g. 8v8 is { count: 2, size: 8 }",
"type": "object",
"properties": {
"count": {
"type": "integer",
"minimum": 2,
"maximum": 64
},
"size": {
"type": "integer",
"minimum": 1,
"maximum": 100000
}
},
"required": [
"count",
"size"
],
"additionalProperties": false
},
"turn_based": {
"type": "boolean"
},
"hidden_info": {
"description": "players hold what others must not see: hands, fog",
"type": "boolean"
},
"competitive": {
"type": "boolean"
},
"ranked": {
"type": "boolean"
},
"rewarded": {
"description": "wins earn something: prizes, items, leaderboard rewards",
"type": "boolean"
},
"untrusted_players": {
"description": "players must not be able to cheat each other, even with no scores or prizes (\"it shouldn't be hackable\")",
"type": "boolean"
},
"tick_hint": {
"description": "simulation updates a second a real-time game needs",
"type": "integer",
"minimum": 1,
"maximum": 1000
},
"state_size_hint": {
"description": "bytes of simulation state",
"type": "integer",
"minimum": 0,
"maximum": 1073741824
},
"view_size_hint": {
"description": "bytes one player receives per update",
"type": "integer",
"minimum": 0,
"maximum": 1073741824
},
"matchmaking": {
"type": "boolean"
},
"party": {
"description": "friends queue together",
"type": "boolean"
},
"private": {
"description": "invite-only rooms by code",
"type": "boolean"
},
"lobby": {
"description": "rooms open in a lobby the host locks and starts",
"type": "boolean"
},
"late_join": {
"type": "boolean"
},
"rejoin": {
"type": "boolean"
},
"backfill": {
"description": "matchmaking fills a running match when a player leaves (unset: proposed for co-op, arenas and team matches, not for duels or turn-based play)",
"type": "boolean"
},
"persist": {
"description": "what players build stays after the room empties: a shared server (named), each player's own base (owner), or a big map split into regions (region)",
"type": "string",
"enum": [
"named",
"owner",
"region"
]
}
},
"required": [
"name"
],
"additionalProperties": false
}
}
},
"additionalProperties": false
}Use its name in your connected MCP client. For the HTTP API, the route is relative to your Convex site URL and requires your agent key as a bearer token. Keep the key on the agent side, outside a game build.