misticos
Centralized location to query data from other plugins. Streamlined, convenient, and performant.

Supported Games

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.

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.

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)

MIT License


Copyright (c) 2019 misticos


Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:


The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.


THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.