PlayerRole System - SuperiorSkyblock2

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.

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

​Understanding Player Roles

​Getting Player Roles

​Role Properties

​Role Comparison

​Role Position Checks

​Role Navigation

​Common Role Patterns

​Checking Authority

​Promoting a Player

​Demoting a Player

​Checking for Leader

​Filtering by Role Level

​Special Roles

​Guest Role

​Coop Role

​Role Configuration

​Role Permissions

​Static Utility Methods

​Best Practices

​1. Always Check for Null

​2. Use Role Comparison for Authority

​3. Check Ladder Status for Promotions

​4. Handle Special Roles Appropriately

​5. Use Display Names for User-Facing Text

​Related Classes

​Source Reference

Understanding Player Roles

Getting Player Roles

Role Properties

Role Comparison

Role Position Checks

Role Navigation

Common Role Patterns

Checking Authority

Promoting a Player

Demoting a Player

Checking for Leader

Filtering by Role Level

Special Roles

Guest Role

Coop Role

Role Configuration

Role Permissions

Static Utility Methods

Best Practices

1. Always Check for Null

2. Use Role Comparison for Authority

3. Check Ladder Status for Promotions

4. Handle Special Roles Appropriately

5. Use Display Names for User-Facing Text

Related Classes

Source Reference