Update 0.1.3: All Changes
Minecraft Script is a programming language for developers of mcfunctions, Minecraft maps and packages. The .mcscript files are therefore compiled and generated to the function format. This enables the developer extended possibilities, such as Modals, Loops, Varibles, Constants and Command-Wrapping.
Everyone who wants to try, can visit my playground stevertus.ga/tools/mcscript and can play with its function.
German documentation here
The Compiler gets offered as Node.js/ Package that is installed locally on your machine. It enables much more features than the online version
For example: compile all files in a directory, direct output in new files, watch your files on changes, etc.
The installation requires the Node.js environment and the Node Package Manager.
This is achieved the best way by using the installer: nodejs.org/en/download/
Just run it and install.
Now open your PCs console. (search CMD).
There you have to type in this command:
npm install -g mcscript
If a successful answer apears you have done everything right and can start.
You can now use the tool by launching the Command Line in your datapacks folder
(with Shift + rightclick on directory -> open command line)
Now you can use the commands like that:
Creates a new datapack for you with all basic files in a scripts folder. Takes as argument the datapack id!
This command converts all .mcscript files into .mcfunction format. You can read here what you can do in the mcscript files.
The console displays all generated files or throws an error if something was not correct.
Alternatively you can use mcscript-compile *filepath* to set an custom directory or file.
This will automatically compile your code if you make any changes (save). So you do not have to enter the above command with every change.
Again, a path can be specified.
!!This command is intended only for developers who want to install their modals in the compiler.
A file must be specified and then the modals out of this file are written to a configuration file.
The code is written in files with the extension .mcscript. It is recommended to manage the files and to highlight the syntax in a code editor (IDE). explore more here.
Unlike mcfunction, each command is injected with a "/" or "run:".
Comments are announced with "//", if comments should also appear in the new file with "#"
Blank lines and skipping lines are ignored.
If a blank line is desired in the mcfunction, express this with a ‘#’ without a comment.
Two blank lines are reached with "##".
The generated files have always the same name as their root.
A custom name can be set with #file: *name*.
Please without .mcfunction!!
Instead of the name, you can enter a whole path where the new file should be:
#file: C:/test/new#file: ./new (in same directory)#file: ./subfolder/new#file: ../new (a directory above)#file: ../subfolder/newYou can also specify several files:
#file: new
//commands here
#file: two
//Commands for two
Also very well combinable with for-loops:
#file: new
//commands here
for(1,5){
#file: test$(i)
//Commands for every file here
}
A already existing file, that is generated before with #file:, can be expanded in other files and new code is easily attached:
#extend: ./test
/commands here
[subcommand]([argument]){ [wrapped actions] }
"as, at, positioned,align,dimension,rotated,anchored" can be grouped together:
as(@a){
/commands => /execute positioned ~ ~ ~ run command
}
The Argument / Arguments in the brackets have to be a string! (with ’ ’ or " ")
It is also possible to use asat() for this:
asat(@s){
/commands => execute as @s at @s run commands
}
"Groups can be listed like so:
as(@p), at(@s), positioned('~ ~1 ~'){
/say command
}
==> /execute as @p at @s positioned ~ ~-1 ~ run say command
// also with if
as('@p'), at('@s'), positioned('~ ~1 ~'), if(entity @s[tag=mytag]){
/say command
}
==> /execute as @p at @s positioned ~ ~-1 ~ if entity @s[tag=mytag] run say command
Like every other programming language there are variables. They are initialized as follows:
var test
The variable can take in a value:
var test = 5
# or
var test
test = 6
This value can be changed as often as you like.
var test
test @s = 10
Values can be assigned also only to special Minecraft selector like so.
Also possible with playernames and placeholders:
test player = 10
Every value is saved in an independent scoreboard with it´s name or selector. So they are accessible with normal methods:
var test
test @s = 10
/scoreboard players get @s test ==> 10
/scoreboard players set @s test 5
# etc
Variables can be merged together:
var test = 10
var new = 5
# For the sake of simplicity, I start again and again with these values. The program makes it naturally different!
test += 2 ==> 12
test -= 2 ==> 8
Bit shorter:
test++ ==> test += 1
test-- ==> test -= 1
test += new ==> 15
test -= new ==> 5
test *= new ==> 50
test /= new ==> 2
test %= new ==> 0
bool [name] [selector](optional) = true|false
Boolean values can be declared like this.
bool isCool = true => tag [global] add isCool
The variable can be changed later:
isCool = false => tag [global] remove isCool
With If testable:
if(isCool){
/commands => execute if entity [global][tag=isCool] run commands
}
Another type of variable is the constant, declared as following:
const test = [value]
This type cannot be changed!
You can use it with $ (var_name) somewhere in your code to avoid long strings and repetitive phrases:
const aString = "Here can be a string"
const aNum = 5
/say $(aString) ==> /say Here can be a string
var test = $(aNum) ==> var test = 5
If functions are similar to grouping:
if('statement'){
/commands => /execute if statement run command
}
With some additional features:
if(!'statement'){
/commands => /execute unless statement run command
}
if('statement'){
/commands => /execute if statement run command
} else { /execute unless statement run command2
/commands2
}
Important: Do not change the argument!
if('entity @s[tag=test]'){
/tag @s remove test
} else {
/tag @s remove test
}
They are both executed!! Improved:
if('entity @s[tag=test]'){
/tag @s add testIf
}
if('entity @s[tag=testIf]'){
/tag @s remove test
} else {
/tag @s remove test
}
if('statement'){
/commands => /execute if statement run command
} else if('statement2') { /execute unless statement if statement2 run command2
/commands2
}
In combination with grouping and if-else statements logical operators can be used:
as('@s'||'@p'){
/command
}
==> execute as @s run command
execute at @p run command
# or as list
if('entity @s[tag=entity1]','entity @s[tag=entity2]'){
/command
}
==> execute if entity @s[tag=entity1] run command
execute if entity @s[tag=entity2] @p run command
if('entity @s'&&'entity @p'){
/command
}
==> execute if entity @s if entity @p run command
var test = 5
# equally
if(test == 5){
/commands
}
# greater/smaller or equal
if(test >= 5){
/commands
}
# greater/smaller
if(test > 5){
/commands
}
# also avalible as comparison
if(test > test2){
/commands
}
# or with variables with entitys
if(test @s > test2 @a){
/commands
}
switch([var_name]){
case <=|<|==|>|>= [other_var]|[number] {
[actions]
},
default(optional) {
[default actions]
}
}
Switches makes the case distinction much easier. It´s able to test easily and clearly certain variables.
e.g:
var test = 10
switch(test){
case > 10 {
/say var is over 10
},
case < 10 {
/say var is under 10
},
default {
/say no match
}
}
Here test is checked for more than 10, if that does not apply to less than 10 and finally outputed as default.
Also abbreviable:
var test = 10
switch(test){
case > 10 run: say var is over 10
, case < 10 run: say var is under 10
, default run: say no match
}
One of the most helpful features is the for loop. It takes in neutral numbers.
From first Argument to second Argument is optional outputed as third Argument
for(1,5){
/commands
# is outputed 5 times
}
for(1,5){
/say $(i)
# say with 1 - 5 is outputed 5 times
}
with $(var_name) the loop variable can be accessed
var_name is out of the box defined as "i", but can be changed with the third argument:
for(1,5,X){
/say $(X)
# say with 1 - 5 is outputed 5 times}
That makes especially with two-dimensional loops sence:
for(1,5,i){
for(1,2,j){
/say $(i).$(j)
}
# say with 1.1 - 5,2 is outputed 10 times
}
raycast([distance](optional), [block to travel through](optional)){
[actions on hitted block]
},{
[actions for every flight step]
}
default distance = 100 Blocks
default block = air
Raycasting is a big thing in Minecraft 1.13 and provides unlimeted opportunities. But it is a bit difficult, so why not making it easier? With Minecraft Script this is really really easy now:
raycast {
/setblock ~ ~ ~ stone
}
This alone sets everywhere where you look a stone
Particles and block limits are also pretty easy:
raycast(10) {
/setblock ~ ~ ~ stone
}, {
/particle flame ~ ~ ~
}
Now there are beautiful effects and a max range of 10 blocks.
The while loop is defined like so:
while([cond]){
/commands
}
The grouped commands are executed as long as the condition [cond] is true.
If the condition to start is not true, the grouping will not be executed!
As a condition, all operators and arguments of the If conditions can be used. e.g.
var test = 0
while(test < 10){
/commands here
test += 1
}
# ==> The commands are executed 10x in one tick
For while-loops you can also use stop and continue:
var test = 0
while(test < 10){
test += 1
if(test == 5){
continue
# If test is equal to 5 the other commands are skipped
}
/commands hier
if(test >= 9){
stop
# If test is equal to or over 5 the loop is stopped
}
}
do {
/commands
} while([cond])
The do-while loop works in a similar way to the while loop, with the small difference that the code block is executed and then the condition is checked.
So the loop is executed at least one time.
forEach(var [var_name] = [start value]; [var_name] ==|>|<|<=|>=|!= [other_var]|[number]; [varname]++){
/commands
}
The forEach Loop is a loop found in almost any programming language.
It is similar to Minecraft Script’s for-loop, but it works dynamically (it does not run on generate, but in Minecraft)
e.g:
forEach(var i = 0; i < 10; i++){
/say hey
}
The Command is executed 10 times and the current value is saved each in the scoreboard i.
Der Command wird also 10mal ausgeführt und der aktuelle Wert jeweils in dem scoreboard i gespeichert.
You can also access the value like so. e.g. Faculty:
var result = 1
forEach(var i = 2; i <= 10; i++){
result *= i
}
==> result = 1 * 2 * 3 * 4 * 5 * 6 * 7 * 8 * 9 * 10
Modals are like functions or methods. That means you can define them:
modal newModal(argument){
/say $(argument)
}
A modal is always introduced with the keyword followed by the name and the arguments in the brackets.
The arguments are accessible inside with $(argument_name).
modal newModal(argument){
/say $(argument)
}
newModal('test')
# => say test
If you use the modal like that, the values are used and it outputs everything.
modal createCommand(command,argument1,argument2){
/$(command) $(argument1) $(argument2)
}
createCommand('say', 'hallo', 'du')
# => say hallo du
You are also able to use multiple arguments.
There are optional and predefined arguments, too:
modal say(argument = "hallo"){
/say $(argument)
}
say()
# => say hallo
say('test')
# => say test
There are already some helpful predefined modals. Please read the specific documentation here.
You have ideas which modals should be a standart? Send me your configuration file to check.
Not available yet
Thanks to all who use Minecraft Script and read this documentation. Contact me if you have a proposal, problem or error.