Minecraft Script

https://github.com/stevertus/mcscript
Admin
Minecraft Script is a programming language that compiles .mcscript files into Minecraft mcfunction...
Tokens:25,746
Snippets:376
Trust Score:6.7
License:MIT
Update:5 months ago
Show doc for...
Tokens:
Raw
### Basic For-Loop Example

Source: https://github.com/stevertus/mcscript/blob/master/README-DE.md

Executes commands a fixed number of times (5 times in this example).

```minecraft-script
for(1,5){
	/commands
	# es wird 5x command ausgegeben
}
```

--------------------------------

### cam.start

Source: https://github.com/stevertus/mcscript/blob/master/Core Modals.md

Starts the camera process.

```APIDOC
## cam.start

### Description
Starts the camera process.

### Method Signature
`cam.start( [entity] )`
```

--------------------------------

### Switch-Case example with conditions

Source: https://github.com/stevertus/mcscript/blob/master/documentation/syntax/README.md

An example demonstrating a switch statement that checks if a variable is greater than, less than, or matches a default value, executing different commands for each case.

```js
var test = 10
switch(test){
    case > 10 {
        /say var is over 10
    },
    case < 10 {
        /say var is under 10
    },
    default {
        /say no match
    }
}
```

--------------------------------

### Install mcscript CLI

Source: https://context7.com/stevertus/mcscript/llms.txt

Install the Minecraft Script compiler globally using npm. Requires Node.js.

```bash
# Requires Node.js (https://nodejs.org/en/download/)
npm install -g mcscript
```

--------------------------------

### Install mcscript CLI

Source: https://github.com/stevertus/mcscript/blob/master/docs/index.html

Provides the command to install the mcscript command-line interface globally using npm. This requires Node.js and npm to be installed.

```bash
npm install -g mcscript

```

--------------------------------

### Executing and Storing Command Result

Source: https://github.com/stevertus/mcscript/blob/master/docs/syntax/index.html

An example of executing a '/data get' command and storing its specific output (the first element of the 'Pos' array for the nearest entity) into a variable named 'varResult'.

```mcscript
var varResult = run: data get entity @s Pos[0]
```

--------------------------------

### Install mcscript Globally

Source: https://github.com/stevertus/mcscript/blob/master/docs/guide/index.html

Use this command in your console to install the mcscript compiler globally on your machine. This allows you to use mcscript commands from any directory.

```bash
npm install -g mcscript
```

--------------------------------

### Switch-Case Example with Variable

Source: https://github.com/stevertus/mcscript/blob/master/README-DE.md

Demonstrates checking a variable against different conditions (greater than, less than) with a fallback default case.

```minecraft-script
var test = 10
switch(test){
    case > 10 {
        /say var ist über 10
    },
    case < 10 {
        /say var ist unter 10
    },
    default {
        /say nichts traf zu.
    }
}
```

--------------------------------

### Install Modals for Compiler

Source: https://github.com/stevertus/mcscript/blob/master/README.md

Intended for developers to install modals into the compiler. Requires specifying a file containing the modals.

```bash
mcscript modals <filepath>
```

--------------------------------

### Implement Loops in mcscript

Source: https://github.com/stevertus/mcscript/blob/master/documentation/README.md

Shows examples of 'for' and 'while' loops. Use 'for' loops for a set number of iterations and 'while' loops for conditional repetition.

```javascript
for(1,5){
  log($(i))
}
while('entity @s[tag=loop]'){

}
```

--------------------------------

### Nested For-Loops Example

Source: https://github.com/stevertus/mcscript/blob/master/README-DE.md

Illustrates using nested for loops with different counter variables ('i' and 'j') to generate combined outputs.

```minecraft-script
for(1,5,i){
    	for(1,2,j){
    		/say $(i).$(j)
    	}
    	# es wird 10x say mit 1.1 - 5.2 ausgegeben
    }
```

--------------------------------

### While-Loop Example with Counter

Source: https://github.com/stevertus/mcscript/blob/master/README-DE.md

Executes commands 10 times by incrementing a counter variable within the loop. Assumes commands are executed within a single tick.

```minecraft-script
var test = 0
while(test < 10){
    /commands hier
    test += 1
}
# ==> Die Commands werden innerhalb eines Ticks 10mal ausgeführt.
```

--------------------------------

### ForEach Loop Example: Simple Iteration

Source: https://github.com/stevertus/mcscript/blob/master/docs/syntax/index.html

Executes the command '/say hey' 10 times, with the loop counter 'i' stored in a scoreboard. The current value of 'i' is accessible within the loop.

```minecraft-script
forEach(var i = 0; i < 10; i++){
    /say hey
}
```

--------------------------------

### Add Community Extension Packs

Source: https://context7.com/stevertus/mcscript/llms.txt

Download and install community extension packs using the 'mcscript add' command. This can be done by package name or a direct URL to a zip archive or GitHub release.

```bash
# List all available packages
mcscript add

# Install a named extension
mcscript add mccam

# Install from a direct URL (zip archive or GitHub release)
mcscript add https://github.com/Stevertus/McCam/archive/master.zip
```

--------------------------------

### Saving Command Response to Variable

Source: https://github.com/stevertus/mcscript/blob/master/docs/syntax/index.html

Shows how to capture the output of a command into a variable named 'res'. The example uses 'run: command' to execute a command and store its result.

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

--------------------------------

### Improved conditional logic with tags

Source: https://github.com/stevertus/mcscript/blob/master/documentation/syntax/README.md

An improved example showing distinct actions based on entity tags, using an if statement to add a tag and a subsequent if-else to remove it, demonstrating state changes.

```js
    if('entity @s[tag=test]'){
    	/tag @s add testIf
    }
    if('entity @s[tag=testIf]'){
    	/tag @s remove test
    	} else {
    	/tag @s remove test
    }
```

--------------------------------

### Improved Conditional Tagging

Source: https://github.com/stevertus/mcscript/blob/master/README.md

This example demonstrates a more refined approach to conditional tagging, ensuring specific tags are added or removed based on entity presence.

```mcscript
if('entity @s[tag=test]'){
	/tag @s add testIf
}
if('entity @s[tag=testIf]'){
	/tag @s remove test
		} else {
	/tag @s remove test
}
```

--------------------------------

### ForEach Loop Example: Factorial Calculation

Source: https://github.com/stevertus/mcscript/blob/master/docs/syntax/index.html

Calculates the factorial of numbers from 2 to 10, storing the cumulative result in the 'result' variable. The loop iterates from i=2 up to and including 10.

```minecraft-script
var result = 1
forEach(var i = 2; i <= 10; i++){
    result *= i
}
```

--------------------------------

### ForEach Loop Syntax

Source: https://github.com/stevertus/mcscript/blob/master/docs/syntax/index.html

A dynamic loop similar to a standard for-loop, executing commands within a range defined by start value, condition, and increment. The loop runs in-game, not at generation time.

```minecraft-script
forEach(var [var_name] = [start value]; [var_name] ==|>|<|<=|>=|!= [other_var]|[number]; [varname]++){
    /commands
}
```

--------------------------------

### Conditional execution with entity selector

Source: https://github.com/stevertus/mcscript/blob/master/documentation/syntax/README.md

Demonstrates an if-else block where the condition checks for an entity with a specific tag. Note that both branches execute regardless of the condition in this specific example.

```js
    if('entity @s[tag=test]'){
    	/tag @s remove test
    } else {
    	/tag @s remove test
    }
```

--------------------------------

### File Handling in mcscript

Source: https://github.com/stevertus/mcscript/blob/master/docs/index.html

Demonstrates how to define and create multiple files using the '#file:' directive. This allows for modular code generation and file merging.

```mcscript
#file: file1
#this is file 1

#file: file2
#this is file 2

```

--------------------------------

### Define an Array

Source: https://github.com/stevertus/mcscript/blob/master/documentation/syntax/README.md

Declare an Array using the Array-operator, listing values within the brackets. Values are indexed starting from 0.

```js
const testArr = Array{
	"value", // index 0
	"value2" // index 1
}
```

--------------------------------

### Access Array value by index

Source: https://github.com/stevertus/mcscript/blob/master/documentation/syntax/README.md

Access elements of an Array using their numerical index, starting from 0. The accessed value can be used in commands.

```js
/say $(testArr).0
```

```js
/say $(testArr).1
```

--------------------------------

### Define Files in mcscript

Source: https://github.com/stevertus/mcscript/blob/master/documentation/README.md

Demonstrates how to define and comment within separate files using the '#file:' directive. This is useful for organizing code into multiple, manageable parts.

```plaintext
#file: file1
#this is file 1

#file: file2
#this is file 2
```

--------------------------------

### Conditional Execution with Entity Selectors

Source: https://github.com/stevertus/mcscript/blob/master/README.md

Use entity selectors within `if` statements to conditionally execute commands. This example shows removing a tag if an entity has it, and doing nothing if it doesn't.

```mcscript
if('entity @s[tag=test]'){
	/tag @s remove test
} else {
	/tag @s remove test
}
```

--------------------------------

### Create New Datapack Scaffold

Source: https://context7.com/stevertus/mcscript/llms.txt

Use the 'mcscript new' command to create a new datapack scaffold with the required folder structure and basic files. Specify the desired namespace.

```bash
# Create a new datapack with the namespace "myadventure"
mcscript new myadventure

# Output: generates pack.mcmeta, data/myadventure/functions/, and scripts/ folder
```

--------------------------------

### Global Files for Project-Wide Scope

Source: https://context7.com/stevertus/mcscript/llms.txt

Files with the '.gl.mcscript' extension are automatically loaded before all other files, making declared variables, constants, and modals available project-wide without explicit imports.

```mcscript
// globals.gl.mcscript  — shared across the entire project
const PROJECT = "myadventure"
const MAX_PLAYERS = 8

modal broadcast(msg){
    /tellraw @a {"text":"[$(PROJECT)] $(msg)"}
}

// any other .mcscript file can now call:
broadcast('Game starting!')
// => tellraw @a {"text":"[myadventure] Game starting!"}
```

--------------------------------

### Compile mcscript Files

Source: https://context7.com/stevertus/mcscript/llms.txt

Compile all .mcscript files in the current directory or a specified path into .mcfunction files. Use '-fullErr' for detailed error reporting.

```bash
# Compile all .mcscript files in the current datapack folder
mcscript compile

# Compile a specific file
mcscript compile ./scripts/main.mcscript

# Compile with full error reporting
mcscript compile -fullErr
```

--------------------------------

### Declare and Use Variables in mcscript

Source: https://github.com/stevertus/mcscript/blob/master/docs/index.html

Demonstrates how to declare variables, assign values, and perform arithmetic operations. Variables can store numbers and be modified.

```mcscript
var var1;
var var2 = 5;

var1 = 10;

var2 += 5;

var1 += var2;

```

--------------------------------

### Function Definition and Execution

Source: https://github.com/stevertus/mcscript/blob/master/documentation/syntax/README.md

Define and optionally execute functions. Functions can be given a name or path as a string. The 'run' keyword executes the function immediately.

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

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

file: ./test
/say function
```

--------------------------------

### Define and Use Arrays in mcscript

Source: https://github.com/stevertus/mcscript/blob/master/README.md

Create ordered lists of values using the `Array` operator. Access elements by their index (starting from 0) using dot notation, e.g., `$(arrayName).0`.

```javascript
const testArr = Array{
	"value", // index 0
	"value2" // index 1
}
```

```mcscript
/say $(testArr).0
⇒ /say value
/say $(testArr).1
⇒ /say value2
```

--------------------------------

### Implement Loops in mcscript

Source: https://github.com/stevertus/mcscript/blob/master/docs/index.html

Shows how to use 'for' and 'while' loops for repetitive tasks. The 'for' loop iterates a specified number of times, while the 'while' loop continues as long as a condition is met.

```mcscript
for(1,5){
  log($(i))
}

```

```mcscript
while('entity @s[tag=loop]'){

}

```

--------------------------------

### Abbreviated Switch-Case with 'run'

Source: https://github.com/stevertus/mcscript/blob/master/documentation/syntax/README.md

A concise syntax for switch-case statements where actions are specified directly after 'run:' for each case, including a default case.

```js
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
}
```

--------------------------------

### Create New Datapack with mcscript

Source: https://github.com/stevertus/mcscript/blob/master/README.md

Generates a new datapack with basic files and a scripts folder. Requires the datapack ID as an argument.

```bash
mcscript new <datapack_id>
```

--------------------------------

### Using Constants in MCScript Commands

Source: https://github.com/stevertus/mcscript/blob/master/docs/syntax/index.html

Illustrates how to substitute constants into commands using the '$(var_name)' syntax. This includes direct string substitution and assigning a constant numeric value to a variable.

```mcscript
/say $(aString)       ==> /say Here can be a string
var test = $(aNum)   ==> var test = 5
```

--------------------------------

### Define and Run Function in Minecraft Script

Source: https://github.com/stevertus/mcscript/blob/master/README.md

Define a function with optional 'run' keyword and execute it. This is an alternative to '#file:'.

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

#file: ./test
/say function
```

--------------------------------

### Global mcscript Files

Source: https://github.com/stevertus/mcscript/blob/master/docs/files/index.html

Create global mcscript files with the `.gl.mcscript` extension. The compiler automatically detects these files and makes their declared variables, constants, and modals available across other mcscript files.

```mcscript
variable.gl.mcscript
```

--------------------------------

### Define and Run Function

Source: https://github.com/stevertus/mcscript/blob/master/docs/syntax/index.html

Define a new mcfunction with a name or path and optional commands to execute within it. The 'run' keyword allows direct execution.

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

```mcscript
file: ./test
/say function
```

--------------------------------

### While-Loop with Continue and Stop

Source: https://github.com/stevertus/mcscript/blob/master/README-DE.md

Demonstrates using 'continue' to skip the rest of the loop's commands for a specific iteration and 'stop' to break out of the loop entirely.

```minecraft-script
var test = 0
while(test < 10){
    test += 1
    if(test == 5){
        continue
        # Wenn test 5 ist werden die restlichen Commands übersprungen
    }
    /commands hier
    if(test >= 9){
        stop
        # Wenn test 9 oder über 9 ist wird die Schleife abgebrochen
    }
}
```

--------------------------------

### Define mcscript File with Path

Source: https://github.com/stevertus/mcscript/blob/master/docs/files/index.html

Specify a custom name or a relative/absolute path for the generated mcscript file using the `#file:` directive. Paths like `./new`, `../new`, or `./subfolder/new` are supported.

```mcscript
#file: C:/test/new
```

```mcscript
#file: ./new
```

```mcscript
#file: ./subfolder/new
```

```mcscript
#file: ../new
```

```mcscript
#file: ../subfolder/new
```

--------------------------------

### Define and Run Functions in mcscript

Source: https://context7.com/stevertus/mcscript/llms.txt

Functions can be defined to output to their own `.mcfunction` files, optionally with an inline '/function' call using the 'run function' keyword. Functions can also be defined without an immediate call.

```mcscript
// Define and run inline
run function explode {
    /summon tnt ~ ~ ~
    /particle explosion ~ ~ ~
}
/say Bomb planted!
// Compiled output (main file):
// => /function prj:explode
// => /say Bomb planted!
// Compiled output (explode.mcfunction):
// => summon tnt ~ ~ ~
// => particle explosion ~ ~ ~

// Define only (no inline call)
function "events/on_join" {
    /title @s title {"text":"Welcome!"}
}
```

--------------------------------

### Variable Initialization and Assignment

Source: https://github.com/stevertus/mcscript/blob/master/docs/syntax/index.html

Declare variables using 'var' and assign values. Variables can be updated multiple times and assigned to specific selectors or player names.

```mcscript
var test = 5
 or
var test
test = 6
```

```mcscript
var test
test @s = 10
```

```mcscript
test player = 10
```

--------------------------------

### log.var

Source: https://github.com/stevertus/mcscript/blob/master/Core Modals.md

Logs a variable into the Minecraft Chat.

```APIDOC
## log.var

### Description
Logs a variable into the Minecraft Chat.

### Method Signature
`log.var( - objective <string> - , [entityname], [target entity] )`
```

--------------------------------

### Basic While Loop

Source: https://github.com/stevertus/mcscript/blob/master/documentation/syntax/README.md

Executes commands repeatedly as long as a condition remains true. If the condition is initially false, the commands will not execute.

```mcscript
var test = 0
while(test < 10){
    /commands here
    test += 1
}
```

--------------------------------

### Command Grouping with 'asat'

Source: https://github.com/stevertus/mcscript/blob/master/docs/syntax/index.html

Use 'asat' to execute commands as the current entity, similar to '/execute as @s at @s'.

```mcscript
asat(@s){
    /commands => execute as @s at @s run commands
}
```

--------------------------------

### Abbreviated Switch-Case Syntax

Source: https://github.com/stevertus/mcscript/blob/master/README-DE.md

A more concise syntax for switch-case statements, using 'run:' to specify actions.

```minecraft-script
var test = 10
switch(test){
    case > 10 run: say var ist über 10
    , case < 10 run: say var ist unter 10
    , default run: say nichts traf zu.
}
```

--------------------------------

### Basic For loop

Source: https://github.com/stevertus/mcscript/blob/master/documentation/syntax/README.md

Execute a block of commands a specified number of times. The loop runs from the first argument up to and including the second argument.

```js
 for(1,5){
	/commands
	# is outputed 5 times
}
```

--------------------------------

### Watch for Changes and Compile

Source: https://github.com/stevertus/mcscript/blob/master/README.md

Automatically recompiles .mcscript files when changes are saved. Supports custom paths and detailed error reporting.

```bash
mcscript watch
```

```bash
mcscript watch *filepath*
```

```bash
mcscript watch -fullErr
```

--------------------------------

### Add Custom Datapack

Source: https://github.com/stevertus/mcscript/blob/master/README.md

Adds a custom datapack from a URL or an mcScript Extension name. Run 'mcscript add' to list supported packages.

```bash
mcscript add [url or package]
```

--------------------------------

### play

Source: https://github.com/stevertus/mcscript/blob/master/Core Modals.md

Plays a sound.

```APIDOC
## play

### Description
Plays a sound.

### Method Signature
`play(- sound_name - <String>, [target entiy] [type] )`
```

--------------------------------

### Command Grouping with mcscript Wrappers

Source: https://context7.com/stevertus/mcscript/llms.txt

mcscript allows wrapping commands with 'execute' sub-commands like 'as', 'at', 'positioned', etc. Multiple wrappers can be combined on a single block. 'asat' is a shorthand for 'as' and 'at' with the same selector.

```mcscript
// Single wrapper
as(@a){
    /say Hello
    // => execute as @a run say Hello
}

// Combined wrappers on one block
as(@p), at(@s), positioned('~ ~1 ~'){
    /say hi from above
    // => execute as @p at @s positioned ~ ~1 ~ run say hi from above
}

// asat shorthand (as + at the same selector)
asat(@s){
    /particle flame ~ ~ ~
    // => execute as @s at @s run particle flame ~ ~ ~
}
```

--------------------------------

### Define a basic modal in mcscript

Source: https://github.com/stevertus/mcscript/blob/master/README.md

Define a modal with a name and arguments. Arguments are accessed using `$(argument_name)`. This modal prints the provided argument.

```mcscript
modal newModal(argument){
		/say $(argument)
	}

	newModal('test')
```

--------------------------------

### Define a basic modal with arguments

Source: https://github.com/stevertus/mcscript/blob/master/documentation/syntax/README.md

Define a modal with a name and arguments. Arguments are accessed using $(argument_name).

```mcscript
modal newModal(argument){
		/say $(argument)
	}

    newModal('test')
```

--------------------------------

### Command Grouping with 'as'

Source: https://github.com/stevertus/mcscript/blob/master/docs/syntax/index.html

Group commands under a specific entity selector using 'as'. This is equivalent to '/execute as <selector>'.

```mcscript
as(@a){
	/commands 	=> /execute positioned ~ ~ ~ run command
}
```

--------------------------------

### Modal Definition with Multiple Arguments for Command Execution

Source: https://github.com/stevertus/mcscript/blob/master/docs/syntax/index.html

Defines a modal 'createCommand' that takes a command name and two arguments, then executes the command with those arguments. This allows dynamic command generation.

```minecraft-script
modal createCommand(command,argument1,argument2){
	/$(command) $(argument1) $(argument2)
}

createCommand('say', 'hallo', 'du')
```

--------------------------------

### For-Loop with Output in Minecraft Script

Source: https://github.com/stevertus/mcscript/blob/master/README.md

Demonstrates using the loop variable 'i' within the loop body to produce dynamic output.

```minecraft-script
for(1,5){
	/say $(i)
	# say with 1 - 5 is outputed 5 times
}
```

--------------------------------

### newStand

Source: https://github.com/stevertus/mcscript/blob/master/Core Modals.md

Summons a new armor_stand with optional parameters.

```APIDOC
## newStand

### Description
Summons a new armor_stand with optional parameters.

### Method Signature
`newStand( [name] , [position], [tags], [marker], [invisible], [noGravity] )`
```

--------------------------------

### Saving Command Response to Variable

Source: https://github.com/stevertus/mcscript/blob/master/documentation/syntax/README.md

Store the result of a command execution into a variable using the 'run:' keyword. This is useful for capturing command output, like entity data.

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

```mcscript
' var varResult = run: data get entity @s Pos[0] '
```

--------------------------------

### ForEach Loop for Calculation

Source: https://github.com/stevertus/mcscript/blob/master/documentation/syntax/README.md

Demonstrates using a forEach loop to perform calculations, such as calculating a factorial. The loop variable can be used within the loop body.

```mcscript
var result = 1
forEach(var i = 2; i <= 10; i++){
    result *= i
}
==> result = 1 * 2 * 3 * 4 * 5 * 6 * 7 * 8 * 9 * 10
```

--------------------------------

### Switch-Case Statement Syntax

Source: https://github.com/stevertus/mcscript/blob/master/README-DE.md

Provides a structured way to handle multiple conditions. Allows for optional default cases.

```minecraft-script
switch([var_name]){
    case <=|<|==|>|>= [other_var]|[number] {
        [actions]
    },
    default(optional) {
        [default actions]
    }
}
```

--------------------------------

### Modal Definition with Optional Argument

Source: https://github.com/stevertus/mcscript/blob/master/docs/syntax/index.html

Defines a modal 'say' with an optional argument that defaults to 'hallo'. If no argument is provided, it says 'hallo'; otherwise, it says the provided argument.

```minecraft-script
modal say(argument = "hallo"){
	/say $(argument)
}

say()

say('test')
```

--------------------------------

### Runtime ForEach Loops in MCScripter

Source: https://context7.com/stevertus/mcscript/llms.txt

A C-style loop that uses Minecraft scoreboards for its counter, enabling runtime iteration with a mutable variable accessible within Minecraft. Useful for calculations or repeated actions based on scoreboard values.

```mcscript
// Basic iteration
forEach(var i = 0; i < 5; i++){
    /say tick
}
```

```mcscript
// Compute factorial of 5 (result stored in scoreboard)
var result = 1
forEach(var i = 2; i <= 5; i++){
    result *= i
}
```

--------------------------------

### console.log

Source: https://github.com/stevertus/mcscript/blob/master/Core Modals.md

Logs a message into the Minecraft Chat.

```APIDOC
## console.log

### Description
Logs a message into the Minecraft Chat.

### Method Signature
`log( - text <string | number> - , [target entity] )`
```

--------------------------------

### Nested For Loops

Source: https://github.com/stevertus/mcscript/blob/master/docs/syntax/index.html

Create nested loops to perform actions based on multiple iteration counts. Demonstrates accessing different loop variables.

```mcscript
for(1,5,i){
	for(1,2,j){
		/say $(i).$(j)
	}
	# say with 1.1 - 5,2 is outputed 10 times
}

```

--------------------------------

### Define a Map with key-value pairs in MCscript

Source: https://github.com/stevertus/mcscript/blob/master/docs/syntax/index.html

Populate a map with key-value pairs by listing them within the Map-operator's brackets. Keys and values are typically strings.

```mcscript
const testMap = Map{
	"key1":"value",
	"key2":"value2"
}
```

--------------------------------

### Basic If/Else Statement

Source: https://github.com/stevertus/mcscript/blob/master/docs/syntax/index.html

Execute commands conditionally based on a statement. The 'else' block runs if the primary condition is false.

```mcscript
if('statement'){
	/commands 	=> /execute if statement run command
}

```

```mcscript
if('statement'){
	/commands 	=> /execute if statement run command
} else { 		   /execute unless statement run command2
	/commands2
}

```

--------------------------------

### Do-While Loops in MCScripter

Source: https://context7.com/stevertus/mcscript/llms.txt

Similar to a `while` loop, but the loop body is guaranteed to execute at least once before the condition is checked.

```mcscript
var attempts = 0
do {
    attempts += 1
    /say Attempt $(attempts)
} while(attempts < 3)
```

--------------------------------

### While Loop with Counter and Conditional Skip/Stop

Source: https://github.com/stevertus/mcscript/blob/master/docs/syntax/index.html

Demonstrates a while loop that increments a counter, skips commands if the counter is 5 using 'continue', and stops the loop if the counter reaches 9 using 'stop'.

```minecraft-script
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
    }
}
```

--------------------------------

### For-Loop with Outputting Loop Counter

Source: https://github.com/stevertus/mcscript/blob/master/README-DE.md

Demonstrates accessing the current loop iteration number using the default variable 'i'.

```minecraft-script
for(1,5){
	/say $(i)
	# es wird 5x say mit 1 - 5 ausgegeben
}
```

--------------------------------

### While-Loop Syntax

Source: https://github.com/stevertus/mcscript/blob/master/README-DE.md

Repeats commands as long as a given condition remains true. The commands are not executed if the condition is initially false.

```minecraft-script
while([cond]){
    /commands
}
```

--------------------------------

### Compile mcscript to mcfunction

Source: https://github.com/stevertus/mcscript/blob/master/README.md

Converts .mcscript files to .mcfunction format. Supports custom file paths and detailed error reporting with the -fullErr flag.

```bash
mcscript compile
```

```bash
mcscript compile *filepath*
```

```bash
mcscript compile -fullErr
```

--------------------------------

### For-Loop with Custom Loop Variable

Source: https://github.com/stevertus/mcscript/blob/master/README-DE.md

Shows how to specify a custom variable name (e.g., 'X') for the loop counter.

```minecraft-script
for(1,5,X){
    	/say $(X)
    	# es wird 5x say mit 1 - 5 ausgegeben
    }
```

--------------------------------

### Conditional Execution with Entity Selectors

Source: https://github.com/stevertus/mcscript/blob/master/docs/syntax/index.html

Demonstrates conditional execution based on entity tags. Note the important caveat about not changing the argument.

```mcscript
if('entity @s[tag=test]'){
	/tag @s remove test
} else {
	/tag @s remove test
}

```

--------------------------------

### Set Custom File Name or Path

Source: https://github.com/stevertus/mcscript/blob/master/README.md

Specifies a custom name or path for generated .mcfunction files. Supports relative and absolute paths.

```mcscript
#file: *name*.
```

```mcscript
#file: C:/test/new
```

```mcscript
#file: ./new
```

```mcscript
#file: ./subfolder/new
```

```mcscript
#file: ../new
```

```mcscript
#file: ../subfolder/new
```

--------------------------------

### Multiple Command Grouping

Source: https://github.com/stevertus/mcscript/blob/master/docs/syntax/index.html

Combine multiple grouping arguments like 'as', 'at', and 'positioned' for complex command execution contexts. Supports conditional execution with 'if'.

```mcscript
as(@p), at(@s), positioned('~ ~1 ~'){
	/say command
}
==>
/execute as @p at @s positioned ~ ~-1 ~ run say command
```

```mcscript
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
```

--------------------------------

### Control Output File with #file: Directive

Source: https://context7.com/stevertus/mcscript/llms.txt

The '#file:' directive specifies which .mcfunction file subsequent commands are written into. It supports relative/absolute paths and can be used with loops to generate multiple files.

```mcscript
// Write into a named function file
#file: setup
/scoreboard objectives add kills dummy

// Write into a subdirectory file
#file: ./events/on_death
/say player died

// Generate a series of numbered files using a for-loop
for(1,5){
    #file: wave$(i)
    /say Starting wave $(i)
}
// Produces: wave1.mcfunction … wave5.mcfunction, each saying "Starting wave N"
```

--------------------------------

### Do-While-Loop Syntax

Source: https://github.com/stevertus/mcscript/blob/master/README-DE.md

Executes a block of commands at least once before checking the condition. The loop continues as long as the condition is true.

```minecraft-script
do {
    /commands
} while([cond])
```

--------------------------------

### Basic For Loop

Source: https://github.com/stevertus/mcscript/blob/master/docs/syntax/index.html

Iterate a specified number of times. The loop variable 'i' can be accessed within the loop.

```mcscript
for(1,5){
	/commands
	# is outputed 5 times
}

```

```mcscript
for(1,5){
	/say $(i)
	# say with 1 - 5 is outputed 5 times
}

```

--------------------------------

### Define a modal using Map and Array constants

Source: https://github.com/stevertus/mcscript/blob/master/documentation/syntax/README.md

Modals can utilize Map and Array constants. Access Map values using dot notation (e.g., $(args).key).

```mcscript
modal defaultMap(args = Map{"key":"value"}){
    /say $(args).key
}
defaultMap()
defaultMap(
    Map{
    "key":"value2"
})

⇒ /say value
⇒ /say value2
```

--------------------------------

### Define a modal with multiple arguments

Source: https://github.com/stevertus/mcscript/blob/master/documentation/syntax/README.md

Modals can accept multiple arguments, which are then used in the actions within the modal.

```mcscript
modal createCommand(command,argument1,argument2){
		/$(command) $(argument1) $(argument2)
	}

    createCommand('say', 'hallo', 'du')
```

--------------------------------

### Conditional Statements in mcscript

Source: https://github.com/stevertus/mcscript/blob/master/docs/index.html

Illustrates the use of 'if' and 'else' statements for controlling program flow based on conditions. Conditions can check for entity existence.

```mcscript
if("entity @s"){
  /say entity found
}

```

```mcscript
// else statement
if("entity @s"){
  /say entity found
} else {
  /say elsewhise command
}

```

--------------------------------

### Define a modal with multiple arguments in mcscript

Source: https://github.com/stevertus/mcscript/blob/master/README.md

Define a modal that accepts multiple arguments and uses them in a command. Arguments are accessed using `$(argument_name)`.

```mcscript
modal createCommand(command,argument1,argument2){
		/$(command) $(argument1) $(argument2)
	}

	createCommand('say', 'hallo', 'du')
```

--------------------------------

### Arithmetic Operations in MCScript

Source: https://github.com/stevertus/mcscript/blob/master/docs/syntax/index.html

Demonstrates basic arithmetic operations and augmented assignments using variables in MCScript. These operations modify the value of 'test' based on the operation and the value of 'new'.

```mcscript
var new = 5
test += 2 ==> 12
test -= 2 ==> 8
```

```mcscript
test++ ==> test += 1
test-- ==> test -= 1
```

```mcscript
test += new ==> 15
test -= new ==> 5
test *= new ==> 50
test /= new ==> 2
test %= new ==> 0
```

--------------------------------

### Basic Raycast Functionality

Source: https://github.com/stevertus/mcscript/blob/master/README-DE.md

Executes actions on the block the player is looking at. Defaults to a distance of 100 blocks and passing through air.

```minecraft-script
raycast {
    /setblock ~ ~ ~ stone
}
```

--------------------------------

### Constants, Maps, and Arrays in mcscript

Source: https://context7.com/stevertus/mcscript/llms.txt

Constants are resolved at compile time and substituted directly. They support string replacement using `.repl()`. Maps and arrays provide structured compile-time data.

```mcscript
// Scalar constant
const NAMESPACE = "myadventure"
const SPAWN_Y = 64

/function $(NAMESPACE):init
// => /function myadventure:init

var height = $(SPAWN_Y)
// => var height = 64

// Replace part of a constant value
const TITLE = "Welcome to the Adventure"
/title @a title {"text":"$(TITLE).repl(\"Adventure\",\"Dungeon\")"}
// => /title @a title {"text":"Welcome to the Dungeon"}

// Map constant (key-value pairs)
const config = Map{
    "world":"overworld",
    "difficulty":"hard"
}
/function $(config).world:setup
// => /function overworld:setup

// Array constant (indexed list)
const levels = Array{
    "forest",   // index 0
    "cave",     // index 1
    "dungeon"   // index 2
}
/say Level: $(levels).0
// => /say Level: forest
```

--------------------------------

### Runtime While Loops in MCScripter

Source: https://context7.com/stevertus/mcscript/llms.txt

Execute commands repeatedly within a single tick as long as a condition remains true. Supports `stop` to break out of the loop and `continue` to skip the current iteration.

```mcscript
var count = 0
while(count < 5){
    count += 1
    if(count == 3){
        continue   // skip the rest of this iteration
    }
    /say count is $(count)
    if(count >= 4){
        stop       // break out early
    }
}
```

--------------------------------

### Multi-line Comment Syntax

Source: https://github.com/stevertus/mcscript/blob/master/docs/syntax/index.html

Use /* ... */ for multi-line comments in mcscript. Blank lines can be represented by a single '#'.

```mcscript
/*
 comment
*/
```

--------------------------------

### Define and Use Maps in mcscript

Source: https://github.com/stevertus/mcscript/blob/master/README.md

Create key-value pairs using the `Map` operator. Access values using dot notation with the key, e.g., `$(mapName).key`.

```javascript
const testMap = Map{

}
```

```javascript
const testMap = Map{
	"key1":"value",
	"key2":"value2"
}
```

```mcscript
/say $(testMap).key1

⇒ /say value
```

--------------------------------

### System Modals in mcscript

Source: https://context7.com/stevertus/mcscript/llms.txt

Built-in modals for common Minecraft patterns. These include logging messages, displaying scoreboard values, summoning armor stands, and playing sounds. McCam modals require the McCam datapack.

```mcscript
// log() — send a chat message to a player (defaults to @a)
log('Hello world')
log('Score updated', @s)
```

```mcscript
// log.var() — display a scoreboard value in chat
log.var('kills')               // show "kills" objective for all players
log.var('kills', 'Steve', @a)  // show Steve's kills to everyone
```

```mcscript
// newStand() — summon an armour stand with optional parameters
newStand()
newStand('myStand', '~ ~1 ~', 'tag1,tag2', true, true, true)
// args: name, position, tags, marker(bool), invisible(bool), noGravity(bool)
```

```mcscript
// play() — play a sound
play('minecraft:entity.experience_orb.pickup')
play('minecraft:music.game', @s, 'master')
```

```mcscript
// --- Minecraft Cam modals (requires McCam datapack) ---
cam.pos1()                      // set camera position 1 at current location
cam.pos2('10 64 10', '0 90')    // set position 2 with explicit coords and rotation
cam.time(200)                   // set camera travel duration (ticks)
cam.start(@s)                   // start camera movement for @s
cam.stop(@s)                    // stop camera movement for @s
cam.noParticles(@s)             // disable particles for entity
cam.noText(@s)                  // disable messages for entity
```

--------------------------------

### Append to Output File with #extend: Directive

Source: https://context7.com/stevertus/mcscript/llms.txt

The '#extend:' directive appends commands to an existing output file declared in another source file. This enables modular organization without duplicating '#file:' declarations.

```mcscript
// In main.mcscript — declare the file first
#file: ./tick
/scoreboard players add @a timer 1

// In another file — extend the same output
#extend: ./tick
/execute as @a[scores={timer=200}] run function prj:reward
/scoreboard players set @a[scores={timer=200}] timer 0
```

--------------------------------

### Conditional Execution with Boolean Variables

Source: https://github.com/stevertus/mcscript/blob/master/docs/syntax/index.html

Demonstrates how to use an 'if' statement in MCScript to conditionally execute commands based on the state of a boolean variable ('isCool'). The condition translates to checking for the presence of the 'isCool' tag on the entity.

```mcscript
if(isCool){
    /commands => execute if entity [global][tag=isCool] run commands
}
```

--------------------------------

### Basic While Loop in Minecraft Script

Source: https://github.com/stevertus/mcscript/blob/master/README.md

Executes commands repeatedly as long as a specified condition remains true. The loop will not execute if the condition is initially false.

```minecraft-script
var test = 0
while(test < 10){
    /commands here
    test += 1
}
# ==> The commands are executed 10x in one tick
```

--------------------------------

### Extend Existing mcscript File

Source: https://github.com/stevertus/mcscript/blob/master/docs/files/index.html

Use the `#extend:` directive to append new commands to an already generated mcscript file. This allows for modular code organization and incremental file updates.

```mcscript
#extend: ./test
/commands here
```

--------------------------------

### cam.pos1

Source: https://github.com/stevertus/mcscript/blob/master/Core Modals.md

Sets the first position to an optional point.

```APIDOC
## cam.pos1

### Description
Sets the first position to an optional point.

### Method Signature
`cam.pos1( [location <string>] , [rotation <string> ] )`
```

--------------------------------

### Declare and Manipulate Variables in mcscript

Source: https://github.com/stevertus/mcscript/blob/master/documentation/README.md

Demonstrates how to declare variables, assign values, and perform arithmetic operations. Use this for storing and manipulating data within your Minecraft datapacks.

```javascript
var var1;
var var2 = 5;

var1 = 10;

var2 += 5;

var1 += var2;
```

--------------------------------

### For-Loop Syntax

Source: https://github.com/stevertus/mcscript/blob/master/README-DE.md

Iterates a specified number of times. Can optionally define a variable name for the loop counter.

```minecraft-script
for([from],[to],[var_name](optional)){
    [actions]
}
```

--------------------------------

### If Statement with Negation in mcscript

Source: https://github.com/stevertus/mcscript/blob/master/README.md

Execute commands if a statement is false by prepending '!' to the condition. This allows for 'unless' logic.

```mcscript
if(!'statement'){
	/commands 	=> /execute unless statement run command
}
```

--------------------------------

### Define New mcscript File

Source: https://github.com/stevertus/mcscript/blob/master/docs/files/index.html

Use the `#file:` directive to define a new mcscript file. You can specify a custom name or a relative/absolute path. The file extension `.mcfunction` is automatically appended.

```mcscript
#file: new
//commands here
```

```mcscript
#file: two
//Commands for two
```

--------------------------------

### Conditional Statements (if/else/unless) in mcscript

Source: https://context7.com/stevertus/mcscript/llms.txt

mcscript compiles to 'execute if' and 'execute unless' commands. It supports negation with '!', 'else', 'else if', and a dedicated 'unless' keyword for negated conditions.

```mcscript
var health = 5

// Basic if
if(health < 3){
    /say Low health!
    // => execute if score [health] health matches ..-1..2 run say Low health!
}

// if / else
if('entity @s[tag=hasKey]'){
    /function prj:open_door
} else {
    /say You need a key.
}
// => execute if entity @s[tag=hasKey] run function prj:open_door
// => execute unless entity @s[tag=hasKey] run say You need a key.

// else if
if(health > 15){
    /say Healthy
} else if(health > 5){
    /say Hurt
} else {
    /say Critical
}

// unless (negated condition)
unless('entity @s[tag=ready]'){
    /say Not ready yet
    // => execute unless entity @s[tag=ready] run say Not ready yet
}
```

--------------------------------

### Define JavaScript Modal in MCScript

Source: https://github.com/stevertus/mcscript/blob/master/docs/syntax/index.html

Create custom modals using JavaScript. The modal must end with a 'return' statement, and the returned value is output as plain text.

```javascript
modaljs newModal(){
	return "say hi";
}

newModal()

# => say hi
```

```javascript
modaljs newModal(){
	var ret = "";

	ret += "say hi\n";
	ret += "say ho\n";

	return ret;
}

newModal()

# => say hi
# => say ho
```

```javascript
modaljs newModal(argument){
	return "say " + argument;
}

newModal('test')

# => say test
```

```javascript
modaljs newModal(text,monster){
	var ret = "";

	ret += "say " + text + "\n";
	ret += "summon " + monster + "\n";

	return ret;
}

newModal("Brains!!!","minecraft:zombie")

# => say Brains!!!
# => summon minecraft:zombie
```

```javascript
modaljs say(argument = "hallo"){
	return "say " + argument ;
}

say()
# => say hallo

say('test')
# => say test
```

--------------------------------

### If-Else statement

Source: https://github.com/stevertus/mcscript/blob/master/documentation/syntax/README.md

Execute one set of commands if the condition is true, and another set if the condition is false using the 'else' keyword.

```js
    if('statement'){
    	/commands 	=> /execute if statement run command
    } else {       /execute unless statement run command2
    	/commands2
    }
```

--------------------------------

### Replacing Text within Constants

Source: https://github.com/stevertus/mcscript/blob/master/docs/syntax/index.html

Demonstrates how to replace text within a constant string using the '.repl()' method. This method can take literal strings or regular expressions for more advanced replacements.

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

--------------------------------

### Define a modal with an optional argument

Source: https://github.com/stevertus/mcscript/blob/master/documentation/syntax/README.md

Arguments can be made optional by providing a default value. If no value is passed, the default is used.

```mcscript
modal say(argument = "hallo"){
		/say $(argument)
	}

    say()
    say('test')
```

--------------------------------

### Switch Case Statement

Source: https://github.com/stevertus/mcscript/blob/master/docs/syntax/index.html

Provides a structured way to perform different actions based on variable comparisons. Supports various comparison operators and a default case.

```mcscript
switch([var_name]){
    case <=|<|==|>|>= [other_var]|[number] {
        [actions]
    },
    default(optional) {
        [default actions]
    }
}

```

```mcscript
var test = 10
switch(test){
    case > 10 {
        /say var is over 10
    },
    case < 10 {
        /say var is under 10
    },
    default {
        /say no match
    }
}

```

```mcscript
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
}

```

--------------------------------

### Modal Definition with Default Map Argument

Source: https://github.com/stevertus/mcscript/blob/master/docs/syntax/index.html

Defines a modal 'defaultMap' that accepts an optional Map argument, defaulting to Map{"key":"value"}. It accesses the map's value using dot notation.

```minecraft-script
modal defaultMap(args = Map{"key":"value"}){
    /say $(args).key
}

defaultMap()

defaultMap(
    Map{
        "key":"value2"
    }
)
```

--------------------------------

### Variable Declaration and Assignment

Source: https://github.com/stevertus/mcscript/blob/master/documentation/syntax/README.md

Declare variables using 'var'. Assign values directly or using selectors, player names, or placeholders. Variables can be updated.

```mcscript
var test
test @s = 10
```

```mcscript
var test = 5
 or
var test
test = 6
```

```mcscript
test player = 10
```

--------------------------------

### Declare and Access Array Elements

Source: https://github.com/stevertus/mcscript/blob/master/docs/syntax/index.html

Arrays store ordered lists of values. Access elements using their zero-based index.

```mcscript
const testArr = Array{
	"value", // index 0
	"value2" // index 1
}

```

```mcscript
/say $(testArr).0
```

```mcscript
/say $(testArr).1
```

--------------------------------

### Basic For-Loop in Minecraft Script

Source: https://github.com/stevertus/mcscript/blob/master/README.md

Executes a block of commands a specified number of times. The loop variable 'i' is automatically available.

```minecraft-script
for(1,5){
	/commands
	# is outputed 5 times
}
```

--------------------------------

### Use Conditional Statements in mcscript

Source: https://github.com/stevertus/mcscript/blob/master/documentation/README.md

Illustrates 'if' and 'if-else' statements for controlling program flow based on conditions. Use these to execute code blocks only when specific criteria are met.

```javascript
if("entity @s"){
  /say entity found
}

// else statement
if("entity @s"){
  /say entity found
} else {
  /say elsewhise command
}
```

--------------------------------

### Define mcscript Files within a Loop

Source: https://github.com/stevertus/mcscript/blob/master/docs/files/index.html

Combine the `#file:` directive with for-loops to dynamically generate multiple mcscript files. This is useful for creating repetitive structures or numbered files.

```mcscript
#file: new
//commands here
for(1,5){
	#file: test$(i)
	//Commands for every file here
}
```

--------------------------------

### Raycasting in mcscript

Source: https://context7.com/stevertus/mcscript/llms.txt

Generates recursive raycasting function chains. Optionally limits range, filters traversal blocks, and targets specific blocks or entities. The code within the braces is executed at the hit location.

```mcscript
// Simplest raycast: place stone wherever the player looks
raycast {
    /setblock ~ ~ ~ stone
}
```

```mcscript
// Limit range to 10 blocks, show flame particles along the ray
raycast(10) {
    /setblock ~ ~ ~ stone
},{ 
    /particle flame ~ ~ ~ 
}
```

```mcscript
// Only travel through air blocks
raycast(10,"air") {
    /setblock ~ ~ ~ stone
}
```

```mcscript
// Travel through everything EXCEPT white wool (negated porous block)
raycast(10, !"white_wool") {
    /setblock ~ ~ ~ stone
}
```

```mcscript
// Target a specific block type
raycast(10,"air", block "white_wool") {
    /setblock ~ ~ ~ red_wool
}
```

```mcscript
// Target an entity — executes AS the hit entity
raycast(10,"air", entity @e[type=armor_stand]) {
    /say I was hit by a ray!
}
```

--------------------------------

### cam.pos2

Source: https://github.com/stevertus/mcscript/blob/master/Core Modals.md

Sets the second position to an optional point.

```APIDOC
## cam.pos2

### Description
Sets the second position to an optional point.

### Method Signature
`cam.pos2( [location <string>] , [rotation <string> ] )`
```

--------------------------------

### Constant Replacement

Source: https://github.com/stevertus/mcscript/blob/master/documentation/syntax/README.md

Constants can have their values modified during usage using '.repl("search", "replacement")'. This supports string literal replacement and regular expressions.

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

```mcscript
'$(aString).repl([/regex/],["$&"])
```

--------------------------------

### If/Else with Negated Condition

Source: https://github.com/stevertus/mcscript/blob/master/docs/syntax/index.html

Use '!' to reverse the condition, executing the block when the statement is false. The 'else' block runs if the negated condition is false.

```mcscript
if(!'statement'){
	/commands 	=> /execute unless statement run command
}

```
Tokens:
Raw