Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/BG-Software-LLC/SuperiorSkyblock2/llms.txt

Use this file to discover all available pages before exploring further.

The PlayerRole interface represents a role that players can have within an island. Roles form a hierarchical ladder system that determines permissions and privileges within the island.

​
Understanding Player Roles

Player roles are organized in a weighted ladder system where:
  • Higher weight = higher position in the hierarchy
  • Weight 0 is typically the lowest member role
  • Negative weights are reserved for special roles (guest, coop)
  • The highest weight role is usually the island leader

​
Getting Player Roles

import com.bgsoftware.superiorskyblock.api.island.PlayerRole;
import com.bgsoftware.superiorskyblock.api.wrappers.SuperiorPlayer;

// Get the default role (typically the first member role)
PlayerRole defaultRole = PlayerRole.defaultRole();

// Get the last role (typically the leader role)
PlayerRole lastRole = PlayerRole.lastRole();

// Get special roles
PlayerRole guestRole = PlayerRole.guestRole();
PlayerRole coopRole = PlayerRole.coopRole();

// Get role by weight
PlayerRole role = PlayerRole.of(0);  // Get role with weight 0

// Get role by ID
PlayerRole role = PlayerRole.fromId(1);

// Get role by name
PlayerRole role = PlayerRole.of("member");

// Get a player's role
SuperiorPlayer player = ...;
PlayerRole playerRole = player.getPlayerRole();

​
Role Properties

​
getId
int
Get the unique ID of the role.
int id = role.getId();
Each role has a unique ID used for internal storage and identification.
​
getName
String
Get the internal name of the role.
String name = role.getName();
// Returns: "member", "moderator", "admin", etc.
This is the name used in configuration files and commands.
​
getDisplayName
String
Get the display name of the role shown in chat, placeholders, and UI.
String displayName = role.getDisplayName();
// Returns: "Member", "Moderator", "Admin", etc.
This is the user-facing name that appears in messages and menus.
​
getWeight
int
Get the weight of the role in the ladder hierarchy.
int weight = role.getWeight();
The weight determines the role’s position in the hierarchy:
  • Higher weight = higher rank
  • Weight 0 is typically the base member role
  • Negative weights are for special non-ladder roles

​
Role Comparison

​
isHigherThan
boolean
Check whether this role is higher than another role in the hierarchy.
PlayerRole memberRole = PlayerRole.of("member");
PlayerRole adminRole = PlayerRole.of("admin");

if (adminRole.isHigherThan(memberRole)) {
    // Admin role has more authority
}
​
role
PlayerRole
required
The role to compare against
​
isLessThan
boolean
Check whether this role is less than another role in the hierarchy.
PlayerRole memberRole = PlayerRole.of("member");
PlayerRole adminRole = PlayerRole.of("admin");

if (memberRole.isLessThan(adminRole)) {
    // Member role has less authority
}
​
role
PlayerRole
required
The role to compare against

​
Role Position Checks

​
isFirstRole
boolean
Check whether this role is the first (lowest) role in the ladder.
if (role.isFirstRole()) {
    // This is the base member role (weight 0)
}
Returns true for roles with weight 0.
​
isLastRole
boolean
Check whether this role is the last (highest) role in the ladder.
if (role.isLastRole()) {
    // This is the island leader role
}
Returns true for the role with the highest weight in the system.
​
isRoleLadder
boolean
Check whether the role is part of the role ladder system.
if (role.isRoleLadder()) {
    // This role is part of the promotion/demotion ladder
}
Returns true if:
  • The role has a weight >= 0, AND
  • The role has either a next or previous role
Special roles like guest and coop (negative weight) return false.

​
Role Navigation

​
getNextRole
PlayerRole
Get the next higher role in the ladder. Returns null if:
  • This is the last role in the ladder
  • The role is not in the ladder (negative weight)
PlayerRole memberRole = PlayerRole.of("member");
PlayerRole nextRole = memberRole.getNextRole();

if (nextRole != null) {
    // Player can be promoted to this role
    player.setPlayerRole(nextRole);
}
This is useful for implementing promotion systems.
​
getPreviousRole
PlayerRole
Get the previous lower role in the ladder. Returns null if:
  • This is the first role in the ladder
  • The role is not in the ladder (negative weight)
PlayerRole adminRole = PlayerRole.of("admin");
PlayerRole previousRole = adminRole.getPreviousRole();

if (previousRole != null) {
    // Player can be demoted to this role
    player.setPlayerRole(previousRole);
}
This is useful for implementing demotion systems.

​
Common Role Patterns

​
Checking Authority

public boolean canManageMember(SuperiorPlayer manager, SuperiorPlayer target) {
    PlayerRole managerRole = manager.getPlayerRole();
    PlayerRole targetRole = target.getPlayerRole();
    
    // Manager must have higher role than target
    return managerRole.isHigherThan(targetRole);
}

​
Promoting a Player

public void promotePlayer(SuperiorPlayer player) {
    PlayerRole currentRole = player.getPlayerRole();
    PlayerRole nextRole = currentRole.getNextRole();
    
    if (nextRole != null) {
        player.setPlayerRole(nextRole);
        player.runIfOnline(p -> {
            p.sendMessage("You've been promoted to " + nextRole.getDisplayName());
        });
    } else {
        // Already at max role
    }
}

​
Demoting a Player

public void demotePlayer(SuperiorPlayer player) {
    PlayerRole currentRole = player.getPlayerRole();
    PlayerRole previousRole = currentRole.getPreviousRole();
    
    if (previousRole != null) {
        player.setPlayerRole(previousRole);
        player.runIfOnline(p -> {
            p.sendMessage("You've been demoted to " + previousRole.getDisplayName());
        });
    } else {
        // Already at lowest role
    }
}

​
Checking for Leader

public boolean isIslandLeader(SuperiorPlayer player) {
    return player.getPlayerRole().isLastRole();
}

​
Filtering by Role Level

public List<SuperiorPlayer> getModeratorsAndAbove(Island island) {
    PlayerRole moderatorRole = PlayerRole.of("moderator");
    
    return island.getIslandMembers(true).stream()
        .filter(member -> {
            PlayerRole role = member.getPlayerRole();
            return role.equals(moderatorRole) || role.isHigherThan(moderatorRole);
        })
        .collect(Collectors.toList());
}

​
Special Roles

​
Guest Role

The guest role is assigned to visitors who enter an island without being a member or coop. 
PlayerRole guestRole = PlayerRole.guestRole();

// Guest role characteristics:
// - Negative weight (not in ladder)
// - isRoleLadder() returns false
// - Limited permissions based on island settings

​
Coop Role

The coop role is assigned to players who have been added as cooperators to an island. 
PlayerRole coopRole = PlayerRole.coopRole();

// Coop role characteristics:
// - Negative weight (not in ladder)
// - isRoleLadder() returns false
// - More permissions than guests
// - Not a permanent member

​
Role Configuration

Roles are typically configured in the roles.yml file: 
roles:
  - name: member
    id: 0
    weight: 0
    displayName: "Member"
    permissions:
      - BREAK
      - PLACE
      
  - name: moderator
    id: 1
    weight: 1
    displayName: "Moderator"
    permissions:
      - BREAK
      - PLACE
      - INVITE_MEMBER
      - KICK_MEMBER
      
  - name: admin
    id: 2
    weight: 2
    displayName: "Admin"
    permissions:
      - BREAK
      - PLACE
      - INVITE_MEMBER
      - KICK_MEMBER
      - SET_ROLE
      - CHANGE_SETTINGS
      
  - name: leader
    id: 3
    weight: 3
    displayName: "Leader"
    permissions:
      - ALL

​
Role Permissions

Each role has associated default permissions that determine what island privileges members with that role have. These permissions are inherited from lower roles and can be customized per island. 
// Check if a player has permission for an action
Island island = player.getIsland();
boolean canBreak = player.hasPermission(IslandPrivilege.BREAK);

// This checks:
// 1. The player's role on the island
// 2. The default permissions for that role
// 3. Any custom permissions set for that specific island

​
Static Utility Methods

The implementation provides several utility methods for working with roles: 
// Get all role names as a comma-separated string
String allRoles = SPlayerRole.getAllRoleNames();
// Returns: "guest, coop, member, moderator, admin, leader"

// Get only ladder role names
String ladderRoles = SPlayerRole.getRolesLadderNames();
// Returns: "member, moderator, admin, leader"

// Get role names valid for limit checking
String limitRoles = SPlayerRole.getRoleLimitsNames();
// Returns roles that can be used in role-based limits

// Refresh cached role name lists (call after role config changes)
SPlayerRole.refreshRoles();

​
Best Practices

​
1. Always Check for Null

PlayerRole nextRole = currentRole.getNextRole();
if (nextRole != null) {
    // Safe to use nextRole
}

​
2. Use Role Comparison for Authority

// Good
if (managerRole.isHigherThan(targetRole)) {
    // Can manage
}

// Avoid direct weight comparison
if (managerRole.getWeight() > targetRole.getWeight()) {
    // This works but less semantic
}

​
3. Check Ladder Status for Promotions

if (role.isRoleLadder() && !role.isLastRole()) {
    // Can be promoted
    PlayerRole nextRole = role.getNextRole();
    player.setPlayerRole(nextRole);
}

​
4. Handle Special Roles Appropriately

PlayerRole role = player.getPlayerRole();

if (role.equals(PlayerRole.guestRole())) {
    // Handle visitor
} else if (role.equals(PlayerRole.coopRole())) {
    // Handle coop member
} else if (role.isRoleLadder()) {
    // Handle regular member
}

​
5. Use Display Names for User-Facing Text

// Good - user-friendly
player.sendMessage("Your role: " + role.getDisplayName());

// Avoid - internal name
player.sendMessage("Your role: " + role.getName());
  • SuperiorPlayer - See SuperiorPlayer Interface
  • IslandPrivilege - Permissions associated with roles
  • RolePrivilegeNode - Internal role permission implementation at /home/daytona/workspace/source/src/main/java/com/bgsoftware/superiorskyblock/island/role/SPlayerRole.java:8

​
Source Reference

The PlayerRole interface is located at:
  • API Interface: /home/daytona/workspace/source/API/src/main/java/com/bgsoftware/superiorskyblock/api/island/PlayerRole.java:1
  • Implementation: /home/daytona/workspace/source/src/main/java/com/bgsoftware/superiorskyblock/island/role/SPlayerRole.java:1

Build docs developers (and LLMs) love

Get started for freeTalk to us