Members, Co-ops & Invitations

Sending

/is invite <player> (permission INVITE_MEMBER) and /is coop <player> (permission COOP_MEMBER) both resolve the sender's island and call InvitationService.create(island, sender, recipient, type) with InvitationType.MEMBER or InvitationType.COOP respectively. The [invite-member] and [coop-player] menu actions do the same, performing the identical permission check themselves before calling create.

InvitationService.create performs no permission check of its own — that is entirely the caller's job — but does guard against redundant invitations, silently returning after messaging the sender:

Otherwise a new IslandInvitation is persisted (15-minute TTL), the sender gets invitation-sent, and the recipient gets invitation-received delivered cross-server through AstralCore's ChatService.

Responding

/is accept [player] and /is decline [player] both call InvitationService.findByRecipient and filter to non-expired invitations:

• With a [player] argument, only that sender's pending invitation is considered; none found → no-pending-invitation.

• With no argument, all of the recipient's pending invitations are considered: zero → no-pending-invitation; more than one → multiple-pending-invitations (the player must re-run the command naming a sender to disambiguate); exactly one is auto-selected.

InvitationService.accept re-resolves the pending invitation by (islandId, recipientId), then delegates to MemberService.addMember (type MEMBER) or CoopService.add (type COOP), deletes the invitation row, and messages both sides (invitation-accepted-recipient/invitation-accepted-sender). InvitationService.decline just deletes the row and messages both sides (invitation-declined-recipient/invitation-declined-sender).

Both accept and decline resolve the island with a synchronous local-cache lookup (IslandService.repository().findCachedById) before touching the invitation at all. If the island isn't currently hydrated on the server the responding player is standing on, the call fails as invitation-not-found even though the invitation row still exists in the database.

Cancelling

/is cancel <player> calls InvitationService.cancel(island, sender, target). Only the original sender may cancel — the check is invitation.senderId().equals(sender.getUniqueId()); a mismatch (or no pending invitation) is silently reported as invitation-not-found. On success both sides are messaged (invitation-cancelled-sender/invitation-cancelled-recipient).

Expiry & pruning

• IslandInvitation.create sets expiresAt = now + 15 * 60 * 1000 (15 minutes).

• InvitationRepository.findPending filters expires_at > now at the SQL level, so an expired invitation is invisible to the duplicate-check in create and to accept/decline/cancel even before it is physically deleted.

• InvitationService's constructor schedules pruneExpiredSync with Bukkit.getScheduler().runTaskTimerAsynchronously(plugin, this::pruneExpiredSync, 1200, 1200) — every 1200 ticks (60 seconds) it bulk-deletes every island_invitations row whose expires_at is in the past.

Kick

MemberCommand#onKick (permission KICK_MEMBER, checked in the command) and the [kick-member] action both call MemberService.kick(island, kicker, targetUuid), which re-checks everything itself:

1. Kicker must have KICK_MEMBER → else no-permission.

2. Target must be a current member → else member-not-found.

3. Target cannot be the owner → else member-higher-role.

4. A non-owner kicker must strictly outrank the target (kicker.role().weight() > target.role().weight()) — owners always bypass this check → else member-higher-role.

On success the row is deleted, IslandMemberLeaveEvent fires locally with Reason.KICKED, a MemberLeavePacket is broadcast, the kicker gets member-kicked-sender, and the kicked player gets member-kicked-target cross-server.

Leave

/is leave calls MemberService.leave(island, player):

• No island → no-island.

• The owner cannot leave → owner-cannot-leave ("Transfer ownership first"). Ownership must be transferred to another member before the former owner can leave.

• Otherwise the row is deleted, IslandMemberLeaveEvent fires with Reason.VOLUNTARY, a MemberLeavePacket is broadcast, and the player gets island-left.

Promote & demote

Both walk a role ladder: island.roles() filtered to kind == MEMBER, sorted ascending by weight (memberRoleLadder). The island owner holds no role at all and is never part of this ladder. With the shipped roles.yml, the MEMBER-kind ladder is just member (weight 2) → admin (weight 3) — visitor and co-op are VISITOR/COOP-kind roles and are never promote/demote targets.

MemberService.promote(island, sender, targetUuid) (permission PROMOTE_MEMBERS):

1. Target must exist and not be the owner → else member-not-found/member-higher-role.

2. If the target is already at the top of the ladder → member-already-highest-role.

3. A non-owner sender cannot promote a target to a role whose weight is >= the sender's own role weight → member-promote-higher.

4. Otherwise the target's role is set to the next rung up; the sender gets member-promoted-sender, the promoted player gets member-promoted-target cross-server.

MemberService.demote(island, sender, targetUuid) (permission DEMOTE_MEMBERS):

1. Target must exist and not be the owner → else member-not-found/member-higher-role.

2. A non-owner sender must strictly outrank the target (same weight comparison as kick) → else member-higher-role.

3. If the target is already at the bottom of the ladder → member-already-lowest-role.

4. Otherwise the target's role is set to the rung below; the sender gets member-demoted-sender, the demoted player gets member-demoted-target cross-server.

Both persist through MemberRepository.setRole and notify the target directly via ChatService — unlike kick/leave, no IslandMemberJoinEvent/IslandMemberLeaveEvent fires for a promote or demote, and no MemberJoinPacket/MemberLeavePacket is sent (see Cross-server sync below).

Transfer ownership

MemberCommand#onTransfer/ the [transfer-ownership] action require the caller to already be the island owner (else not-island-owner), then resolve the target as an existing IslandMember (else member-not-found) and call MemberService.transfer(island, currentOwner, newOwner). Only the current owner may invoke it — enforced again inside transfer itself.

transfer picks the highest-weight MEMBER-kind role on the island (with the shipped roles this is admin, weight 3) and runs a single transaction: the ex-owner is demoted into that role and their isOwner flag cleared, then the new owner's isOwner flag is set and their roleId cleared. On success the ex-owner gets ownership-transferred-sender, the new owner gets ownership-transferred-target cross-server. Like promote/demote, transfer does not fire IslandMemberJoinEvent/IslandMemberLeaveEvent or send a MemberJoinPacket/MemberLeavePacket — cross-server consistency comes entirely from the generic repository sync described below.