Welcome to the first in a series of code recipes, or challenges that we’ll be doing with ScriptCraft. In this challenge, we’ll be creating a random greeting that will display when a player joins our server. This code challenge will familiarize you with several fundamental concepts that we’ll be using in the other challenges that will follow.

Before we begin, let’s make sure we have our SpigotMC server, and the Java Minecraft client running, and are ready to start adding things to the folder where our server is installed. To do this code challenge, you will need to have already gone through the steps required for getting your SpigotMC server running with ScriptCraft. You should have a server folder that looks something like this (my server folder is named SpigotMC):

NOTE: If you have not already done the initial setup required to use ScriptCraft to create your own plugins, follow the steps on the ScriptCraft page under the heading GETTING STARTED WITH SCRIPTCRAFT before continuing.

The following concepts will be covered in this challenge:

• Plugins & Modules
• The JavaScript Math object.
• Arrays in JavaScript
• Looping statements in JavaScript
• The ‘requires()’ method
• Listening for Events

First a word on the difference between a module and a plugin:

A module is code that is not auto-magically available in game, that is – it’s not available ‘globally’. A module is only available within the scope that declares a reference to that module. Even if we ‘export’ a method from the module, it is not something that can be called using the ‘js’ command in game, or used within another method, unless we have created a reference to the module in order to include it in our code. Modules have to be ‘loaded’ into other code in order to be available, using the ‘requires’ method. You’ll see this in action in our ‘MyPlugin.js’ plugin code.

On the other hand, plugins are available globally, whatever we export from a plugin is available to be called in-game using the ‘js’ command, and plugin methods and variables are also available globally. NOTE: this means we have to be careful when naming a method or variable in the global scope of our plugin code, since there may already be something that has the same name, which will cause an error.

So generally it goes like this: modules are code we can use where/when we need them by referencing them in our code, whereas plugins are code that can use the modules they need, and are available in-game by default.

Step 1: Modules

The first thing we need is our own folder in the scriptcraft/modules folder where we’ll be saving the modules we create. It doesn’t matter what our folder is named, as long as it is in the scriptcraft/modules folder, but for the purpose of these tutorials, we’ll name our folder ‘MyModules’  – so create a new folder named ‘MyModules’ in the scriptcraft/modules folder for yourself, it should look like this:

We’ll need to create the following modules, each one is a JavaScript file we’ll create, that we’ll save in our scriptcraft/modules/MyModules folder:

Now for the code we’ll need in each one.

The greetings.js module:

In the greetings module, on line 1 we first have a variable called ‘greetings’ which holds our array of different greetings. We’ll be randomly selecting a greeting from the array to put in front of the name of the player who joins the server when they join.

In the ‘GetRandomGreetings’ function, on line 5 we initialize a variable named ‘index’ to -1, this is the index we’ll use to access an item within our array. Within a ‘while’ loop we use the JavaScript Math object’s Math.random() method and the Math.floor() method, along with the ‘length’ property of our array to get a random number between 0-5, and we store what’s returned in our ‘index’ variable.

Why use the while loop? Glad you asked 🙂

Notice that although our array has 6 items in it, the index for the first item is zero – this is the way all arrays in JavaScript, as well as in most other languages work: the first index in the array is 0, the second item is at index 1, etc. In other words:

greetings[0] = "Hello"
greetings[1] = "Hi"
greetings[2] = "Howdy"
etc...

This means that although the .length property of our array will return 6 (the number of items our array has), the index we use will need to be a number from 0 to 5.

So, since we can end up with a random index that is outside the bounds of our array of greetings (we have six items in our greetings array, but the Math.random() method can produce a number that is higher than 5) we use a while loop to keep generating an index until we have one that falls within the bounds of our array.

We could have dealt with this differently, for example, we could have just generated an index using:

var index = Math.floor(Math.random() * greetings.length - 1);

…and then adjusted it if the number produced was outside of the bounds of our array:

if(index > 5)
{ 
   index = 0; 
}

…but then our random greeting would not appear nearly as ‘random’ – so I chose to use the while loop to keep generating numbers until we had one that does fall within the range of 0-5.

The messenger.js module:

 

 

 

 

 

 

 

 

 

In the messenger module, we export one function called ‘SendMessage’ using exports.say – this means things using our module will use ‘say’ to use this method. This module gives us a generic way of sending a message to a specific player using that player’s name.

The function receives two parameters: ‘playerName’ and ‘message’. On line 4 we use the ‘require(moduleName)’ method to inject the code for a module into our function so we can use it – in this case the ‘utils’ module. The ‘utils’ module is something that came packaged with ScriptCraft which we can use – in fact all the modules included in ScriptCraft are things that we can use…we just need to know how to include them in our code using the ‘requires’ method, and what things they ‘export’ so we know how to call them, and what parameters may be expected.

Next, on Line 6 we use the utils variable we initialized to use the ‘player’ method of the utils object – which returns us a player object for the player name we pass into it – assuming that player is currently logged into the server.

Then, on lines 8 through 11, we do a null check, and if we have a player object, use the ‘sendMessage’ method of the player object to send a message to that player.

Step 2: Our plugin

Just like we created a folder to hold our modules in the scriptcraft/modules folder, we’ll also create a folder to hold our plugins in the scriptcraft/plugins folder:

 

 

 

 

 

 

In this folder, we’ll create a JavaScript file named: ‘MyPlugin.js:

 

 

 

 

 

 

Here is the code we’ll need for our plugin:

 

 

 

 

 

 

 

 

Here we have a function named ‘greet’ which is what we’ll use in our event listener. The method receives one parameter: ‘playerName’.

On lines 3 and 4 we create references to our two modules which we store in variables named ‘messsenger’ and ‘greetings’ – this makes our module codes available for use within our function.

On line 6 we use the exported ‘getGreeting’ method of our greetings module to get a random greeting. On line 8 we use that greeting along with the ‘playerName’ that was passed into our function to create the greeting message we’ll want to pass to the player – this we store in a variable named ‘message’.

On line 10 we use our ‘messenger’ module’s exported ‘say’ method to pass our message to the player.

Finally, outside of our function, on lines 13 through 15, we use the ‘events’ object which ScriptCraft provides to us to “listen” for the ‘playerJoin’ event. This bit of code creates a listener for the playerJoin event that will execute whatever code we have in it’s body (Line 14) whenever the playerJoined event is fired off by the server – that is, everytime a player joins our server.

On Line 14 – you can see that whenever the playerJoin event is received, we will use our ‘greet’ function to send the player that joined a greeting! Notice that we get the player’s name, which we need to pass into our greet function, from the ‘evt’ object that get’s passed to us by the playerJoined event. There are other properties that may be useful to use in the ‘evt’ object – but for this purpose, all we need is to use the ‘evt.player’ object’s ‘name’ property to get the name of the player who just joined the server.

That’s it! With this code all setup – after doing a ‘js refresh()’ to be sure our new code is loaded into our server – the next time someone joins the server, they will receive a randomly selected greeting!