JavaScript in Bukkit

ChatControl Pro supports dynamic, high performance variables you can create! They can be used across the plugin, for example in formatting your chat or death messages. Currently, the folder /variables stores all custom variables in each separate yml file.

Variables can not only be used to display information, but because you can write your own full code in JavaScript to display them, they can also do whatever you would wish for your players/server, such as sending sounds or spawning monsters.

You can use command "/chc inspect" to enumerate all methods or fields in a class, which lets you to make new variables easier.

Requirements

It is recommended you know a little bit of Java, knowing how to access methods in Bukkit, and have some basic knowledge of JavaScript itself, or at least know how to use Google properly and adjust and debug others' JavaScript code to your needs.

There is an extensive guide on how to code Javascript for Java on these locations:

• Unofficial Nashorn Tutorial
• Official Nashorn Tutorial

Setting up

Each variable residues in its own file in the variables/ folder. Before we create our own one, let's have a look at one of the default variables {item} that shows the item the player is hovering in his hands.

# -------------------------------------------------------------------------------------------------
# Getting the item the player has in his hands.
# -------------------------------------------------------------------------------------------------
#
# The key we look for in the chat, example:
# chat message: "Hello everyone, I have an [item] in my hand"
#
Key: "{item}"
#
# The value the key will be replaced to.
#
# This uses JavaScript and must return a boolean value
#
# If you have no idea how to code in JavaScript you most likely take
# no benefit of custom variables, but if you do, please see the following
# article for basic explanation: https://winterbe.com/posts/2014/04/05/java8-nashorn-tutorial/
#
Value: "player.getItemInHand().getType()"
#
# What ItemStack should be displayed when we hover the mouse
# over this variable in the chat
#
Hover_Item: "player.getItemInHand()"
#
# What texts should be displayed when we hover the mouse
# over this variable in the chat
#
#Hover: []
#
# What website URL should be opened when we click with the mouse
# on this variable in the chat
#
#Open_Url: ""
#
# What command should appear in the player command box on his screen
# if he clicks on this variable in the chat
#
#Suggest_Command: ""

The first settings key you must define is "Key", that simply means what you need to put in the chat or a format as the variable. In this case, it is "{ping}."

The second mandatory key is "Value", that is simply a JavaScript code that will return the value such as "Hello World" and replace our "{ping}".

Multiline messages

Do this if you if want to show message on multiple lines:

Available options:

Two two mandatory keys, "Key" and "Value" are discussed above. Besides those, you can write the following options to your yml file directly:

Hover_Item

Mandatory: false
Description: What item should be displayed when we hover the mouse over this variable in the chat?
Return value: Bukkit ItemStack class
Example: "player.getItemInHand()"

Hover

Mandatory: false
Description: What text or texts should display when we hover the mouse over this variable in the chat?
Return value: String or array of Strings
Example: "Hello World"
Another example: |-
                 Hello this is a multi-line
                 text that will show on two lines!

Open_Url

Mandatory: false
Description: What website should be opened when we click the mouse on this variable?
Return value: String
Example: "https://mineacademy.org"

Suggest_Command

Mandatory: false
Description: What command should appear in the player's command box when we click the mouse on this variable?
Return value: String
Example: "tell kangarko Hello there!"

Run_Command

Mandatory: false
Description: What command should run as the sender when he clicks the mouse on this variable?
Return value: String
Example: "tell kangarko Hello there!"

Sender_Permission

Mandatory: false
Description: What permission must the message sender have in order for this variable to display to him?
Return value: String
Example: "my.example.permission"

Receiver_Permission

Mandatory: false
Description: What permission must the message receiver have in order for this variable to display to them?
Return value: String
Example: "my.example.permission"

Tips

You can use the variable "player" in JavaScript to get the Bukkit Player class.

Multi-line codes

To put a text on multiple lines, simply prefix it with |- and then type on multiple lines after that. Example:

Value: |-
       &cThis text will
       &cshow on multiple
       &clines &6easily

Using variables from PlaceholderAPI in your custom variable

Here is an example on how you can combine other plugins' variables to mix up your own variable depending on another variable's output!

Value: |-
  getTagOrPrefix(); // call the function below that returns the tag or prefix

  function getTagOrPrefix() {
      // replace with the tag
      var tag = "{deluxetags_identifier}";
     
      // if the tag is empty, return prefix, else return tag with [] around it.
      return tag == "" ? "{pl_prefix}" : "[" + tag + "]";
  }

Accessing NMS easily

Value: |-
  // acts if as you were inside of CraftPlayer class, so NMS is directly available
  player.getHandle().ping

Let's analyze this code really quickly:

1. The script begins with the declaration of the Value itself. It can have unlimited size thanks to the |- functionality.
2. The code itself - contains predefined "player" variable you can use (if present) to get the player instance. This instance represents CraftPlayer in Bukkit in Java, so you can easily access NMS internals without even specifying those pesky 1_16_R1 numbers every time!