This page is only intended to provide the basics of using javascript for scripting Custom Stuff item and block events. If you want to know about functions added by Custom Stuff, please refer to the functions section on the Wiki_Content page. Specific examples of code for items can be found in the examples catagory page.

Before I start, I want to point out that all the code listed below will be formatted as if it were in a .script file. For those who do not know how to call these scripts from your event, here are a few examples for how to do just that.

onRightClick = "mod.loadScript('rightclickcode.script');";
onDestroyedByPlayer[0] = "mod.loadScript('random.script');";
onActivated[0] = "mod.loadScript('random.script');";

Almost all code that will be included on this page can be used directly in the block and item file's events, but can sometimes be harder to read and understand. To add the code directly in an event, remove any line breaks (where you hit enter) and change any " " to ' ' or add / before each of the double quotes except the first and last.

The Absolute basics of Javascript

First, and most important of all, javascript is case sensitive. This means that randomnumber and RandomNumber would be two entirely different variables and can contain two seperate values. It also means that if a function has a capital in it, there is a chance you would have an error if you forget to capitalize it correctly.

Javascript code is usually activated in order from top to bottom. A Javascript block is a set of javascript code contained within curly brackets { } that is executed together. Although you can include the curly brackets for regular coding, it would not affect the code much. A javascript block is usually used when using functions or conditions. More about functions and contitions will be discussed later.

Another feature that javascript has is the comment. A comment can be indicated by using a double slash // before the comment. This version of the comment only lasts for one line, but is useful for leaving quick notes about what code is supposed to be.

//Simple grass recipes
mod.addRecipe("2 1", 1, 2, 295, 3); 		//seeds over dirt

Notice that comments can be used either on their own line, or at the end of another line. Be aware though that this comment will make everything after it on the same line be considered a comment. This means that the // can be included at the start of a line of code to cause that line of code to be ignored. This can be useful when trying to isolate a problem in a script.

Javascript Variables

If you have had algebra, you probably remember learning about variables and how they can contain values. You probably also learned things like if x=4 and y = 8, then z=x+y would make z = 12.

Variables such as these are also used in javascript for holding values for later use. Unlike in algebra though, these variables can contain not only numbers, but also text. When text is used in code, it is called a string and needs to be contained with quotes " " to prevent being considered code.

Created a variable in javascript is usually called "declaring" a variable. You can declare a javascript variable by including the var keyword like in the examples below.

var x;
var blockName;

After declaring the variable, the variable is empty, you can manually set this later or you can set the value at the same time it is declared.

var x = 14;
var blockName = "grass";

In this example, the variable x contains the number 14 and blockName contains grass as a string. If x was declared as var x = "14";, then the 14 would instead be considered a string, which is basically text instead of a number.

When setting the value of a variable, you are not limited to simply entering the exact value you want. Just like in algebra, you can include mathmatical operations and other variables to receive a different value. Some examples can be seen below.

x = 4 + 7;   //makes x=11
x = y * 2;   //if y=3 then x=6

Also, it is possible to assign values to an undeclared variable. This will cause the variable to be automatically declared as a global variable. Assigning values to undeclared variables is as easy as writing variableName = value; though it is better to always declare the variable yourself.


Several types of operators are available in javascript. Arithmetic operators, assignment operators, comparison operators, and logical operators will all be covered in this section.

Arithmetic operators

Arithmetic operators such as + can be used to determine a value rather than assign a value. The examples in the table below use x=8 and y=5 as the starting values for each example.

Operator Descripton Example Result
+ Addition x=y+4; x=9 y=5
- Subtraction x=y-4; x=1 y=5
* Multiplication x=y*3; x=15 y=5
/ Division x=y/2; x=2.5 y=5
% Modulus (divison remander) x=y%2; x=1 y=5
++ Increment x++; x=9 y=5
x=++y; x=6 y=6
x=y++; x=5 y=6
-- Decrement x--; x=7 y=5
x=--y; x=4 y=4
x=y--; x=5 y=4

Assignment Operators

Assignment operators such as = are used to assign those values to the javascript variables. The examples in the table below use x=8 and y=5 as the starting values again.

Operator Example Same As Result
= x=y; x=5
+= x+=y; x=x+y; x=13
-= x-=y; x=x-y; x=3
*= x*=y; x=x*y; x=40
/= x/=y; x=x/y; x=1.6
%= x%=y; x=x%y; x=3

Also, you can use the + symbol to add together two strings. this will attach the 2nd string to the end of the first string without adding any spaces. If you want to have a space, you need to add one at the end of the first string, add to the start of the second string, or manually add one in between. Here is an example of combining several strings for the sendMessage function of custom stuff.

var firstName = "Zerg";
var lastName = "Ling";
player.sendMessage("My name is " + firstName + " " + lastName + ".");

The result from this example is that the player will see "My name is Zerg Ling." when the function is run.

Also, if you add a number and a string, the result will always be a string, even if the string was '5' and you added 6. To change a string number back into a regular number, just multiply by 1 like so:


Comparison Operators

A comparison operator is used to determine if a condition is met. This will become more useful when learning about the if...else statement later in this article. The examples in this table below use x=5 as the inital value.

Operator Description Example
== is equal to

x==8 is false
x==5 is true
x=="5" is true

=== is exactly equal to (value and type)

x===5 is true
x==="5" is false

!= is not equal to x!=5 is false
> is greater than x > 7 is false
< is less than x < 7 is true
>= is greater than or equal to x >= 7 is false
<= is less than or equal to x <= 7 is true

Remember, = is to assign values while == is to compare values. Switching these two operators can cause some unintentional side affects.

Logical Operators

Operator Description Example
&& AND (x > 7 && y < 4) is false
"||" //remove quotes
(x > 7 || y < 4) is true
! NOT !(x==y) is true

If...Else Statement

  • if - The code for this statement only executes if a condition is true.
  • if...else - Executes one set of code if the condition is true, or a different set of code if the condition is false.
  • if...else if...else - same as if...else but checks a different condition for a different set of code before defaulting to else.
//code executed if condition1 is true.
else if(condition2)
//code executed if condition1 is false but condition2 is true.
//code if both condition1 and condition2 are false.

An example of the if statement in use.

if(world.getBlockId(position) == 3)
world.setBlockId(position, 2);

This example checks if the block is dirt. If the block is dirt, it will change it to grass. If statements can often be found in an item or block file's events for simple amounts of code. The same script show above can be used in an event if kept to one line like the example shown below.

rightclick="if(world.getBlockId(position) == 3){world.setBlockId(position, 2);}";

For more about javascript, please use Google to find more javascript tutorials or go to w3schools, which was used as a reference for most of the above article. A few other useful functions can be found below, found either through other examples on the wiki or through search engines. If an advanced javascript tutorial is posted on the wiki, a link to it will be add here.

Other Useful Functions

Some other useful functions that could be useful for Custom Stuff scripting. Italicized text in the list below means that the words should replaced with the appropriate values.

  • Math.random() - generates a decimal between 0 and 1, though can never generate exactly 1.
  • Math.round(number) - rounds a number to the closest whole number.
  • Math.roof(number) - round number up, so 2.0001 would become 3 but 2 would still be 2.
  • Math.floor(number) - rounds number down, opposite of roof.

Getting a true random number.

The Math.random function can be useful by itself, but it is much easier to work with whole numbers. Normally to get whole numbers, you would just use Math.round, but if you use this while trying to get a random number, the lowest and the highest number would have about half the chance to appear as the other numbers. The option does not work either because there is an extremely slim chance you can still receive 0, even though normally you would only get higher values. To solve this, you can use the floor function like below.


The Math.random()*20 will generate a number between 0 and 19.99999_, which is then rounded down, giving a value between 0 and 19, a total of 20 numbers. If 1 to 20 is desired, instead using the following.


These random numbers can be used in a conditional to allow for a chance to activate rather than always activating under certain conditions.

if(Math.floor(Math.random()*100) < 5)
{ some code }
//OR like so
if(Math.floor(Math.random()*20) == 0)
{ some code }

The above two versions will cause the if statement to be true only 5% of the time, meaning there is a 95% chance the code will not run. This can be useful for things such as plants that should not always activate.