Create the extension

Setup a new project

Make a new world

Start creating your own blocks by opening Minecraft Education Edition. Once you have Minecraft running, create a new world to test with. Any kind of world is fine but flat worlds are easier to work with.

Open Code Builder

Open Code Builder in your game by pressing C on the keyboard. Create a project and give it the name of your custom blocks extension.

If Code Builder is only taking up half the screen, recommend switching to larger window mode. Display the side menu (☰) and select Larger Window..

Now, switch the editor from Blocks to JavaScript.

Create some custom blocks

Click on the Settings (⚙️) gearwheel and choose Toggle the File Explorer in the menu. The Explorer pane will open at the left of the Editor window.

On the Explorer heading in File Explorer, click on the [➕] button to add some custom blocks.

Next, you’ll see a new Toolbox category called CUSTOM and some code added to your Workspace in the JavaScript editor window.

These custom blocks are vaild code and you can use them right away in your project if you want. One is a block called fib and the other is called foo.

You won’t use these new custom blocks as they are though. Instead, they will serve as a starting point to create the blocks in your extension. You’ll change this code to make your own specialized blocks and namespace.

The code created in the new custom.ts file, now shown in the editor, currently contains this:

/**
* Use this file to define custom functions and blocks.
* Read more at https://minecraft.makecode.com/blocks/custom
*/

enum MyEnum {
    //% block="one"
    One,
    //% block="two"
    Two
}

/**
 * Custom blocks
 */
//% weight=100 color=#0fbc11 icon=""
namespace custom {
    /**
     * TODO: describe your function here
     * @param n describe parameter here, eg: 5
     * @param s describe parameter here, eg: "Hello"
     * @param e describe parameter here
     */
    //% block
    export function foo(n: number, s: string, e: MyEnum): void {
        // Add code here
    }

    /**
     * TODO: describe your function here
     * @param value describe value here, eg: 5
     */
    //% block
    export function fib(value: number): number {
        return value <= 1 ? value : fib(value -1) + fib(value - 2);
    }
}

Code your own custom blocks

As an example, let’s say we want to make an extension that has two code blocks for building walls. We want to call our extension BuildWall.

Let’s modify this code to make the blocks for the BuildWall extension.

Description comment

First, change the file description comment to describe what your extension blocks will do.

/**
* Use this file to define custom functions and blocks.
* Read more at https://minecraft.makecode.com/blocks/custom
*/

This is changed to say:

/**
* An extension to build walls and enclosures
* using width and height parameters.
*/

Remove unused code

Next, erase the code for the enum. We won’t use that in this example.

enum MyEnum {
    //% block="one"
    One,
    //% block="two"
    Two
}

Set the namespace information

You’ll notice that the Toolbox contains the category CUSTOM for the new code blocks contained in custom.ts. This category name comes from the namespace that surrounds the code that makes up your custom code blocks. You can see this on the line of code with namespace custom {. Also, there is a special comment line with some attributes for the namespace which indicate where to place the category in the Toolbox, the color that the custom code blocks will have, and the icon displayed with the category name.

/**
 * Custom blocks
 */
//% weight=100 color=#0fbc11 icon=""
namespace custom {
    ...
}

Let’s change the namespace name and attributes to uniquely identify our extension in the Toolbox and editor. Use the name BuildWall for the namespace and set a different color as well as a different icon.

/**
 * BuildWall blocks
 */
//% weight=100 color=#FF8040 icon="\uf00a"
namespace BuildWall {
    ...
}

Make your first custom block

Go to the code for the foo() function.

    /**
     * TODO: describe your function here
     * @param n describe parameter here, eg: 5
     * @param s describe parameter here, eg: "Hello"
     * @param e describe parameter here
     */
    //% block
    export function foo(n: number, s: string, e: MyEnum): void {
        // Add code here
    }

Let’s change the code for the foo() function to make it build a wall using blocks.fill() from the existing BLOCKS category. Inside the comment section, add a descriptions for the function and the parameters.

    /**
     * Build a single wall of blocks
     * @param wide number of blocks wide, eg: 5
     * @param high number of blocks high, eg: 2
     * @param block the block to build with, eg: BRICKS
     */

Next, we’ll define the code block attributes. The block attribute will have the text and parameter inputs that are displayed on the code block when it’s displayed in the Blocks editor. One other attribute is added called block.shadow. This gives a nice symbolic view of the block parameter with a dropdown selection list for choosing a block to build the wall with.

    //% block="build a wall %wide wide by %high high using %block"
    //% block.shadow=minecraftBlock

We’re now going to change the code for the foo() function to our wall building function. Replace the name foo with buildWall. Use the parameters shown in the following example instead of the ones currently used by foo(). Insert the blocks.fill() code as shown inside the body of buildWall().

    export function buildWall(wide: number, high: number, block: number): void {
        blocks.fill(
            block,
            pos(2, 0, 0),
            pos(2, high, wide),
            FillOperation.Replace
            )
    }

Make your second custom block

Go to the fib() function replace it with another custom code block.

    /**
     * TODO: describe your function here
     * @param value describe value here, eg: 5
     */
    //% block
    export function fib(value: number): number {
        return value <= 1 ? value : fib(value -1) + fib(value - 2);
    }

If you can’t think of another function to make right now, just replace fib() with the code for the enclosure() function here.

    /**
     * Build a square enclosure of blocks
     * @param wide number of blocks wide, eg: 5
     * @param high number of blocks high, eg: 2
     * @param block the block to build with, eg: BRICKS
     */
    //% block="build an enclosure %wide wide by %high high using %block"
    //% block.shadow=minecraftBlock
    export function enclose(wide: number, high: number, block: number): void {
        blocks.fill(
            block,
            pos(wide / -2, high, wide / -2),
            pos(wide / 2, high, wide / 2),
            FillOperation.Outline
            )   
    }

Test your custom code blocks

Go back to the Blocks editor and take a look in the Toolbox. You should see a new BUILDWALL category with your custom blocks.

Put your new custom code blocks into chat commands. Then, go back the game world and try them to see if they work as you expect.

Publish and share!

Now that you have your custom code blocks working, you’re ready to publish your extension . Read on and find out how to get your extension out to the rest of the world!