Script Matcher

SuperbVote includes a script matcher that will run the function matchVote() of a JavaScript file of your choice. This is excellent for adding extra matching SuperbVote doesn't include out of the box.

Note that your script will be run asynchronously, and it will not be safe to access resources normally accessed in the main thread. The Nashorn engine also has a non-trivial warmup time, so matching might be delayed the first time you get a vote. (Make sure to look at the "JavaScript environment" section, since it is different than what you may be familiar with.)

Example matcher

Service name is palindrome

function matchVote(ctx) {
    return palindrome(ctx.vote.serviceName);
}

function palindrome(word) {
    var cleaned = word.toLowerCase().replace(/[^a-z0-9]/g, "");
    return cleaned.split("").reverse().join("") == cleaned;
}

Current player IP address is 127.0.0.1

Note: While this doesn't require require-online: true, it is highly recommended.

function matchVote(ctx) {
    var player = server.getPlayer(ctx.vote.uuid)
    if (player == null) return false
    return player.address.address.hostAddress === '127.0.0.1'
}

JavaScript environment

You are in a standalone JavaScript environment (that means no DOM or Node.js bells and whistles, but see below for more detail).

Bare ECMAScript 5 will work fine, and functionality that Nashorn adds (such as Java.type()) works as well, so you can access the Bukkit API.

For convenience, the current Bukkit Server is exposed as the global server, and there is a helper method callSync(fn) that runs the specified fn in the main server thread and returns its result (in a blocking fashion).

Your best resources for working with this environment include the Nashorn documentation, Mozilla's comprehensive JavaScript documentation and the Spigot API reference.

API

function matchVote(ctx) - called when SuperbVote receives a vote. This function is blocking.

With 0.5 and higher, you can return any truthy JavaScript object, and SuperbVote will assume that the vote matched. Prior to 0.5, you must return true or 0 for the vote to match.

Context object

The ctx object passed into your match contains two properties:

• vote: Vote object, described below.
• currentVotes: The number of votes the player currently has, excluding the vote to be added. (That is, if this will be the first time the player has voted, this will be 0, not 1.)

Vote object

The vote object inside the ctx object contains the following properties.

• String name
• UUID uuid - Java object
• String serviceName
• Date received - Java object
• boolean fakeVote - Indicates a vote generated by /sv fakevote
• String worldName