looping.gg

Docs/MCP reference

rooms_plan

Read only

Work out the rooms a game needs from its shape before rooms_configure, instead of guessing.

POST/api/agent/rooms/plan

Behavior

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, 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.

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 is authoritative), room size, teams, tick rate and lobby flags, 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) or the large room tier, which is coming and not available yet. It changes nothing; the looping-multiplayer skill says how to find the shape.

Input parameters

nameOptional
string

the kind this shape is; unnamed, the default kind

  • Pattern: ^[a-z][a-z0-9-]{0,15}$
playersOptional
object

how 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
}
teamsOptional
object

teams 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_basedOptional
boolean
hidden_infoOptional
boolean

players hold what others must not see: hands, fog

competitiveOptional
boolean
rankedOptional
boolean
rewardedOptional
boolean

wins earn something: prizes, items, leaderboard rewards

tick_hintOptional
integer

simulation updates a second a real-time game needs

  • Minimum: 1
  • Maximum: 1000
state_size_hintOptional
integer

bytes of simulation state

  • Minimum: 0
  • Maximum: 1073741824
view_size_hintOptional
integer

bytes one player receives per update

  • Minimum: 0
  • Maximum: 1073741824
matchmakingOptional
boolean
partyOptional
boolean

friends queue together

privateOptional
boolean

invite-only rooms by code

lobbyOptional
boolean

rooms open in a lobby the host locks and starts

late_joinOptional
boolean
rejoinOptional
boolean
clientOptional
"js" | "unity"

the game calls the JavaScript SDK (default) or the Unity C# layer

kindsOptional
object[]

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"
      },
      "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"
      }
    },
    "required": [
      "name"
    ],
    "additionalProperties": false
  }
}

The descriptions above include conditional requirements. The full schema below shows structural validation; runtime checks also apply.

JSON Schema

Input schema · draft-7
{
  "$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"
    },
    "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"
    },
    "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"
          },
          "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"
          }
        },
        "required": [
          "name"
        ],
        "additionalProperties": false
      }
    }
  },
  "additionalProperties": false
}
Calling this tool

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.