mcscript

Minecraft Script is a programming language designed for developers of mcfunctions, Minecraft maps, and packages. It allows you to write code in .mcscript files, which are then compiled into the standard Minecraft function format. This provides extended programming capabilities not available in raw mcfunctions, including:

• Modals
• Loops
• Variables
• Constants
• Command-Wrapping

Minecraft Script files use the .mcscript extension. Unlike standard .mcfunction files, commands in .mcscript are prefixed with / or run:.

Key Syntax Rules:

• Comments: Use // for standard comments. If you want comments to appear in the generated .mcfunction file, use #.
• Blank Lines: Blank lines are ignored. To force a blank line in the output, use a # on its own line. Use ## to represent two blank lines.
• Multi-line Comments: Use the standard /* ... */ syntax.
• Command Injection: Every command must be explicitly prefixed with / or run: to be recognized.

/*
 comment
*/

// Standard comment
# This comment will appear in the output mcfunction

##
// This results in two blank lines

By default, variables (#vars), constants (#consts), and Modals are scoped to the individual file they are declared in.

To create global scope, create a file with the .gl.mcscript extension. The compiler automatically detects these globals and makes them available to all other files in the project. This is useful for centralizing Modals or shared constants.

// Example: globals.gl.mcscript
// This file will be accessible by all other scripts

By default, .mcscript files generate output files with the same name in the /functions directory. You can override this behavior using the #file: *name* directive inside your script.

Rules:

• Do not include the .mcfunction extension in the name.
• You can specify absolute paths, relative paths (e.g., ./neu), or parent directory paths (e.g., ../neu).
• You can specify multiple files within a single script.
• The directive is compatible with for-loops to generate multiple files dynamically.

#file: neu
//commands here

#file: zwei
//Commands for two here

// Using with a loop:
for(1,5){
    #file: test$(i)
    //Commands for each file here
}

Variables, constants, and modals are normally stored separately for each file. To create shared objects, create a file with the .gl.mcscript extension. The compiler automatically detects these global files and makes their declared objects available in all other files.

// Example: my_globals.gl.mcscript
const MY_CONSTANT = 10;

The forEach loop is a dynamic loop that runs inside Minecraft rather than during the generation phase. It allows you to iterate based on a condition and increment a variable. The current value of the iterator is automatically saved to a Minecraft scoreboard with the name of the iterator variable.

Syntax: forEach(var [var_name] = [start value]; [var_name] [operator] [other_var]|[number]; [varname]++) { [commands] }

Operators: ==, |>, <, <=, >=, !=

// Example: Running a command 10 times
forEach(var i = 0; i < 10; i++){
    /say hey
}

// Example: Using the iterator for calculations
var result = 1
forEach(var i = 2; i <= 10; i++){
    result *= i
}
// result becomes 1 * 2 * 3 * 4 * 5 * 6 * 7 * 8 * 9 * 10

Logical operators can be used within Command Grouping and If-statements.

• OR (||):
  • In grouping: as(@s||@p){ ... } (executes for both).
  • In if: if(@s[tag=e1], 'entity @s[tag=e2]') (executes if either is true).
• AND (&&):
  • In if: if('entity @s' && 'entity @p') (executes only if both are true).
• Comparison: Supports ==, !=, >, <, >=, <= for variables and selectors.

// OR in grouping
as(@s||@p){
    /command
}

// OR in if
if(@s[tag=entity1], 'entity @s[tag=entity2]'){
    /command
}

// AND in if
if('entity @s' && 'entity @p'){
    /command
}

// Variable comparison
var test = 5
if(test >= 5){
    /say greater or equal
}

You can group Minecraft execution context modifiers (like as, at, positioned, align, in, dimension, rotated, and anchored) to simplify complex /execute chains.

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

Arguments must be provided as strings (using ' ' or " "). You can also use the shorthand asat() for combining as and at.

as(@a){
	/commands 	=> /execute as @a run command
}

// Using asat shorthand
asat(@s){
    /commands => execute as @s at @s run commands
}

// Multiple groups
as(@p), at(@s), positioned('~ ~1 ~'){
    /say command
}
// Results in: /execute as @p at @s positioned ~ ~-1 ~ run say command

Minecraft Script code is written in files with the .mcscript extension.

Command Injection: Unlike standard mcfunction files, every command must be injected using either a / or run: prefix.

Comments:

• Single-line comments: //
• Comments that should appear in the generated file: #
• Multi-line comments: /* ... */

Whitespace: Empty lines and line breaks are ignored during compilation. To preserve structure in the resulting mcfunction file, use a # on an empty line. To represent two empty lines, use ##.

// This is a comment
# This empty line will appear in the output
## This will appear as two empty lines

/say hello
run: say world

/*
Multi-line
comment
*/

By default, variables (#vars), constants (#consts), and Modals (#modals) are scoped to the individual file they are declared in.

To create global scope, create a file with the .gl.mcscript extension. The compiler automatically detects these files and makes the declared objects (variables, constants, and modals) available to all other files in the project.