Players

Player management, roles, and preferences in SuperiorSkyblock2

Overview

The SuperiorPlayer interface wraps Bukkit’s player system with island-specific functionality, tracking player roles, preferences, island membership, and mission progress.

SuperiorPlayer Basics

Getting a SuperiorPlayer

import com.bgsoftware.superiorskyblock.api.SuperiorSkyblockAPI;
import com.bgsoftware.superiorskyblock.api.wrappers.SuperiorPlayer;

Player bukkitPlayer = // ... get bukkit player
SuperiorPlayer superiorPlayer = SuperiorSkyblockAPI.getPlayer(bukkitPlayer);

// Or by UUID
UUID uuid = // ... player UUID
SuperiorPlayer superiorPlayer = SuperiorSkyblockAPI.getPlayer(uuid);

Core Properties

Identity

// Basic identity
UUID getUniqueId();
String getName();
String getTextureValue();

// Status tracking
long getLastTimeStatus();
void updateLastTimeStatus();

Island Membership

Island Association

Players can belong to an island and have relationships with multiple islands:

// Primary island
Island getIsland();
boolean hasIsland();
void setIsland(Island island); // Advanced usage only

// Island leader
SuperiorPlayer getIslandLeader();

// Co-op islands
List<Island> getCoopIslands();
void addCoop(Island island);
void removeCoop(Island island);

// Check location
boolean isInsideIsland(); // Inside their own island

A player can only be a member of one island, but can be a co-op member of multiple islands.

Island Invitations

// Manage invitations
void addInvite(Island island);
void removeInvite(Island island);
List<Island> getInvites(); // In order received

Do not call addInvite() or removeInvite() directly. Use Island.inviteMember() and Island.revokeInvite() instead.

Player Roles

Role System

Players have roles that determine their permissions on the island:

Get Role

PlayerRole getPlayerRole();

Returns the player’s current role (e.g., Member, Moderator, Admin).

Set Role

void setPlayerRole(PlayerRole role);

Changes the player’s role. Only higher-ranked members can change roles.

Role Properties

// PlayerRole methods
int getId();
String getName();
String getDisplayName();
int getWeight(); // Higher = more permissions

boolean isHigherThan(PlayerRole other);
boolean isLessThan(PlayerRole other);
boolean isFirstRole();
boolean isLastRole();
boolean isRoleLadder();

PlayerRole getNextRole();
PlayerRole getPreviousRole();

Role Hierarchy

Roles are organized in a ladder system:

Owner (highest weight)
  ↓
Admin
  ↓
Moderator  
  ↓
Member
  ↓
Co-op (lowest weight)

Permissions

Island Permissions

// Check island privilege
boolean hasPermission(IslandPrivilege permission);

// Check bypass permissions
boolean hasBypassPermission(IslandPrivilege permission);

// Regular Bukkit permissions
boolean hasPermission(String permission);
boolean hasPermissionWithoutOP(String permission);

Island privileges are separate from Bukkit permissions. They control actions like breaking blocks, opening doors, or changing settings.

Player Preferences

Players have numerous preferences that affect their gameplay experience:

Toggle Settings

World Border

boolean hasWorldBorderEnabled();
void toggleWorldBorder();
void setWorldBorderEnabled(boolean enabled);
void updateWorldBorder(Island island);

Displays island boundaries visually.

Blocks Stacker

boolean hasBlocksStackerEnabled();
void toggleBlocksStacker();
void setBlocksStacker(boolean enabled);

Enables block stacking mode for placing multiple blocks.

Team Chat

boolean hasTeamChatEnabled();
void toggleTeamChat();
void setTeamChat(boolean enabled);

Messages sent only to island members.

Island Fly

boolean hasIslandFlyEnabled();
void toggleIslandFly();
void setIslandFly(boolean enabled);
boolean hasFlyGamemode(); // Check if in creative/spectator

Allows flying on the player’s island.

Bypass Mode

boolean hasBypassModeEnabled();
void toggleBypassMode();
void setBypassMode(boolean enabled);

For admins to bypass island protections.

Admin Spy

boolean hasAdminSpyEnabled();
void toggleAdminSpy();
void setAdminSpy(boolean enabled);

Receive notifications about island activities.

Panel Toggle

boolean hasToggledPanel();
void setToggledPanel(boolean toggled);

Enable/disable GUI panels.

Schematic Mode

boolean hasSchematicModeEnabled();
void toggleSchematicMode();
void setSchematicMode(boolean enabled);

For creating island schematics.

Locale & Appearance

// Language preference
Locale getUserLocale();
void setUserLocale(Locale locale);

// Border color
BorderColor getBorderColor();
void setBorderColor(BorderColor color);

Location & Teleportation

Location Methods

// Get location
World getWorld();
Location getLocation();
Location getLocation(Location reuse); // Reuse location object

Teleportation

Basic Teleport

// Teleport to location
void teleport(Location location);
void teleport(Location location, Consumer<Boolean> result);

Player Status

Players can have multiple status flags:

// Status management
void setPlayerStatus(PlayerStatus status);
void removePlayerStatus(PlayerStatus status);
boolean hasPlayerStatus(PlayerStatus status);

Common Status Flags

• PVP Warmup: Player recently toggled PVP
• Teleporting: Player is in teleport warmup
• Flying: Player is flying on their island
• Leaving Island: Player is leaving island area

Schematics

For players creating custom island schematics:

// Schematic positions
BlockPosition getSchematicPos1();
void setSchematicPos1(Block block);

BlockPosition getSchematicPos2();
void setSchematicPos2(Block block);

1. Enable schematic mode

   player.setSchematicMode(true)

2. Set position 1

   player.setSchematicPos1(block)

3. Set position 2

   player.setSchematicPos2(block)

4. Save schematic

   Use SuperiorSkyblock API to save the region

Disbands Tracking

// Disband limits
int getDisbands();
void setDisbands(int amount);
boolean hasDisbands();

Prevents players from repeatedly creating and disbanding islands.

PvP System

// Check if player can hit another
HitActionResult canHit(SuperiorPlayer target);

PvP Rules

Players cannot hit each other if:

1. Inside an island with PvP disabled
2. One player has PvP warmup active
3. Both are in the same island outside PvP worlds
4. Target is a visitor with damage immunity
5. Target is a co-op member with damage immunity

Missions Integration

Players implement IMissionsHolder for mission tracking:

// Mission progress
void completeMission(Mission<?> mission);
Map<Mission<?>, Integer> getCompletedMissions();
boolean hasCompletedMission(Mission<?> mission);
int getAmountMissionCompleted(Mission<?> mission);

void resetMission(Mission<?> mission);
void resetAllMissions();

See Missions for more details.

Persistent Data

Store custom data on players:

// Get persistent data container
PersistentDataContainer getPersistentDataContainer();

This allows modules to store custom data that persists across restarts.

Caching System

// Access player cache
PlayerCache getCache();

The cache system provides fast access to frequently accessed data.

Menu & GUI

// Get currently opened menu
MenuView<?, ?> getOpenedView();

Use this to check if a player has a SuperiorSkyblock menu open.

Player States

Visibility States

// Check player visibility
boolean isVanished();
boolean isAFK();
boolean isShownAsOnline(); // Not vanished, not spectator, online

Player Builder

For creating SuperiorPlayer instances programmatically:

SuperiorPlayer.Builder builder = SuperiorPlayer.newBuilder()
    .setUniqueId(uuid)
    .setName("PlayerName")
    .setPlayerRole(role)
    .setLocale(Locale.US)
    .setDisbands(3)
    .setWorldBorderEnabled(true)
    .setIslandFly(false);

SuperiorPlayer player = builder.build();

The builder is for advanced usage. In normal operation, SuperiorSkyblock manages player creation automatically.

Data Merging

// Merge another player's data
void merge(SuperiorPlayer otherPlayer);

Used when consolidating player accounts or migrating data.

Best Practices

Check Online Status

Always verify isOnline() before accessing player-specific data like location or inventory.

Use Async Operations

For operations that might cause lag, use callbacks and async patterns.

Respect Permissions

Check both island privileges and Bukkit permissions before actions.

Handle Null Islands

Not all players have islands. Check hasIsland() first.

See Also

Islands

Learn about the island system

Missions

Understand player mission tracking