Minecraft Script Documentation

Update 0.2.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.

Visit the official Website for information, guides and videos: https://mcscript.stevertus.com

German documentation here

Installation
- Installation of Node.js
- Installation of Minecraft Script
Cli Commands
file system
Syntax
IDEs and Syntax Highlighting <a id="install"></a>

Installation

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. <a id="install-nodejs"></a>

1.1 Installation of Node.js

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. <a id="install-mcscript"></a>

1.2 Installation of Minecraft Script

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. <a id="cli"></a>

CLI Commands

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: <a id="cli-new"></a>

2.1 mcscript new

Creates a new datapack for you with all basic files in a scripts folder. Takes as argument the datapack id! <a id="cli-compile"></a>

2.2 mcscript compile

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. With an additional -fullErr flag you can view full errors and code positions. <a id="cli-watch"></a> <a id="cli-watch"></a>

2.3 mcscript watch

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 and -fullErr can be specified. <a id="cli-add"></a>

2.4 mcscript add [url or package]

This command adds a custom datapack to your directory. As argument an url to the resource or a mcScript Extension name can be used.

Get a list of all supported packages by running justmcscript add

2.5 Dev: mcscript modals

!!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. <a id="files"></a>

3) File system

3.1 File setup

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/new

You 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
}

3.2 Extend Files

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

3.3 Global Files

Variables (#vars), [constants] (#consts), and [Modals] (#modals) are stored separately for each file. Now you can create a global file with the extension '. gl. mcscript '. The compiler automatically detects globals and uses the declared objects in other files as well. For example, you can write the modals to a separate file. <a id="syntax"></a>

Minecraft Script Syntax

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 "##".

A comment across multiple lines can be expressed with:

/*
 comment
*/

4.1 Command Grouping / Wrapping

[subcommand]([argument]){ [wrapped actions] }

"as, at, positioned,align,in,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

4.2 Functions

[run] function "name|path" {
/commands
}

run optional a path should be given as string a name consisting of only characters, can be given without ""

A function generates a new mcfunction with the given name or path. You can also execute the function directly with the run keyword. This is an alternative to a more complicated varient with #file:.

e.g:

run function test {
	/say function
}
/say not function
=
/function prj:test
/say not function

#file: ./test
/say function

4.3 Variables

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

** Save command response to variable: **

var res = run: command
==> execute store result score res res run command

The result of the command is written to the variable res. Example with /data get: ' var varResult = run: data get entity @s Pos[0] ' <a id="boolean"></a>

4.4 Boolean Variables (Tags)

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
}

4.5 Constants

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

Replace constants The value of an constant can still be changed when used. To do this, add '.repl()' to the constant:

$(const).repl([search],[replacement])

In our example, we want to replace a:

/say $(aString).repl(" a "," the ") ==> /say Here can be the string

Also a RegEx can be inserted here and can be also accessed with '$&' in the replacement: `$(a

Mcscript

Install / Use

README