ShadowConfigDocs

XP & Ranks

Configure in-game rank progression curves, leaderstat integration, and automated Roblox Group role promotions.

Overview

The XP & Ranks system tracks player experience or leaderstats (such as Wins, Kills, or XP) in your Roblox game. As players accumulate points in-game, ShadowConfig evaluates rank thresholds and can automatically promote players to corresponding roles in your official Roblox Group.

How It Works

  1. Leaderstat Tracking — Set the target leaderstat name (e.g. Wins, XP, Level) that determines player rank.
  2. Rank Thresholds — Define rank names and required point thresholds (e.g. Member at 100 XP, Veteran at 500 XP).
  3. Roblox DataStore Storage — XP and ranks are stored directly in your game's own Roblox DataStore (ShadowConfig DataStore, key XPConfig) via Open Cloud.
  4. Roblox Group Auto-Promotion — When enabled, reaching a rank threshold calls the Roblox Open Cloud Groups API to assign the matching Roblox Group Role ID to the player in real-time.

Importing Ranks from Roblox Group

Instead of manually typing every rank and role ID, enter your Roblox Group ID in the XP & Ranks tab and click Import Ranks from Group. ShadowConfig will automatically fetch all roles in your group, sort them by rank precedence, and pre-fill an escalating XP progression curve.

Open Cloud API Requirements

For automated group promotion to work, your Open Cloud API Key (configured in Settings) must have:

  • datastore:read & datastore:write scopes for your game Universe.
  • groups:write scope for your Roblox Group ID.
  • The owner of the API key must hold the Manage Lower Ranks permission in the group.

Related Links

For Discord role synchronization based on Roblox ranks, check out the Rank Sync Documentation.