Placeholders

Supported software

Server Type	PlaceholderAPI	This Plugin
Paper & Forks	Yes	Yes
Purpur	Yes	Yes
Folia	Yes	Yes
Spigot	Yes	No
Other	No	No

Install the plugin

Install the required plugins

Download Placeholders from GitHub and PlaceholderAPI. Folia requires PlaceholderAPI 2.11.7 or newer.Place both JARs in the server template’s plugins/ folder. Standard SimpleCloud templates already include simplecloud-api; add it through the target’s Plugins setting or the CLI if you use a custom template.

Start a matching server

Start a server from the template. The plugin registers the simplecloud expansion with PlaceholderAPI; it does not require a separate expansion download.

Test a placeholder

Join the server and run:

/papi parse me %simplecloud_server_id%

A group server returns its SimpleCloud server UUID. A persistent server returns a value when you use a persistent_server_* placeholder instead.

The expansion identifier is simplecloud, so every placeholder starts with %simplecloud_...%.

Server placeholders

These placeholders resolve from the current SimpleCloud server using SIMPLECLOUD_UNIQUE_ID.

Placeholder	Description
`%simplecloud_server_id%`	Server UUID
`%simplecloud_server_type%`	Server group type
`%simplecloud_server_host%`	Serverhost ID
`%simplecloud_server_numerical_id%`	Numerical ID within the group
`%simplecloud_server_ip%`	Server IP address
`%simplecloud_server_port%`	Server port
`%simplecloud_server_max_players%`	Maximum players
`%simplecloud_server_min_memory%`	Minimum memory in MB
`%simplecloud_server_max_memory%`	Maximum memory in MB
`%simplecloud_server_player_count%`	Current player count
`%simplecloud_server_state%`	Current server state

Group placeholders

These placeholders resolve from the current SimpleCloud group using SIMPLECLOUD_GROUP.

Placeholder	Description
`%simplecloud_group_name%`	Group name
`%simplecloud_group_type%`	Group server type
`%simplecloud_group_min_memory%`	Minimum memory in MB
`%simplecloud_group_max_memory%`	Maximum memory in MB
`%simplecloud_group_max_players%`	Maximum players per server
`%simplecloud_group_player_count%`	Summed player count across group servers

Persistent-server placeholders

These placeholders resolve from the current persistent server using SIMPLECLOUD_UNIQUE_ID.

Placeholder	Description
`%simplecloud_persistent_server_id%`	Persistent-server UUID
`%simplecloud_persistent_server_name%`	Persistent-server name
`%simplecloud_persistent_server_type%`	Server type
`%simplecloud_persistent_server_host%`	Assigned serverhost ID
`%simplecloud_persistent_server_max_players%`	Maximum players
`%simplecloud_persistent_server_min_memory%`	Minimum memory in MB
`%simplecloud_persistent_server_max_memory%`	Maximum memory in MB
`%simplecloud_persistent_server_player_count%`	Current player count, or `0` when no instance is running
`%simplecloud_persistent_server_is_active%`	Whether the persistent server is active

Target another resource

By default, the placeholders above return information about the server on which the plugin is running. To display information about another resource, add its selector before the property.

Resource	Format
Group	`%simplecloud_group_<group-name>_<property>%`
Persistent server	`%simplecloud_persistent_server_<persistent-server-name>_<property>%`
Running server by group and numerical ID	`%simplecloud_server_<group-name>:<numerical-id>_<property>%`
Running server by UUID	`%simplecloud_server_id:<server-id>_<property>%`

For example:

%simplecloud_group_Lobby_player_count%
%simplecloud_persistent_server_MainLobby_is_active%
%simplecloud_server_Lobby:1_state%
%simplecloud_server_id:550e8400-e29b-41d4-a716-446655440000_player_count%

Use the same properties that appear after the resource prefix in the tables above. For example, server_player_count becomes server_Lobby:1_player_count, and group_max_players becomes group_Lobby_max_players.

Group and persistent-server names may contain underscores. The colon in a running-server selector separates the group name from its numerical server ID.

A targeted placeholder cannot be resolved if the selected resource does not exist, the running server is offline, or the selector is invalid.

Example usage

scoreboard:
  title: "&bServer Status"
  lines:
    - "&7Server: &f%simplecloud_server_id%"
    - "&7Players: &f%simplecloud_server_player_count%/%simplecloud_server_max_players%"
    - "&7State: &f%simplecloud_server_state%"
    - ""
    - "&7Group: &f%simplecloud_group_name%"
    - "&7Total Players: &f%simplecloud_group_player_count%"
    - ""
    - "&7Lobby-1: &f%simplecloud_server_Lobby:1_player_count% players"

If a current-resource placeholder returns no value, confirm that the server is running inside SimpleCloud and that the matching environment variable is available. For a targeted placeholder, verify the resource name, UUID, or numerical ID.

Troubleshooting

PlaceholderAPI leaves the placeholder unchanged

Confirm that PlaceholderAPI, simplecloud-api, and simplecloud-placeholder are enabled on the same Paper server. Then check the server log for dependency or expansion registration errors.

A current-server placeholder returns no value

Run the server through SimpleCloud. Current-resource placeholders depend on the SIMPLECLOUD_UNIQUE_ID or SIMPLECLOUD_GROUP environment variable set by SimpleCloud.

A targeted placeholder returns no value

Check the resource name, UUID, or numerical ID. The target must exist, and a targeted running server must be online.

Introduction

Setup

Configuration

Plugins

Supported software

Install the plugin

Server placeholders

Group placeholders

Persistent-server placeholders

Target another resource

Example usage

Troubleshooting

​Supported software

​Install the plugin

​Server placeholders

​Group placeholders

​Persistent-server placeholders

​Target another resource

​Example usage

​Troubleshooting

Supported software

Install the plugin

Server placeholders

Group placeholders

Persistent-server placeholders

Target another resource

Example usage

Troubleshooting