Overview

AstralSkyblock is the network skyblock plugin for AstralRealms. Every island is an isolated SlimeWorld that is created from a blueprint, persisted to MySQL, and loaded on demand on whichever island server has room for it — players never need to be on the "home" server of their island to play on it. Island data (roles, permissions, members, co-ops, settings, upgrades) is cached in Redis and kept consistent across every server over RabbitMQ, and almost the entire player experience is driven through AstralCore menus and dialogs rather than commands.

Highlights

Area	Summary
Islands	One `Island` per SlimeWorld, created from an `IslandBlueprint` (schematic + spawn point + icon). Locked by default until the owner explicitly opens it.
Roles & permissions	Per-island `IslandRole` registry (`MEMBER`/`VISITOR`/`COOP` kinds) gating 52 typed `IslandPermission`s (including the `ALL` wildcard), seeded from `roles.yml` at creation.
Settings	18 togglable `IslandSettings` environment flags (PvP, mob griefing, fire/water/lava spread, time & weather locks with mutual-exclusion groups, …).
Members, co-ops & invitations	`IslandMember` roster with ownership transfer, `IslandCoop` trusted-visitor grants, and time-limited (15 minute) `IslandInvitation`s for both.
Upgrades	Priced, levelled `IslandUpgrade` tracks (world border size, member/co-op/hopper/minecart limits, crop growth speed, spawner rate, mob drops, generator) loaded from `upgrades/*.yml`.
Generators	Cobblestone/basalt generators re-roll into a configurable block table (`generators/*.yml`) on `BlockFormEvent`; valuable blocks are gated behind the `VALUABLE_BREAK` permission via `block-values.yml`.
Multi-server hosting	`ServerService` tracks the emptiest island server and the live host per island; players are routed and teleported cross-server automatically.
GUI-driven UX	Island management (members, roles, permissions, settings, co-ops, bans, upgrades) runs through AstralCore menus/dialogs, not subcommands.

Requirements

Dependency	Required	Notes
Paper	Yes	`api-version: '1.21'`, `load: POSTWORLD` (so worlds from other plugins are already up).
AstralCore	Yes	Declared in `plugin.yml` `depend`. Provides menus, dialogs, actions, placeholders, `DatabaseService`, `CacheService`, `MessagingService`.
AdvancedSlimePaper (ASP)	Yes	Island worlds are `SlimeWorld`s loaded/cloned/saved through the ASP API (`AdvancedSlimePaperAPI`).
MySQL	Yes	Two independent MySQL surfaces: `DatabaseService` (islands, roles, members, …) and a dedicated ASP `MysqlLoader` (world blobs), each configured in `database.properties`/`loader.yml`.
Redis	Yes	`CacheService`-backed caches for islands, roles, members, servers, warps, upgrades, flags, bans and co-ops.
RabbitMQ	Yes	`MessagingService` + `ASPacketRegistry`, used for island load requests, member/co-op sync, deletes and repository invalidation packets.

Island servers vs lobby servers

AstralSkyblock runs on every server that depends on it, but only some servers actually host island worlds. SkyblockConfiguration.islandsGroup (islands-group in config.yml) names the server group that hosts islands; SkyblockConfiguration#isIslandServer() compares it against the running server's own group (AstralPaperAPI.serverInformation().group()). AstralSkyblock#onEnable uses that check to decide what to register:

Island-only listeners — IslandSettingsListener (applies/enforces IslandSettings on the world) and IslandPermissionsListener (enforces IslandPermissions on block/entity/interact events) register only when isIslandServer() is true.
Generators — GeneratorListener registers only when configuration.generators().enabled() is true (independent of the island-server check, but generator blocks only exist in island worlds).
The idle-world sweep and per-server island-count heartbeat (WorldService, ServerService) likewise only run on island servers, since only they hold loaded island worlds to sweep or report.

Every server — island or lobby — still runs PlayerConnectionListener, IslandListener, the base commands, and the placeholder/service layer, so /is go and menu-driven navigation work from anywhere on the network.

Core concepts

Concept	What it is
Island	The persisted unit of gameplay: a `UUID`, name, lock state, level, spawn pose, and (while active) hydrated relationships to its owner, members, roles, co-ops, settings and upgrades.
IslandBlueprint	A named schematic template (`sourceWorld`, spawn `MinecraftLocation`, icon) loaded from `blueprints/*.yml`; one is flagged `default: true` and used when `/is create` is given no blueprint.
IslandRole / IslandPermission	Per-island governance: roles carry a `weight` (seniority), a `kind` (`MEMBER`, `VISITOR`, `COOP`), and a set of `IslandPermission`s (or the `ALL` wildcard). `Island#hasPermission` checks the island owner, then the player's member role, then — for non-members — their co-op role.
IslandSettings	Per-island environment flags (`ALWAYS_DAY`, `PVP`, `CREEPER_EXPLOSION`, …) with conflict groups so only one time-lock and one weather-lock can be active at once.
IslandMember / IslandCoop / IslandInvitation	Membership is owner + role-bearing members; co-op grants a trusted non-member a role's permissions without membership; invitations are time-boxed (15 minutes) offers of either kind.
IslandUpgrade	A priced, levelled track (`UpgradeType`: `WORLDBORDER_SIZE`, `MEMBERS_LIMIT`, `COOP_LIMIT`, `GENERATOR`, `HOPPERS_LIMIT`, `CROP_GROWTH_SPEED`, `SPAWNERS_RATE`, `MOB_DROPS`, `MINECART_LIMITS`) purchased level-by-level from `upgrades/*.yml`.
Generators & block values	`generators/*.yml` defines the weighted block table a cobblestone/basalt generator re-rolls into; `block-values.yml` assigns a point value per block and doubles as the membership set that gates `VALUABLE_BREAK`.

Command surface at a glance

The base alias is skyblock|is|island. Subcommands are split across four ACF command classes that all share the alias:

Subcommand	Class	Purpose
(default)	`SkyblockCommand`	Opens the `island-main` menu for the player's island.
`create`, `delete`, `go`, `reload`	`SkyblockCommand`	Island lifecycle and teleport; `reload` requires `skyblock.reload`.
`invite`, `coop`, `accept`, `decline`, `cancel`	`InvitationCommand`	Invitation lifecycle for both member and co-op invites.
`kick`, `leave`, `promote`, `demote`, `transfer`	`MemberCommand`	Membership and role management.
`uncoop`	`CoopCommand`	Removes a co-op grant.

See Commands for full syntax, permissions and completions.

Services

AstralSkyblock#onEnable constructs and exposes the following services (accessible as AstralSkyblock.get().<name>()):

Getter	Service	Responsibility
`blueprints()`	`BlueprintService`	Loads `blueprints/*.yml`, tracks the default blueprint.
`worlds()`	`WorldService`	ASP `SlimeWorld` create/load/save/unload, host-server bookkeeping, idle-unload sweep.
`islands()`	`IslandService`	Island CRUD, cache warmup, cross-server spawn resolution, settings flush.
`players()`	`PlayerService`	Records last-seen player rows.
`roles()`	`RoleService`	Role CRUD and permission seeding from `roles.yml`.
`members()`	`MemberService`	Membership CRUD, cross-server member sync.
`coops()`	`CoopService`	Co-op grant CRUD, cross-server sync.
`invitations()`	`InvitationService`	Invitation lifecycle, periodic pruning of expired invites.
`servers()`	`ServerService`	Emptiest-island-server lookup, per-island host-server mapping.
`generators()`	`GeneratorService`	Loads `generators/*.yml`, resolves the default generator.
`upgrades()`	`UpgradeService`	Loads `upgrades/*.yml`, purchases/levels island upgrades.
`menus()`	`MenuContainer` (AstralCore)	Loads and opens the `menus/*.yml` screens.
`dialogs()`	`DialogContainer` (AstralCore)	Loads dialog-driven prompts (e.g. name entry, confirmations).

Eleven AstralSkyblock actions back the settings/permissions/member/co-op menus and are registered directly on the plugin: toggle-role-permission, update-role-permissions, toggle-island-setting, update-island-settings, invite-member, kick-member, promote-member, demote-member, transfer-ownership, coop-player, uncoop-player.

GUI-driven UX

Beyond the handful of ACF commands above, island management is a menu/dialog flow: island-main links out to island-members, island-roles, island-permissions, island-settings, island-coops, island-bans, island-creation, island-member-manage, island-member-role, and confirmation menus (island-confirm-kick, island-confirm-leave, island-confirm-disband, island-confirm-ban) under resources/menus/, each wired up with [open-menu]/ action-list clicks rather than typed arguments. This is why most of the IslandPermission catalogue (role edits, settings toggles, warp/ban management, …) has no corresponding subcommand — it's exclusively menu-driven.

Multi-server hosting model

Because an island can be visited from any lobby server, AstralSkyblock resolves where to spawn a player before teleporting them:

ServerService#findHostServer checks Redis for a live host-server mapping for the island.
If none exists, ServerService#findEmptiestServer picks the island server with the fewest loaded islands (from a self-reported heartbeat each island server publishes every 300 ticks), filtered to servers under their maximum-islands cap.
If the emptiest server is the current server, the world is loaded locally; otherwise an IslandLoadRequestPacket is sent over RabbitMQ and awaited before a NetworkLocation is resolved.
SkyblockCommand#onGo (and any other spawn path through IslandService#spawnIsland) hands the resolved NetworkLocation to AstralCore's TeleportationService, which performs the actual cross-server teleport.

WorldService also runs an idle-unload sweep on island servers (default 5 minutes of emptiness, configurable via world-idle-unload-seconds, negative to disable) so unattended islands free their server's island slot.

Astral Realms Documentation Help