JavaScript Script Blocks

Script Blocks provide an easy, inline way to use JavaScript to generate, or insert values into, your commands.

Inline Scripts

Used to evaluate some JavaScript and inline the result into a command.

<%...%>

Scope

Variables, and functions that are available for use in inline script blocks.

• context

  The current Compiler Context.

• embed(block: BoundBlock)

  Takes a BoundBlock instance (such as a Template block argument) and embeds a reference to it.

• isMacro

  true if the current line is a macro line (starts with $).

• Global Scope

Argument Scope

Argument scope is the special scope that is used when an Inline Scripts is used as an argument for MC-Build Compile-time features, such as REPEAT, or IF expressions.

It has access to everything the normal inline script scope has, except for the embed function.

Examples

Using an Inline Script

Code

say <% 1 + 1 %> <%10*10%>

REPEAT (1, 10) as i {
    say <% i %>
}

Output

say 2 100
say 1
say 2
say 3
say 4
say 5
say 6
say 7
say 8
say 9
say 10

Multi-line Scripts

Used to evaluate more complex JavaScript. Instead of injecting the return result of the script into a command, Multi-line Scripts include a few functions that can be used to generate commands, and more.

<%%
    ...
%%>

Scope

Variables, and functions that are available for use in multi-line script blocks.

• emit(str: String)

  Emits a string into the output.

• emit.mcb(str: String)

  Emits a string into the output after running it through the MC-Build compiler. In a top-level script block, the string can contain top-level code, such as function definitions.

• emit.block(commands: Array[String], data?: String)

  Takes a list of commands, generates a function, and emits a call to that function. data is added after the function call, for example macro arguments. Returns the generated function's name. Not available in top-level script blocks.

• context

  The current Compiler Context.

• embed(block: BoundBlock)

  Takes a BoundBlock instance and returns a function command that references it, which can then be emited.

• require(path: String)

  Requires a file relative to the current file. Same as the require function in Node.js.

• isMacro

  true if the script block is in a macro context.

• Global Scope

Examples

Using a Multi-line Script

Code

function say_hello {
    <%%
        emit("say Hello World")
        for (let i = 0; i < 3; i++) {
            emit(`say ${i}`)
        }
    %%>
}

say_hello.mcfunction

say Hello World
say 0
say 1
say 2

Generating Functions with Multi-line Scripts

At the top level of a file, emit.mcb() can generate functions. Use \n for line breaks in the emitted code.

Code

<%%
    for (let i = 0; i < 3; i++) {
        emit.mcb(`function say_${i} {\nsay ${i}\n}`)
    }
%%>

say_0.mcfunction

say 0

say_1.mcfunction

say 1

say_2.mcfunction

say 2

Global Scope

Variables, and functions that are available for use in all script blocks.

• REPEAT

  the method that produces an iterator used for evaluating REPEAT expressions.

• store

  An object that can be used to store misc values that persist between script blocks, but not between builds.

• global

  An object that can be used to store misc values that persist between script blocks, and between rebuilds in mcb watch mode.

• config

  The object exported by your mcb.config.js (or mcb.config.json) file. Add your own keys to it to use them in scripts, for example IF config.debug { ... }.