Roles, Permissions & Settings

roles.yml structure

roles.yml seeds every new island's role set. It deserializes to RolesConfiguration, a map of role id → entry:

RoleService.defaultRoleSeeds builds one RoleSeed (an IslandRole + its resolved EnumSet<IslandPermission>) per entry, in roles.yml iteration order; IslandRepository#create inserts them as part of the single island-creation transaction. roles.yml only affects islands created afterward — /is reload re-parses the file but does not retroactively touch existing islands' persisted roles or permissions.

Shipped roles

Role weight & hierarchy

weight is the whole hierarchy mechanism — there is no separate rank field. It is used in two places:

• Island#canEditRole(player, role) — true for admins/the owner; for anyone else, only if their own member role's weight is strictly greater than the target role's weight. This gates [toggle-role-permission] and RoleService#updatePermissions (backing [update-role-permissions]): failing it sends ASMessages.ROLE_PERMISSION_HIGHER (" You cannot assign a role higher than your own. ").

• Promote/demote stepping (MemberService#promote/#demote, see Members) — walks the island's roles ordered by ascending weight and moves the target one step up/down that ladder. Non-owners can't promote a member to, or demote a member from, a weight at or above their own; those checks (and kicking/banning a peer-or-senior member) fail with ASMessages.MEMBER_HIGHER_ROLE (" You cannot do that to a member whose role is equal to or higher than yours. ").

In short: ROLE_PERMISSION_HIGHER guards editing a role's permission set, while MEMBER_HIGHER_ROLE guards acting on a member whose role outranks (or matches) the actor's.

Conflict groups

IslandSettings#conflictingSettings() defines two mutually-exclusive groups — only one member of each can be enabled on an island at a time:

• Time locks: ALWAYS_DAY, ALWAYS_MIDDLE_DAY, ALWAYS_NIGHT, ALWAYS_MIDDLE_NIGHT

• Weather locks: ALWAYS_RAIN, ALWAYS_SHINY

Island#toggleSetting enforces this client-side of persistence: enabling a setting that has a conflicting group member currently on stages that conflicting member off in the same dirtySettings flush. Settings outside these two groups (PVP, CROPS_GROWTH, etc.) have no conflicts and toggle independently.

Applying environment settings

Because time/weather locks are world state rather than cancellable events, IslandSettingsListener handles them differently from the rest of the catalogue:

• IslandSettingsListener.applyEnvironment(Island, World) is a static method that reads the active time/weather locks and calls World#setTime/setGameRule(DO_DAYLIGHT_CYCLE, …)/setStorm/setThundering/setGameRule(DO_WEATHER_CYCLE, …) directly. It runs on world load and again every time settings are flushed (from [toggle-island-setting] and [update-island-settings]).

• onTimeSkip/onWeatherChange/onThunderChange cancel any event that would fight an active lock in the interim (e.g. a TimeSkipEvent while any time lock is set, or Minecraft's natural weather engine trying to clear rain while ALWAYS_RAIN is on).

• Every other setting (PVP, CREEPER_EXPLOSION, CROPS_GROWTH, …) is enforced purely by cancelling the relevant Bukkit event when Island#isSettingEnabled is false — no gamerule or world-state mutation.

Default settings on new islands

config.yml's default-settings list is applied to every setting at island creation — IslandRepository#create inserts each IslandSettings constant with its enabled state taken from whether it appears in SkyblockConfiguration#defaultSettings(). The shipped default enables CROPS_GROWTH, EGG_LAY, ENDERMAN_GRIEF, FIRE_SPREAD, GHAST_FIREBALL, LAVA_FLOW, PVP, TNT_EXPLOSION, TREE_GROWTH, WATER_FLOW, and WITHER_EXPLOSION — every setting except the six time/weather locks. See Configuration for the full config.yml reference.

toggle-role-permission

Flips one IslandPermission on one role, staging the change in the role's dirty-permission map (not yet persisted). Requires the executor to have SET_PERMISSION on the island and to outrank the target role.

update-role-permissions

Flushes a role's staged permission toggles to the database via RoleService#updatePermissions, re-checking SET_PERMISSION and the role-weight guard before writing. Sends ROLE_PERMISSION_UPDATE_SUCCESS/ROLE_PERMISSION_UPDATE_FAILURE to the executor. Wired as a close-actions hook on the island-permissions menu, so it fires once when the player backs out or closes the menu rather than on every individual toggle.

toggle-island-setting

Flips one IslandSettings flag, staging it in the island's dirty-settings map and immediately re-applying the environment (time/weather gamerules and state) if the island's world is loaded on the current server. Requires SET_SETTINGS.

update-island-settings

Flushes an island's staged setting toggles via IslandService#updateSettings, re-checking SET_SETTINGS before writing and re-applying the environment once persistence succeeds. Sends SETTINGS_UPDATE_SUCCESS/SETTINGS_UPDATE_FAILURE. Wired as a close-actions hook on island-settings.