Advanced Scripts

Arguments

When calling a JavaScript placeholder, arguments may be supplied for extra functionality. These arguments are included after the placeholder name, and are separated by commas (,) by default, can be changed via configuration

When included, the arguments are passed to the script through an array called args.

For example, the arguments in the placeholder %javascript_example_test,3,args% would be test, 3, and args.

Here is an example that returns a random number between the given arguments.

var min = 1;
var max = 25;

function randomInteger() {
   if (args.length == 2) {
       min = args[0];
       max = args[1];
   }

   var random = Math.random() * (max - min);
       random += min;

   return Math.floor(random);
}

randomInteger();

Note that it is a good idea to include defaults, or at the very least check that the arguments exist before using them. In the example above, the defaults are min = 1 and max = 25. So, if the above script were called without any arguments, a random integer between 1 and 25 would still be returned.

Examples (assuming the identifier is called randomintbetween):

• %javascript_randomintbetween_5,100% would return a random integer between 5 and 100.
• %javascript_randomintbetween_200,5000% would return a random integer between 200 and 5000.

Placeholders could also be used as arguments. Instead of using %placeholder% you'll have to use {placeholder}.

Example (assuming the identifier is called check):

• %javascript_check_{vault_rank}% would check if the player has the a specific rank and would return something based on their rank.

PlaceholderAPI.static.setPlaceholders() could also be used to parse placeholders inside the javascript placeholder.

Example:

var kitName = args[0];
var placeholder = "essentials_has_kit_" + kitname;
var hasKit = PlaceholderAPI.static.setPlaceholders(BukkitPlayer, "%" + placeholder + "%");

function hasKit(){
  if(hasKit == "yes"){
    return "&aTrue";
  }
  return "&cFalse";
}

hasKit();

This example will take a kit name as an argument and check if the player has access to that kit and return True or False based on the input. It also parses the placeholder(essentials_has_kit_kitname) for the BukkitPlayer which is the player that the javascript placeholder is parsed for.

Player Information

When a placeholder script is called, the player that is passed to the Javascript-Expansion is also passed to the placeholder script. This player can be accessed with BukkitPlayer. After receiving, you can access all of the player methods included in the Spigot API.

Here is an example that will return the player's name and their health.

var player = BukkitPlayer;

function playerNameHealth() {
	var name = player.getDisplayName();
	var health = player.getHealth();

	return name + " has " + health + " health!";
}

playerNameHealth();

Produces: when ran.

Server Information

Just like the player, the server is also passed along to the placeholder script when called. The server may be accessed using BukkitServer. After receiving, you can access all of the server methods included in the Spigot API.

Here is an example that will display the Server's MOTD through a placeholder.

var server = BukkitServer;

function getMotd() {
	var motd = server.getMotd();

	return motd;
}

getMotd();

Produces: when the server's MOTD is "A Minecraft Server".

Storing Data

Storing data from within the placeholder script is quite easy. When a placeholder script is called, a Data object is passed to it. Whenever the script modifies the object, it is modified in Javascript-Expansion as well, and then saved to a data file when the expansion unloads.

Here is an example script that stores how many times a placeholder is viewed by the current player.

// Location keys are just like YAMLConfiguration keys
var dataLoc = "%player_name%.viewed";

function viewCount() {
	var views = Data.exists(dataLoc) ? Data.get(dataLoc) : 0;

	views++;

	Data.set(dataLoc, views);
	Placeholder.saveData();

	return views;
}

viewCount();

Produces: when parsed for the first and second times for a given player.

NOTE: If you have a straight-forward string key, you can use DataVar instead of Data.get(String):

function viewCount() {
	var views = DataVar.constantNum  // in replacement of Data.get("constantNum")

	return views;
}

viewCount();

Valid Methods:

• Data.getData() returns a Map<String, Object> of the entire placeholder script's data.
• Data.clear() removes all data.
• Data.exists(key) returns true if a key exists; else false.
• Data.get(key) returns the value stored under key.
• Data.remove(key) removes a key from the data.
• Data.set(key, value) stores a value under key.
• Data.setIfNull(key, value) stores a value under key only if this data doesn't exist in cache.
• Data.isEmpty() returns true if the data is empty; else false.
• Placeholder.saveData() saves the current data state to the data file.