Migrating from Older Versions

Warning

MC-Build 3 and later are 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.

If you're upgrading from MC-Build 3, see Upgrading from MC-Build 3 to 4.

Updating MC-Build

If you already have an older version installed, you can run this command to overwrite it, and install the latest version globally.

npm i -g mc-build@latest

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

See Configuration for all of the options.

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

See Configuration for all of the options.

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 {
    <...>
}

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 their async variants have been removed from the language. You can implement your own while and until loops with Templates.

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

Upgrading from MC-Build 3 to 4

Function references need a namespace or prefix

MC-Build no longer adds the current namespace and folder to a bare function name. A bare name such as function my_function is now a compile error. Add ./ to call a function in the same folder, or use a full namespace:path reference. See Function Calls for all of the reference types.

Updating function references

Old

function test {
    function demo
    schedule function demo 1t
}

Updated

function test {
    function ./demo
    schedule function ./demo 1t
}

Libraries

Library support has been removed. Use Templates and imports to share code between projects.

Comments

# comments are now removed from the output. Use \# to keep a comment in the generated .mcfunction file. See Comments.

Migrating from Older Versions

Updating MC-Build

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 from MC-Build 3 to 4

Function references need a namespace or prefix

Libraries

Comments

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

Compile `!LOOP`

Compile `!IF`

`execute if / else`

`while` and `until`

`tick` and `load` functions

`clock` functions