Loading Looping…
Skip to content
looping.gg
DiscoverMarketsProfile
Buy GG token
Loading…
looping.gg
DiscoverMarketsDocsCreateBuy GG tokenProfileTerms
DiscoverCreateMarketsProfile
Developer docs

Build on Looping

Getting startedConnect an agentUpload and publish

Game integration

Game SDKMultiplayer roomsPlayers and savesIn-game purchases

Reference

MCP tool reference
Manage agent access Create a project

Docs/MCP reference

leaderboards_configure

Write

Declare the game's leaderboards.

POST/api/agent/leaderboards/configure

Behavior#

Declare the game's leaderboards. Read the looping-leaderboards skill first: whether the game should have a board at all, and which settings fit it. Give only the boards to change; null removes one and clears its entries. Each board: title; order high (more is better, the default) or low (times, strokes); keep best (each player's best, the default), latest (the player's current value: a level, a rating) or total (the sum of every post: lifetime wins, kills, gold earned); period all (the default), day, week or month (resets at UTC midnight; the previous period stays readable); trust any (the default: player-reported posts, marked as such) or verified (only an authoritative room's rules.js result and replay-verified rounds post to it); split, a key such as "track" or "level" for one board per value (up to 200 values), with splits listing its values ("monaco", "spa"; added to those it has): a post or a round from the game names only a listed value, while an authoritative room's result may open a new one; format number, time_ms or points (how the game page displays values); shown false keeps it off the game page (the game still reads it).

order, keep, period, trust and split are fixed once a board exists. primary names the board an older SDK's finishRound(score) posts to and leaderboard() reads; a lone board is primary by itself, and with several, name one whenever none is. Up to 16 boards; names are 1-32 lowercase letters, digits and dashes starting with a letter. Boards are free. Once a game has any board, only what it posts to a board is stored: a match stores only what its rules.js result() returns in boards, so change rules.js in the same build.

Propose the boards to the creator in one yes-or-no sentence before calling this.

Input parameters#

boardsRequired
object
Nested schema
{
  "type": "object",
  "propertyNames": {
    "type": "string",
    "pattern": "^[a-z][a-z0-9-]{0,31}$"
  },
  "additionalProperties": {
    "anyOf": [
      {
        "type": "object",
        "properties": {
          "title": {
            "type": "string",
            "minLength": 1,
            "maxLength": 40
          },
          "order": {
            "type": "string",
            "enum": [
              "high",
              "low"
            ]
          },
          "keep": {
            "type": "string",
            "enum": [
              "best",
              "latest",
              "total"
            ]
          },
          "period": {
            "type": "string",
            "enum": [
              "all",
              "day",
              "week",
              "month"
            ]
          },
          "trust": {
            "type": "string",
            "enum": [
              "any",
              "verified"
            ]
          },
          "split": {
            "anyOf": [
              {
                "type": "string",
                "pattern": "^[a-z][a-z0-9_-]{0,31}$"
              },
              {
                "type": "null"
              }
            ]
          },
          "splits": {
            "maxItems": 200,
            "type": "array",
            "items": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,39}$"
            }
          },
          "format": {
            "type": "string",
            "enum": [
              "number",
              "time_ms",
              "points"
            ]
          },
          "shown": {
            "type": "boolean"
          }
        },
        "additionalProperties": false
      },
      {
        "type": "null"
      }
    ]
  }
}
primaryOptional
string
  • Pattern: ^[a-z][a-z0-9-]{0,31}$

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": {
    "boards": {
      "type": "object",
      "propertyNames": {
        "type": "string",
        "pattern": "^[a-z][a-z0-9-]{0,31}$"
      },
      "additionalProperties": {
        "anyOf": [
          {
            "type": "object",
            "properties": {
              "title": {
                "type": "string",
                "minLength": 1,
                "maxLength": 40
              },
              "order": {
                "type": "string",
                "enum": [
                  "high",
                  "low"
                ]
              },
              "keep": {
                "type": "string",
                "enum": [
                  "best",
                  "latest",
                  "total"
                ]
              },
              "period": {
                "type": "string",
                "enum": [
                  "all",
                  "day",
                  "week",
                  "month"
                ]
              },
              "trust": {
                "type": "string",
                "enum": [
                  "any",
                  "verified"
                ]
              },
              "split": {
                "anyOf": [
                  {
                    "type": "string",
                    "pattern": "^[a-z][a-z0-9_-]{0,31}$"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "splits": {
                "maxItems": 200,
                "type": "array",
                "items": {
                  "type": "string",
                  "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,39}$"
                }
              },
              "format": {
                "type": "string",
                "enum": [
                  "number",
                  "time_ms",
                  "points"
                ]
              },
              "shown": {
                "type": "boolean"
              }
            },
            "additionalProperties": false
          },
          {
            "type": "null"
          }
        ]
      }
    },
    "primary": {
      "type": "string",
      "pattern": "^[a-z][a-z0-9-]{0,31}$"
    }
  },
  "required": [
    "boards"
  ],
  "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.

ReferenceBrowse all toolsSetupConnect an agent

Other tools

BehaviorInput parametersJSON Schema