PlaceholderAPI - A hub for your placeholders

[dualspiral]

Ok, so I’ve managed to create my bridge between Nucleus and PlaceholderAPI, which is great! I had one question about the API - the onPlaceholderRequest method has an argument “Function<Text, String> textParser”.

From what I can see, it’s to send down a text serialiser to use… but surely the Expansion should be solely responsible for creating the Text object? I don’t know what format the parser is expecting of me - I don’t have control of that. I could put a string in there, and it’ll get formatted differently based on what has been sent down, or not parsed at all, if it doesn’t conform.

For example, let’s take one of your expansions: the Player expansion. If I send down an Ampersand Formatting code serialiser, this works fine. If I send down a JSON serialiser, this breaks. You should be performing the Text formatting in that method yourself, without the help of a serialiser (and if you need one, the Expansion should decide that).

Surely you should just get the Text object out (as you’ll want the formatting as the Expansion author intended it), and apply any post-processing to it after, rather than providing a text parser which may be different each time and might cause an exception.

[Wundero]

Alright, I will change that. I can’t think of a good reason to keep the system like that, I guess I was just trying to add too much extra functionality that backfired on me.

[rojo8399]

A new version has been released for PlaceholderAPI, it is available for download here.

---

What’s new in version 3.5:

• Fixed load order of placeholders
• BREAKING CHANGE: Removed TextSerializers from PlaceholderService and Expansion - Any plugins using this API will need to update their placeholders to match this change.
• JavaScript minor fixes

Check out the plugin wiki!

View the plugin on GitHub!

[rojo8399]

A new version has been released for PlaceholderAPI, it is available for download here.

---

What’s new in version 3.6:

• Fixed issue with %economy% placeholder

Check out the plugin wiki!

View the plugin on GitHub!

[rojo8399]

A new version has been released for PlaceholderAPI, it is available for download here.

---

What’s new in version 3.7:

• Renamed ‘currency’ to ‘economy’ to match in game placeholder - the only needed update is in the placeholderapi.conf file.
• Fixed info command error
• Fixed issue with regular expression in the parse command
• Allowed service to specify a Pattern for placeholder matching, rather than just open/close text
• Better colour handling for parsing strings into templates
• Internal fixes, changes and improvements

Check out the plugin wiki!

View the plugin on GitHub!

[rojo8399]

A new version has been released for PlaceholderAPI, it is available for download here.

---

What’s new in version 3.8:

• Fixed issues with open/close argument specification
• Allowed more customizable TextTemplate parsing:
  • Allowed plugins to provide their own map with arguments to provide the template, PlaceholderAPI will fill what’s not in the map
  • Allowed plugins to request what PlaceholderAPI would fill into the arguments. NOTE: PlaceholderAPI will automatically fill all non-optional arguments regardless of whether it is a placeholder, and the mapped values will simply be key surrounded by open/close arguments
• Added %player_ping% placeholder
• Slightly better info command output
• JavaScript placeholders now allowed to parse with a pattern or without.
• Slightly better parse command handling.
• Internal improvements

Check out the plugin wiki!

View the plugin on GitHub!

[SenpaiPuff]

@rojo8399 Is it possible to add a placeholder with Pixelmon values, for example Pokédex value?

[rojo8399]

A new version has been released for PlaceholderAPI, it is available for download here.

---

What’s new in version 3.9 (This version is for Sponge 5.2):

• API BREAKING: Removed support for TextSerializer serialization of texts and opted for format code serialization only
• Improved performance
• Better documented the Pattern argument in the PlaceholderService interface so that incoming regular expressions successfully match placeholders
• Added JavaScript function value(...) to the service variable to allow variables to be returned as String, an operable type in JavaScript
• Improved internal security
• Added ListeningExpansion interface to allow expansions to register as listeners through PlaceholderAPI
• Made the info command have a slightly less constrained output for placeholder tokens
• Changed server configuration (will be enabled by default so should continue to work unless you have it disabled, but you will want to update your configuration after loading this version with settings you want. The server = true/false node will no longer work)
• Added many player placeholders:
  • %player_stat_<minecraft statistic name>%
  • %player_language%
  • %player_gamemode%
  • %player_flying%
  • %player_health%
  • %player_max_health%
  • %player_food%
  • %player_saturation%
  • %player_x%
  • %player_y%
  • %player_z%

Check out the plugin wiki!

View the plugin on GitHub!

[rojo8399]

A new version has been released for PlaceholderAPI, it is available for download here.

---

What’s new in version 3.9 (This version is for Sponge 5.1):

• API BREAKING: Removed support for TextSerializer serialization of texts and opted for format code serialization only
• Improved performance
• Better documented the Pattern argument in the PlaceholderService interface so that incoming regular expressions successfully match placeholders
• Added JavaScript function value(...) to the service variable to allow variables to be returned as String, an operable type in JavaScript
• Improved internal security
• Added ListeningExpansion interface to allow expansions to register as listeners through PlaceholderAPI
• Made the info command have a slightly less constrained output for placeholder tokens
• Changed server configuration (will be enabled by default so should continue to work unless you have it disabled, but you will want to update your configuration after loading this version with settings you want. The server = true/false node will no longer work)
• Added many player placeholders:
  • %player_stat_<minecraft statistic name>%
  • %player_language%
  • %player_gamemode%
  • %player_flying%
  • %player_health%
  • %player_max_health%
  • %player_food%
  • %player_saturation%
  • %player_x%
  • %player_y%
  • %player_z%

Check out the plugin wiki!

View the plugin on GitHub!

[rojo8399]

A new version has been released for PlaceholderAPI, it is available for download here.

---

What’s new in version 3.9 (This version is for Sponge 6.0):

• API BREAKING: Removed support for TextSerializer serialization of texts and opted for format code serialization only
• Improved performance
• Better documented the Pattern argument in the PlaceholderService interface so that incoming regular expressions successfully match placeholders
• Added JavaScript function value(...) to the service variable to allow variables to be returned as String, an operable type in JavaScript
• Improved internal security
• Added ListeningExpansion interface to allow expansions to register as listeners through PlaceholderAPI
• Made the info command have a slightly less constrained output for placeholder tokens
• Changed server configuration (will be enabled by default so should continue to work unless you have it disabled, but you will want to update your configuration after loading this version with settings you want. The server = true/false node will no longer work)
• Added many player placeholders:
  • %player_stat_<minecraft statistic name>%
  • %player_language%
  • %player_gamemode%
  • %player_flying%
  • %player_health%
  • %player_max_health%
  • %player_food%
  • %player_saturation%
  • %player_x%
  • %player_y%
  • %player_z%

Check out the plugin wiki!

View the plugin on GitHub!

[Wundero]

Please do not click the version 5.2 post - it is invalid.

[Wundero]

I apologize for the recent inactivity, university exams were a stressful period of time. I am testing out building off of multiple SpongeAPI versions, however since nothing seems to change between 5.1 and 6.0 I will not release multiple build versions anymore. 3.10 will return to the old, single version system.

3.10 will likely be the last build for a while as it seems to cover most of what I can think of so far. If anyone wants to see features in this plugin aside from new placeholders, please post a reply to this thread or the issue on GitHub. If you want to suggest possible placeholders, you can post your ideas on this thread or on this GitHub issue. Note that I will check GitHub more frequently than the Sponge forums.

I will continue checking compatibility with SpongeAPI versions 5.1 and 6.0 when building and, if compatibility changes, will support both until 6.0 becomes a stable build.

I hope to begin rolling out placeholders for things outside of the SpongeAPI as soon as possible. You can check out the planned placeholders on the GitHub Issue mentioned above. Now that my summer break has arrived I should have much more time on my hands to create said placeholders.

EDIT: I should quickly mention that the statistic placeholder will be receiving a revamp in 3.10 that moves it to it’s own placeholder, so if you use %player_stat_...% note that it will not work as of 3.10.

[rojo8399]

A new version has been released for PlaceholderAPI, it is available for download here.

---

What’s new in version 3.10:

• Internationalization support
  • There is now a messages.conf json file which allows you to change all messages displayed by PlaceholderAPI.
• Allow deletion and modification of JavaScript files while running
• Moved %player_stat_...% to %statistic_...%. An explanation of how to use this will be added to the wiki ASAP.
• Added support for vanished players (must be using data keys) to be hidden from %server_online%
• Added reload command
  • Allows you to reload the whole plugin with /papi r OR
  • Allows you to reload an individual placeholder with 1/papi r `
• API: Added ReloadableExpansion to allow devs to know when their placeholder is reloaded and perform actions
• Added many placeholders to player:
  • %player_uuid%
  • %player_can_fly%
  • %player_exp%
  • %player_exp_total%
  • %player_exp_to_next%
  • %player_level%
  • %player_first_join%
  • %player_fly_speed%
  • %player_walk_speed%
  • %player_max_air%
  • %player_remaining_air%
  • %player_item_in_main_hand%
  • %player_item_in_off_hand%
  • %player_time_played%
  • %player_time_played_seconds%
  • %player_time_played_ticks%
  • %player_time_played_minutes%
  • %player_time_played_hours%
  • %player_time_played_days%%`
  • %player_direction%
• Performance improvements

Check out the plugin wiki!

View the plugin on GitHub!

[Wundero]

Looks like there was a minor mistake in the update notes, the individual placeholder reload command is papi r <placeholder>.

[rojo8399]

A new version has been released for PlaceholderAPI, it is available for download here.

---

What’s new in version 3.11:

• bStats support.
• Improved info command to allow more than 20 placeholders (by adding a clickable button).
• Actually made the reload command reload things properly, such as reloading all placeholders.
• Fixed %player_max_air% and %player_remaining_air% to reflect true minecraft values.
• Put the statistics expansion into it’s own configuration section.
• New messages for the plugin have been added and will be generated after one server restart.
• Fixed the gradle group to be me.rojo8399.placeholderapi from me.rojo8399. This likely won’t change anything until a proper maven repo can be deployed so this is more of a formality note.
• Minor fixes.
• API changes (non-breaking and non-urgent):
  • Added two new default methods to Expansion:
    • onValueRequest(Player, Optional<String>)
      • This returns an Object type which reflects the type of output. For example, %player% will return a String while %player_ping% will return an Integer. This is useful for direct type comparisons and lets you easily see true values of returned placeholders. This can return null.
    • onValueRequest(Player, Optional<String>, Class<T>)
      • This returns the generic type <T> specified by the Class<T> parameter passed into the method. This takes the output of the previous method and attempts to cast it to the desired type. If the type provided is null this will fail hard, but if it is not but the cast fails or something else goes wrong, the optional returned will be empty.

Check out the plugin wiki!

View the plugin on GitHub!

See the plugin’s statistics!

[Wundero]

Just as a note, this plugin is built against SpongeAPI 5.1 however in my testing it supported up to 7.0, which means it works for Minecraft versions 1.10.2, 1.11.2 and 1.12, depending on the version of Sponge you have installed.

[BrainStone]

Hi. I have a question (and potentially a bug)

Is it supposed to work like the PlaceholderAPI + BungeTablistPlus(_SpigotBridge)? Like being able to use the placeholders int BTLP through the sponge bridge? If not that would be very neat!

And it appears that relaoding doesn’t add new placeholders. Like I enabled economy and reloaded and it wasn’t there.

[SnowBlitzz]

How would you get player kill and death counts with the %statistic_xx%

I’ve tried %statistic_deathCount% for example, both with an uppercase C and without but it won’t work

[Wundero]

@BrainStone

Hi. I have a question (and potentially a bug)

Is it supposed to work like the PlaceholderAPI + BungeTablistPlus(_SpigotBridge)? Like being able to use the placeholders int BTLP through the sponge bridge? If not that would be very neat!

And it appears that relaoding doesn’t add new placeholders. Like I enabled economy and reloaded and it wasn’t there.

As far as I know BungeeTabListPlus does not support a Sponge build, but if it does, it would be up to the creator to use PlaceholderAPI, so I cannot say if it is supported.

As for reloading, the only placeholders I can add are placeholders that are internal to PlaceholderAPI. Any placeholders registered by other plugins, for instance Nucleus’ Gluon, cannot be added without a full restart yet. I am working on a feature that will allow them to run code when PlaceholderAPI reloads, but that will still require some time as the other developers would need to implement it.

@SnowBlitzz

How would you get player kill and death counts with the %statistic_xx%

I’ve tried %statistic_deathCount% for example, both with an uppercase C and without but it won’t work

EDIT: The internal statistic in Sponge for deathCount is deaths, so %statistic_deaths% is the working placeholder. I will still be writing a fix such that %statistic_craft_item%, %statistic_craftitem%, and statistic_craft.item% will all be valid statistics, though for simplicity’s sake I recommend using the default minecraft statistic names, such as craftItem (case is ignored). Of course, specifying item still requires . separation, like this: %statistic_craftitem.minecraft.planks%. I will not be changing the . notation for the specific stat tracking, just the overall stat name such that it is similar to the minecraft internal name.

[Wundero]

Before I forget, this is a warning about the next update I am going to post.

Update 4.0 is coming soon, and it includes some API breaking changes.

The biggest change to the API would be the Expansion interface, which has been modified to require a different method for placeholder parsing. Now, instead of implementing public Text onPlaceholderRequest(Player player, Optional<String> token), placeholders will be required to implement public Object onValueRequest(Player player, Optional<String> token). This allows for several improvements both internally and externally, and standardizes the appearance of certain objects in Text form. Of course, you could just return a Text object like before, but I recommend returning the representative type of the placeholder token parsed. For instance, %server_cores% would return an Integer object, while %server_motd% would return a Text object.

The next biggest change is the addition of RelationalExpansion and relational placeholder parsing. This new specification allows placeholders to change the returned value based not only on who the information is about but who is observing said information. For example, %rel_player_distance% gives the distance between the primary player and the observer, in number of blocks. Of course, this holds more power than just simple distance, and will become even more useful when this pull request is implemented. This change is breaking for any plugins (not that I expect there to be any because PlaceholderAPI provides the default implementation and should work for most if not all purposes) that implement PlaceholderService. All relational placeholders regardless of identifier must start with rel_ so as to denote that it is relational.

With relational placeholders there is also a minor change in the config, which is not there by default. It simply decides whether to parse relational placeholders like normal ones but for the observer. For example, if you parsed the placeholder %rel_player_displayname% and this option was off, it would output %rel_player_displayname%, however if it was on, it would output the displayname of the second player.

There are some other minor improvements coming with the next update as well, but I thought it would be important to mention these breaking changes and what they meant for the future of the plugin and any others that attach to it.

*As a note, I have been very busy recently so I have been unable to work very often on the plugin. This is likely to continue for the foreseeable future so any help would be appreciated, specifically with creating placeholders for other plugins. Every little bit counts, so if you have any ideas or comments, please let me know!