This plugin is for querying data about other plugins in a fast, convenient, centralized way.

Typical use cases

For a user

Let's say you have Info Menu. You want to show Currency, Raid Block and much more. Now you have to ask Info Menu developer to add these 2 things, right? And for so many basic things like players online, slots.. No! Info Menu should work with Placeholder API - that's it, you don't have to do anything else, all the placeholders we have are now available to you there. Same applies to any other plugin, for example - Smart Chat Bot, where you could easily insert your last and next wipe dates with time!

For a developer

Suppose you have a plugin that can provide player stats like population or currency, and you want to share that data across multiple plugins. To avoid calling a hook for each plugin as well as performance-unfriendly string formatting, you can instead have those plugins call one Placeholder API hook.

You can add your data with a string identifier such as "{population}", and Placeholder API will handle the rest! Placeholder API provides a convenient and performant bridge to share data between plugins.

How to use it?

Structure

{name:format!option}

• name is placeholder name displayed in list etc.
• format is the way to display the value.
• option is a parameter passed to the plugin, custom value.

Built-in formats

• bool(True/False) - Yes|No, show first option if true, second otherwise.
• string(Text) - upper, converts text to uppercase. lower, converts text to lowercase.

Built-in options

• DateTime(date and time) - local, append Local Time Offset from configuration.

Examples

1. Display player's continent code: {player.address.data!continent.code}.
2. (Rust) Display yes or no, whether a jump button is pressed: {player.input.isdown!jump:yes|no}.
3. (Rust) Get maximum hunger level: {player.metabolism!calories;max}.
4. Display current local date: {date.now!local}.
5. Display current year and month name: {date.now:yyyy MMMM}

How to use formats?

There are many built-in formats in C# that this plugin is using.

• Numeric (Standard/Custom)
• Date and Time (Standard/Custom)
• TimeSpan (Standard/Custom)
• Enumeration

Commands

• placeholderapi.list [Search query] - List all existing placeholders (Requires a permission: placeholderapi.list).
• placeholderapi.test (Text) - Process placeholders for a given string, options in the end of command: player X and ignorecache true(Requires a permission: placeholderapi.test).

Permissions

• placeholderapi.list - Usage of list command.
• placeholderapi.test - Usage of test command.

For Developers

Hooks

private void OnPlaceholderAPIReady(bool addressRequests)
{
    // TODO: Register placeholders, get any actions like GetProcessPlaceholders
    if (addressRequests)
        Puts("This server requests address data via ip-api.com!");
}

private void OnAddressDataRetrieved(IPlayer player, bool isCached)
{
    // TODO: Kick the player, send welcome message
}

API

Address Data

private JObject GetAddressData(string address)
// Returns address data as a JObject.
// Available fields can be viewed here: [https://ip-api.com/docs/api:json](https://ip-api.com/docs/api:json).
// These fields will not be available: query, reverse and message.

Placeholders

private void ProcessPlaceholders(IPlayer player, StringBuilder builder, bool ignoreCache = false)
// Run placeholders for a StringBuilder

private object GetProcessPlaceholders(int version = 0)
// Get an action for processing placeholders for higher performance
// 0 - Action<IPlayer, StringBuilder>
// 1 - Action<IPlayer, StringBuilder, bool>

private object EvaluatePlaceholder(IPlayer player, string name, string option, bool ignoreCache = false)
// Evaluate a placeholder value without any custom formats and get the value

private object GetEvaluatePlaceholder(int version = 0)
// Get a function for evaluating placeholders for higher performance
// 0 - Func<IPlayer, string, string, object>
// 1 - Func<IPlayer, string, string, bool, object>

private bool ExistsPlaceholder(string name)
// Returns true if a placeholder with such name already exists

private bool AddPlaceholder(Plugin plugin, string name, Func<IPlayer, string, object> action, string description = null, double cacheTTL = double.NaN, bool cachePerPlayer = true)
// Add a placeholder for plugin (required) with a specified name and optional description
// Action should return evaluated value for IPlayer and string that is an option given
// Cache TTL is time to live for cache. Set to NaN or negative value to ignore. Set to MaxValue for no cache expiration.

Donate

Click me

Credits

• MJSU - Much help with ideas, 7D2D, some Regex and other stuff.
• 1928tommygun - Best description ever.

(AKA PAPI)