Ranks

Ranks define who has access to Sphere and what they can do. Each rank lives inside the Ranks table in your Settings and is identified by its key. A player is assigned whichever rank they qualify for with the highest Priority. Only one rank is ever active per player at a time.

If a player qualifies for more than one rank at the same time, only the one with the highest Priority is applied.

---

Creating a Rank

Add a new key to the Ranks table. The key name becomes the rank’s identifier everywhere in Sphere, including in Inherits references and permission lookups.

["Moderator"] = {
    Priority = 1,
    Permissions = {"kick"},
    Members = {
        Users = {game.CreatorId},
    },
    Prefix = {
        Text = "[MOD]",
        Color = Color3.fromRGB(255, 165, 0),
    },
}

Annotation

type Rank = {
    Priority: Number?,
    Permissions: {String},
    Members: {
        Group: {String}?,
        Users: {String | Number}?,
        Gamepass: {Number}?,
        Membership: {"Premium"}?,
        Asset: {Number}?,
        FriendsWith: {Number}?,
        Badge: {Number}?,
    }?,
    Inherits: String?,
    Prefix: {Text: string, Color: Color3}?,
}

Input

Priority Number • Required
When a player qualifies for more than one rank, the one with the highest value wins.

Permissions Table • Required
An array of permission strings granted to this rank. See Permissions.

Members Table • Required
A dictionary of membership rules. See Members.

Inherits String
The name of another rank to inherit permissions from. Members are never inherited, only permissions. Omit when Permissions = {"*"} — the wildcard already covers all permissions unconditionally.

Prefix Table
The chat tag shown next to the player’s name. See Prefix.

---

Members

Members is a dictionary of membership rules. Each key is a member type and its value is the list of entries. A player qualifies for the rank if they satisfy any key in the table.

A player only needs to satisfy one of them to qualify.

Users

Matches players by UserId, username, or special values. Mix and match any of these inside the same list.

Users = {2, "Roblox", game.CreatorId, "@Everyone"}

Input

UserId Number
The most reliable way to target a specific player.

Username String
Matches by username. Prefer UserId where possible.

game.CreatorId Special
Resolves to the UserId of the game creator at runtime.

game.PrivateServerOwnerId Special
Resolves to the UserId of the private server owner at runtime.

“@Everyone” Special
Every player who joins the game automatically qualifies.

Group

Matches players based on their rank inside a Roblox group. Each entry is a string in the format "GroupId:Operator+RankId".

Group = {"123456789:>=1"}

Input

GroupId Number • Required
The Roblox group ID to check.

Operator String • Required
How to compare the player’s rank. Accepted values: >=, <=, ==, >, <.

RankId Number • Required
The rank value to compare the player’s group rank against.

Gamepass

Matches players who own any of the listed gamepass IDs.

Gamepass = {123456789}

Input

Gamepass IDs {Number} • Required
A list of gamepass IDs. The player qualifies if they own any one of them.

Membership

Matches players with an active Roblox Premium subscription. Currently only "Premium" is a valid value.

Membership = {"Premium"}

Asset

Matches players who own any of the listed asset IDs.

Asset = {123456789}

Asset ownership checks are slow. Use them sparingly and avoid combining multiple Asset rules in the same rank.

Input

Asset IDs {Number} • Required
A list of asset IDs. The player qualifies if they own any one of them.

FriendsWith

Matches players who are friends with any of the listed UserIds.

FriendsWith = {123456789}

Input

UserIds {Number} • Required
A list of UserIds. The player qualifies if they are friends with any one of them.

Badge

Matches players who own any of the listed badge IDs.

Badge = {123456789}

Badge checks are slow. Use them sparingly and avoid combining multiple Badge rules in the same rank.

Input

Badge IDs {Number} • Required
A list of badge IDs. The player qualifies if they own any one of them.

---

Permissions

Permissions is an array of strings. Each string is a permission name granted to players holding this rank. Names are matched exactly against what is passed to CreateSection and CreateCommand.

Permission names are case sensitive. Kick and kick are two different permissions.

Use "*" to grant all permissions unconditionally. Ranks using "*" should omit Inherits, as the wildcard already covers everything.

Permissions = {"kick", "ban", "announce"}

Inheritance

When Inherits is set, the rank receives all permissions from the named rank on top of its own. Only permissions are inherited, never Members. The chain resolves recursively across as many levels as needed.

Show Example

--// [[ MODERATION ]]
["Moderator"] = {
    Priority = 1,
    Permissions = {"kick"},
    Members = {
        Users = {game.CreatorId},
    },
},

--// [[ ADMINISTRATION ]]
["Admin"] = {
    Priority = 2,
    Inherits = "Moderator",
    Permissions = {"ban"},
    Members = {
        Users = {game.CreatorId},
    },
},

--// [[ OWNERSHIP ]]
["Owner"] = {
    Priority = 3,
    Permissions = {"*"},
    Members = {
        Users = {game.CreatorId},
    },
},

---

Prefix

Prefix is an optional table that controls the chat tag shown next to the player’s name. If omitted, no tag is shown.

Prefix = {
    Text = "[MOD]",
    Color = Color3.fromRGB(255, 165, 0),
}

Input

Text String • Required
The tag displayed next to the player’s name in chat. Supports rich text tags such as <b>.

Color Color3
The color of the tag. Omit to use the default chat color.