Creating Custom Placeholders

skript-placeholders provides the ability to create custom placeholders that can be used with other plugins with placeholder support.

About Custom Placeholders

Custom placeholders are a top-level element, meaning they must be created at the "top" of your scripts (in the same way you would use an event).

Every placeholder must return a result, which is always a string (text) value. This result may be accessed or changed using the result expression:

[the] [placeholder] result

Tip

Though the result of a placeholder must be a string, it is possible to set the result to any type of value, as the addon will automatically convert the value into a string.

Creating a Custom PlaceholderAPI Placeholder

For this addon, PlaceholderAPI placeholders are broken up into two parts: the prefix and the identifier. These two parts are separated by the first underscore in a placeholder. The prefix also represents the name of expansion that will appear in PlaceholderAPI. Given a placeholder like skriptplaceholders_name, skriptplaceholders is the prefix, and name is the identifier. These values can be obtained using the following expressions:

[the] placeholder
[the] [placeholder] prefix
[the] [placeholder] identifier

To create a custom PlaceholderAPI placeholder, you must use the following structure pattern to declare the prefix:

(placeholder[ ]api|papi) placeholder (with|for) [the] prefix %*string%

This pattern can be simply expressed as:

placeholderapi placeholder with the prefix <text>

Using this structure and the expressions mentioned above, we can create a simple placeholder:

placeholderapi placeholder with the prefix "skriptplaceholders": # The prefix/expansion in PAPI is 'skriptplaceholders'
  if the identifier is "hello": # The placeholder is 'skriptplaceholders_hello'
    set the result to "Hello %player%!"

The code above creates a simple placeholder, skriptplaceholders_hello, that evaluates to a simple message: Hello <player>!. In game, we can use the papi command to evaluate it:

Tip

It is possible to have multiple placeholder structures for the same prefix. The addon will check against each one until it is able to evaluate a result.

Creating Relational Placeholders

Important

Relational placeholders always start with rel. For example, given a relational placeholder with the prefix skriptplaceholders and the identifier equality, the full placeholder is rel_skriptplaceholders_equality.

It is also possible to create relational placeholders, which evaluate based on two player inputs. The pattern is almost identical:

(placeholder[ ]api|papi) relational placeholder (with|for) [the] prefix %*string%

This pattern can be simply expressed as:

placeholderapi relational placeholder with the prefix <text>

Additionally, when creating relational placeholders, there are two expressions available to obtain the player inputs:

[the] first player
[the] second player

Note

For relational placeholders, the players will always be online.

Using this structure and these expressions, we can create a simple relational placeholder:

placeholderapi relational placeholder with the prefix "skriptplaceholders":
  if the identifier is "equality":
    if the first player is the same as the second player:
      set the result to true
    else:
      set the result to false

The code above creates a simple placeholder, skriptplaceholders_equality, that evaluates to true or false, depending on whether the first player and the second player are the same player. In game, we can use the papi command to evaluate it:

Creating a Custom MVdWPlaceholderAPI Placeholder

Unlike PlaceholderAPI, placeholders in MVdWPlaceholderAPI are not broken up into prefixes and identifiers. Additionally, they may not always contain an underscore.
To create a custom MVdWPlaceholderAPI placeholder, you must use the following structure pattern to declare the prefix:

(mvdw[ ]placeholder[ ]api|mvdw) placeholder [with [the] name|named] %*string%

This pattern can be simply expressed as:

mvdwplaceholderapi placeholder named <text>

Using this structure and the expressions mentioned above, we can create a simple placeholder:

mvdwplaceholderapi placeholder named "skriptplaceholders_hello": # The placeholder is 'skriptplaceholders_hello'
  set the result to "Hello %player%!"

The code above creates a simple placeholder, skriptplaceholders_hello, that evaluates to a simple message: Hello <player>!.