Migrating from MC-Build 2 to 3

Warning

MC-Build 3 is in alpha, and is not backwards compatible with MC-Build 2. It is highly recommended that you read through this migration guide, and the rest of the documentation to better understand the changes before upgrading.

Updating MC-Build 3

If you already have MC-Build 2 installed, you can run this command to overwrite it, and install MC-Build 3 globally.

npm i -g mc-build@alpha

CLI Differences

Running mcb will no longer start watch mode by default. You'll need to run mcb watch instead.

You can run mcb to see a list of available commands.

Upgrading your `config.js` and `config.json` files

The config.js and config.json files have been updated to be more flexible and easier to use. You will need to update your config.js or config.json file to match the new format.

First, you will need to rename your config.js or config.json file to mcb.config.js or mcb.config.json respectively.

Then, you will need to update the fields in your config.js or config.json file to match the new format. The following tables show the old fields and their new replacements. Expand the table for your respective file type to see the changes.

Upgrading from config.js to mcb.config.js

Old Field	New Field	Default	Description
`mc.dev`	`N/A`		The functionality of `mc.dev` can be replicated using a custom key, so it has been removed.
`mc.header`	`header`	`"# Generated with MC-Build\n"`	The header to be added to the top of all generated files.
`mc.internalScoreboard`	`internalScoreboardName`	`"mcb.internal"`	The name of the internal scoreboard used by MC-Build.
`mc.rootNamespace`	`N/A`		The `mc.rootNamespace` option has been removed.
`global.preBuild`	`setup`	`null`	The `global.preBuild` and `global.postBuild` options have been replaced with the `setup` option.
`global.postBuild`	`setup`	`null`	The `global.preBuild` and `global.postBuild` options have been replaced with the `setup` option.
`mc-math.tempScoreboard`	`eqVarScoreboardName`	`"mcb.eq.var"`	The scoreboard to use when for temperary variables when using `eq` expressions.
`mc-math.constScoreboard`	`eqConstScoreboardName`	`"mcb.eq.const"`	The scoreboard to use when for constant values when using `eq` expressions.
`mc-extra.integrated`	`N/A`		The `mc-extra.integrated` option has been removed, as the functionality of mc-extra has been integrated into the default language.

Old Default config.js

module.exports = {
    global: {
        preBuild: null,
        postBuild: null,
    },
    mc: {
        dev: true,
        header: "# Generated with MC-Build\n",
        internalScoreboard: "mcb.internal",
        rootNamespace: "mcb",
    },
    "mc-math": {
        tempScoreboard: "mcb.eq.var",
        constScoreboard: "mcb.eq.const"
    }
}

New Default mcb.config.js

module.exports = {
    header: "# Generated with MC-Build\n",
    internalScoreboardName: "mcb.internal",
    eqVarScoreboardName: "mcb.eq.var",
    eqConstScoreboardName: "mcb.eq.const",
    setup: null,
    ioThreadCount: 1,
}

Upgrading from config.json to mcb.config.json

Old Field	New Field	Default	Description
`mc.dev`	`N/A`		The functionality of `mc.dev` can be replicated using a custom key, so it has been removed.
`mc.header`	`header`	`"# Generated with MC-Build\n"`	The header to be added to the top of all generated files.
`mc.internalScoreboard`	`internalScoreboardName`	`"mcb.internal"`	The name of the internal scoreboard used by MC-Build.
`mc.rootNamespace`	`N/A`		The `mc.rootNamespace` option has been removed.
`mc-math.tempScoreboard`	`eqVarScoreboardName`	`"mcb.eq.var"`	The scoreboard to use when for temperary variables when using `eq` expressions.
`mc-math.constScoreboard`	`eqConstScoreboardName`	`"mcb.eq.const"`	The scoreboard to use when for constant values when using `eq` expressions.
`mc-extra.integrated`	`N/A`		The `mc-extra.integrated` option has been removed, as the functionality of mc-extra has been integrated into the default language.

Old Default config.json

{
    "mc": {
        "dev": true,
        "header": "# Generated with MC-Build\n",
        "internalScoreboard": "mcb.internal",
        "rootNamespace": "mcb"
    },
    "mc-math": {
        "tempScoreboard": "mcb.eq.var",
        "constScoreboard": "mcb.eq.const"
    }
}

New Default mcb.config.json

{
    "header": "# Generated with MC-Build\n",
    "internalScoreboardName": "mcb.internal",
    "eqVarScoreboardName": "mcb.eq.var",
    "eqConstScoreboardName": "mcb.eq.const",
    "ioThreadCount": 1
}

Upgrading your MC-Build code

Many features have been updated or removed in MC-Build 3. The following sections detail the changes you will need to make to your MC-Build code to upgrade to MC-Build 3.

Compile `!LOOP`

!LOOP has been replaced with REPEAT, and has new arguments. See Compile REPEAT for more information.

The following examples show how to replace !LOOP with REPEAT for a few common use cases.

Looping over a static range: !LOOP vs REPEAT

If you were using !LOOP to loop over a static number range, you can replace it with REPEAT like this:

Original

!LOOP(1, 10, i) {
    say <% i %>
}

Updated

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

Looping over an array: !LOOP vs REPEAT

If you were using !LOOP to loop over an array, you can replace it with REPEAT like this:

Original

!LOOP(array, i) {
    say <% i %>
}

Updated

REPEAT (array) as i {
    say <% i %>
}

Compile `!IF`

!IF has been replaced with IF, ELSE IF, and ELSE, and has a few minor syntax changes. See Compile IF / ELSE for more information.

The following examples show how to replace !IF with IF for a few common use cases.

Simple !IF vs IF

If you were using !IF to check a simple condition, you can replace it with IF like this:

Original

!IF(config.my_variable == 1) {
    <...>
}

Updated

# Parentheses are no longer required, but are still allowed.
IF config.my_variable == 1 run {
    <...>
}

Complex !IF vs IF / ELSE IF / ELSE

If you were using !IF to check a more complex condition, you can replace it with IF, ELSE IF, and ELSE like this:

Original

!IF(a == 1 && b == 2) {
    <...>
}
!IF(!(a == 1) && b == 2) {
    <...>
}
!IF (!(a == 1) && !(b == 2)) {
    <...>
}

Updated

# Parentheses are no longer required, but are still allowed.
IF a == 1 && b == 2 {
    <...>
} ELSE IF b == 2 {
    <...>
} ELSE {
    <...>
}

`execute if / else`

execute(condition) {...} has been updated to be an extension of execute blocks, see execute if / else for more information.

The following example shows how to update execute if / else to the new syntax.

Example

Old

execute (if score @s my_score matches 1) {
    <...>
} else execute (if score @s my_score matches 2) {
    <...>
} else {
    <...>
}

Updated

execute if score @s my_score matches 1 run {
    <...>
} else execute if score @s my_score matches 2 run {
    <...>
} else run {
    <...>
}

`while` and `until`

while and until and thier async variants have been removed from the language, and will instead be included as part of the standard library. See the standard library's while / until page for more information.

Warning

The standard library is not yet available, so you will need to implement your own while and until loops via Templates, or wait for the standard library to be released.

`tick` and `load` functions

Tick and Load functions have been updated to be more flexible.

Instead of naming your functions tick and load, you can now name them whatever you want, and use the new function tag argument after the function name to specify what tags the function should be included in.

See Function Definitions for more information.

Updating tick and load functions

Old

function tick {
    <...>
}
function load {
    <...>
}

Updated

function my_ticking_function minecraft:tick {
    <...>
}
function my_loading_function minecraft:load {
    <...>
}

`clock` functions

Clock functions now have a required name argument.

See Clocks for more information.

Updating clock functions

Old

clock 1s {
    <...>
}

Updated

clock my_clock 1s {
    <...>
}

Macros

Macros have been replaced with the new Template system.

Converting your macros into Templates is a bit more involved, and the ease of doing so will depend on the complexity of your macros. However, the new Template system is much more powerful and flexible than the old macro system, so it is definitely worth the effort to convert them.

See the templates documentation for more information.

The following example shows how to convert a very simple macro into a Template.

Converting a simple macro into a Template

Old

macro say_this {
    say <% args[0].content %>
}

Updated

template say_this {
    with message:raw {
        say <% message %>
    }
}

Add-on Languages

lang-mc-extra and lang-mc-math have had their functionality integrated into MC-Build by default.

Migrating from MC-Build 2 to 3

Updating MC-Build 3

CLI Differences

Upgrading your config.js and config.json files

Upgrading your MC-Build code

Compile !LOOP

Compile !IF

execute if / else

while and until

tick and load functions

clock functions

Macros

Add-on Languages

Upgrading your `config.js` and `config.json` files

Compile `!LOOP`

Compile `!IF`

`execute if / else`

`while` and `until`

`tick` and `load` functions

`clock` functions