Placeholders

AstralSkyblock registers one root namespace and four chaining namespaces with AstralCore. For the placeholder syntax itself (%a_b_c%, %a_{b_c}%, $e(...)) see Placeholders.

`skyblock_*` (root)

SkyblockPlaceholders registers under RootPlaceholderContainer — usable anywhere AstralCore evaluates a placeholder (menus, dialogs, messages).

Placeholder	Type	Description
`%skyblock_player_island%`	Island?	The requesting player's island, resolved via `MemberService#findPlayerIsland`. Requires a `Player` context (`context.context()`); returns `null` if the context isn't a player or the player has no island. Chain further tokens into the `island_*` sub-keys below.

view-requirements:
  - "[compare] %skyblock_player_island_hasPermission_SET_SETTINGS% == true"

`island_*`

Island is itself a ComplexPlaceholder (namespace island). Reached via %skyblock_player_island_*%, or registered directly wherever a command/service builds a PlaceholderContainer for a specific island (.registerPlaceholder(island) — surfaces as bare %island_*%), or passed into a menu as a %parameters_island% parameter and chained as %parameter_island_*%/%parameters_island_*% inside that menu's own placeholder scope.

Placeholder	Type	Description
`%island_id%`	UUID	Primary key.
`%island_name%`	String	Island name.
`%island_locked%`	Boolean	Lock state.
`%island_level%`	int	Island level.
`%island_owner%`	IslandMember	The owning member — chain into `member_*` (see Members, Co-ops & Invitations).
`%island_members%`	ItemProvider<IslandMember>	All members, for a layout `provider:`. Iterate into `member_*` per item — see Members, Co-ops & Invitations.
`%island_roles%`	ItemProvider<IslandRole>	All roles, for a layout `provider:`. Iterate into `role_*` per item — see Roles, Permissions & Settings.
`%island_settings%`	ItemProvider<setting>	Every `IslandSettings` value paired with this island, wrapped in an `IslandSettingsItemProvider`. Iterate into `setting_*` per item (see below).
`%island_hasPermission_<PERMISSION>%`	Boolean	Whether the current `Player` context holds `<PERMISSION>` on this island (`Island#hasPermission`, an `IslandPermission` enum name). Requires a `Player` context — `null` otherwise.
`%island_upgradeLevel_<UPGRADE_TYPE>%`	int	The island's purchased level for `<UPGRADE_TYPE>` (an `UpgradeType` enum name), `0` if never purchased.
`%island_updatedAt%`	long	Last-updated timestamp (epoch millis).
`%island_createdAt%`	long	Creation timestamp (epoch millis).

A bare %island% (no further tokens) returns the Island instance itself.

hasPermission and upgradeLevel each consume every remaining token as the enum name (context.collapseRemaining()), so multi-word enum constants work without extra escaping:

view-requirements:
  - "[compare] %skyblock_player_island_hasPermission_SET_SETTINGS% == true"
  - "[compare] %skyblock_player_island_hasPermission_BAN_MEMBER% == true"

lore:
  - "<gray>World border level: %parameters_island_upgradeLevel_WORLDBORDER_SIZE%"

`setting_*`

IslandSettingsPlaceholder (namespace setting) pairs one IslandSettings enum constant with the island it belongs to. Reached by iterating %island_settings% inside a menu layout — the layout's taint: (e.g. setting) exposes the current item as %parameter_setting_*%/%parameters_setting_*% for that iteration.

Placeholder	Type	Description
`%setting_id%`	String	The `IslandSettings` enum name (e.g. `PVP`, `ALWAYS_DAY`).
`%setting_item%`	ItemStackPlaceholder	The setting's configured icon (`IslandSettings#value`, an `ItemStackWrapper` from `settings.yml`), resolved against the current placeholder function. Chain further into item sub-keys (`material`, `name`, `lore`, …).
`%setting_enabled%`	Boolean	Whether the paired island currently has this setting enabled (`Island#isSettingEnabled`).

A bare %setting% (no further tokens) returns the IslandSettings enum constant itself.

items:
  setting-enabled:
    copy-from: "%parameter_setting_item%"
    view-requirements:
      - "[compare] %parameter_setting_enabled% == true"
    actions:
      - "[toggle-island-setting] %parameters_island% %parameter_setting%"

See Roles, Permissions & Settings for the full list of IslandSettings values and their conflict groups.

`permission_*`

IslandPermissionPlaceholder (namespace permission) pairs one IslandPermission enum constant with the IslandRole it belongs to. Reached by iterating a role's %role_permissions% (an IslandPermissionsItemProvider) inside a menu layout, exposed under that layout's taint: the same way as setting_* above.

Placeholder	Type	Description
`%permission_id%`	String	The `IslandPermission` enum name (e.g. `KICK_MEMBER`, `SET_SETTINGS`).
`%permission_item%`	ItemStackPlaceholder	The permission's configured icon (`IslandPermission#value`, an `ItemStackWrapper` from `permissions.yml`), resolved against the current placeholder function.
`%permission_enabled%`	Boolean	Whether the paired role currently grants this permission (`IslandRole#hasPermission`).

A bare %permission% (no further tokens) returns the IslandPermission enum constant itself.

items:
  permission-enabled:
    copy-from: "%parameter_permission_item%"
    view-requirements:
      - "[compare] %parameter_permission_enabled% == true"
    actions:
      - "[toggle-role-permission] %parameters_island% %parameters_role% %parameter_permission%"

See Roles, Permissions & Settings for the full list of IslandPermission values and where roles are edited.

`upgrade_*`

IslandUpgrade (namespace upgrade) represents one priced, levelled track loaded from upgrades/*.yml (e.g. WORLDBORDER_SIZE). Reached wherever a service or menu registers an IslandUpgrade directly, or by iterating the upgrade registry.

Placeholder	Type	Description
`%upgrade_type%`	UpgradeType	The upgrade's enum type.
`%upgrade_levels%`	ItemProvider<level>	Every configured `Level` for this upgrade, for a layout `provider:`.
`%upgrade_level_<n>%`	Level?	The `Level` entry whose config key is `<n>` (looked up in the `levels` map keyed by level number), or `null` if no `<n>` token follows.

A bare %upgrade% (no further tokens) returns the IslandUpgrade record itself.

`level_*`

IslandUpgrade.Level (namespace level) is one purchasable rung of an upgrade track.

Placeholder	Type	Description
`%level_level%`	int	The level number.
`%level_price%`	double	Cost to purchase this level.
`%level_currency%`	String	Currency id charged (e.g. `default`).
`%level_currencyDisplay%`	Component	Display name for the currency, resolved from the configured `currencyDisplay` component against the current placeholder function.
`%level_value%`	double	The gameplay value granted at this level (meaning depends on `UpgradeType` — e.g. world border radius).

A bare %level% (no further tokens) returns the Level record itself.

See Islands for the full upgrade purchase flow and the UpgradeType catalogue.

Resolution chaining

Every namespace above implements ComplexPlaceholder.get(PlaceholderContext), which switches on context.next() one underscore-separated token at a time. A case that returns another ComplexPlaceholder (or an ItemProvider, which is one) is a chain point — resolution keeps consuming tokens against the new object until a leaf value is returned. This is how %skyblock_player_island_settings_at_0_enabled% walks from the root namespace, into the caller's island, into its settings provider, to a specific setting, down to a boolean leaf.

Usage note

These placeholders are consumed almost entirely inside menus/*.yml and messages.yml. Two registration patterns show up across the source:

Chained from the player — %skyblock_player_island_*%, used in menu view-requirements that gate buttons on the viewer's own island (e.g. %skyblock_player_island_hasPermission_SET_SETTINGS% in main.yml).
Registered directly — commands and services build a PlaceholderContainer for a specific island (not necessarily the viewer's) and register it with .registerPlaceholder(island), plus a target player where relevant: AstralPaperAPI.createPlaceholderContainer(kicker).registerPlaceholder(island).registerDirect("target", ...). This surfaces as bare %island_*%/%target_*% in messages.yml strings such as member-not-found: "%target_name% is not a member of %island_name%." Menus instead receive the island as an open parameter (%parameters_island%) and chain from there.

See Placeholders for the shared %parameters_*%/%layouts_*% mechanics that carry the island through a menu.

Last modified: 25 July 2026

Placeholders

skyblock_* (root)

island_*

setting_*

permission_*

upgrade_*

level_*