Usage
The first step is creating a file for your project. The default file extension for MineScript files is .ms
,
and all code for your datapack should be in that file. You should also create a file with the same name, but with
the extension .info
, where you'll write the name of your datapack in the first line and its description on the second. There's an .xml
file in the main directory that can be used as a language file for Notepad++, if you choose to use it as your default editor.
Basics
One important thing you should remember about MineScript is that it has two types of instructions: those that run inside Minecraft itself (and always start
with $
), and those that run while the datapack is being created. For example, the following instruction:
print("Hello world!")
will run before the datapack is built, but this one:
$print("Hello world!")
will only run once you load the datapack is loaded onto your Minecraft world.
Syntax
MineScript syntax is pretty similar to most programming languages, except in its use of the $
symbol. Let's see what it can do:
Basic arithmetic
x = 2
y = 3 * x
z = 1 / (2 + y)
print(z)
These are all valid expressions and MineScript will output the result 0.125
.
As of this version, there are only 5 arithmetic operators:
Operation | Meaning |
---|---|
+ |
Addition |
- |
Subtraction |
* |
Multiplication |
/ |
Division |
% |
Modulo |
^ |
Exponentiation |
If / Else statements
if (1 + 2 == 3) {
print("1 + 2 = 3") # This will run
} else {
print("Something's gone wrong here...") # This won't run
}
If statements will run the code inside the curly brackets if the expression inside the
parentheses evaluates to anything other than 0
or false
, so this will still work:
if (1 + 2) {
print("1 + 2") # This will run
}
There are 6 different comparison operators:
Operation | Meaning |
---|---|
< |
strictly less than |
<= |
less than or equal |
> |
strictly greater than |
>= |
greater than or equal |
== |
equal |
!= |
not equal |
These operators will throw an error when used to compare objects of incompatible types (for example, and array and an integer).
You can also use &&
- the AND operator - and ||
- the OR operator - to add different conditions to one if statement.
For loops
For loops are setup similarly to java, using the following syntax:
for (i=0; i<10; i++) {
print(i) # This will run 10 times and print the numbers from 0 to 9
}
i=0
initializes the variable i
, i<10
means the code within the brackets will run until this condition is no longer true, and i++
updates
the variable each in iteration, in this case incrementing its value by 1.
While loops
While loops are also setup similarly to java, using the following syntax:
i = 0
while (i < 10) {
i++
print(i) # This will run 10 times and print the numbers from 1 to 10
}
i < 10
is the condition, and the loop will run while this is true.
Functions
Functions can be used to reduce the ammount of code you need to write in repetitive tasks, or just to help you organize your code better.
function printsum() {
result = 0
for (i=0; i<len(arr); i++) {
result += arr[i]
}
print(result)
}
arr = [2,3,4]
printsum() # Output 9 (2 + 3 + 4)
This function will print out the sum of all elements of an array arr
, by iterating through all of them. Functions can also
return a value, using the keyword return
.
function sum(a) {
result = 0
for (i=0; i<len(a); i++) {
result += a[i]
}
return(result)
}
arr = [2,3,4]
print(sum(arr)) # Output 9 (2 + 3 + 4)
Include
The include
keyword is a special keyword that lets you include all the code from another .ms
file into your current project.
It should always come before anything else on your code. An example would be:
File myotherproject.ms
$function afunction() {
$print("Loaded from another file")
}
File myproject.ms
include myotherproject
$function load() {
$afunction()
}
In-game operations
Let's now take a look at how this code would work if run inside the game.
All code that is to run in-game should be inside a function (which will later be converted into an actual Minecraft function file),
and the functions tick
and load
are reserved - tick
will run every tick (about 20 times/second) while load
will run only when the datapack is loaded.
Basic arithmetic
$function load() {
$x = 2
$y = 3 * $x
$z = 1 / (2 + $y)
$print($z)
}
Just like before, these are all valid expressions and will run, but only once you load the datapack onto your world. Unlike before, the result will be 0
,
because Minecraft scoreboard
objectives do not support floating-point numbers.
If / Else statements
$function load() {
$x = 3
$if($x == 3) {
$print("1 + 2 = 3")
} $else {
$print("Something's gone wrong here...")
}
}
If and else statements function as explained before, with the only difference being you can use in-game variables inside the parentheses:
$function load() {
$x = 2
$if ($x > 1) {
$print($x, " is greater then 1")
}
}
For loops
The syntax for these loops is exactly the same as explained previously:
$function load() {
$for ($i=0; $i<10; $i++) {
$print($i)
}
}
But there is an additional for loop called forentity
that iterates through all entities of a certain type:
$function load() {
$forentity ("@e[type=minecraft:zombie]"; zombie) {
$tp(zombie, "~ ~10 ~") # Teleports all zombies 10 blocks up
}
}
"@e[type=minecraft:zombie]"
is the selector - the type of entity that we're going to iterating through - and zombie
is a variable that's going
to store the selector to the specific entity being targeted in each iteration.
While loops
The syntax for these loops is also the same as explained previously:
$function load() {
$i = 10
$while($i > 0) {
$i--
$print($i)
}
}
This will print out the numbers from 9 to 0.
Functions
Functions are turned into Minecraft function files, and can be used later in your code, or called from within minecraft using /function yourpack:yourfunction
$function reset() {
$a = 0
$b = 0
$c = 0
$print("Reset")
}
$function load() {
$reset()
}
This code will run your $reset
function when the datapack is loaded.
Minecraft Commands
You can still run any Minecraft command normally by using $mc("your command here")
.
Building your datapack
After you've finished writing all your code, you can build your datapack using the command minescript --file yourpack.ms
.
MineScript will create your datapack .zip
folder inside /dist/datapack.zip
. If you want to change the name of the datapack
or some if its attributes, use minescript --help
to get a list of all possible flags you can use.