Skip to content

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.