Creating new procedure blocks

Section
MCreator plugins

Making the procedure block

The folder

To be seen by MCreator, JSON files defining procedure blocks have to be in the base root of the plugin (with the plugin.json) and then, create a new folder named "procedures". Then, all of your JSON files will have to create there.

Making the JSON file

Block's ID

The name of the file is important as it will be the block's ID. Your block's ID should:

  • Not contain capital letters
  • Not contain spaces (Use underscores)
  • Not contain other language words (English should always be used)
  • Avoid using the plugin ID
  • Begin with the Minecraft type (entity, gui, world, world_data (world getters), etc.) except for some exceptions

Displayed text

To set the text, you have 2 options, localization files or integrated into the JSON file

Localization files

Localization files are the files used by MCreator to be able to translate the UI. Every localization file has to be inside "base_root/lang/". Then, add a new file named "texts.properties". This is the basic file used by MCreator. It has to contain all English translations. To add other language support, you can add _fr_FR to support French, _it_IT to support Italian, etc. You can see all suffixes in the built-in plugin named "mcreator-localization".

When you are inside a localization file, add a new line starting with "blockly.block.theBlockID=" and then, simply write the text to display on the block. To use one or multiple arguments, simply add %  + the argument's number.

This number will be its place in the argument list of the JSON file.

Tooltip

To add a tooltip to your block when the user moves the cursor on the block, simply add a new line finishing with ".tooltip".

blockly.block.my_amazing_block=Get JSON logic property %1 of %2
blockly.block.my_amazing_block.tooltip=Split JSON objects with a comma (e.g. first, second) to go in a subobject

Note: All default procedure blocks use this way.

Integrated

Another way to add the text is by adding a "message0" field at the beginning of the JSON file. Then, simply do the same thing as for localization files

Arguments

This section is used to declare the type of each variable you have put before. The first variable will be the %1 you have put in the ”message0”.

There are 3 argument types: fields, inputs and input_statements. To learn what they can do, you should read this Wiki page.

Extensions

Extensions allow you to add create a new dropdown field containing values of a mapping file or all elements of a specific mod element type.

To add extensions, simply add a new field named "extensions". This field has to be a list as you can add multiple extensions in a single block.

Several extensions exist and can be used. You can find them in the default procedure blocks of MCreator.

To use the value of an extension, you need to register the field of this extension in "fields". The name, however, has to be specific. You can get it by checking the default blocks. You can also check this file if you have some knowledge of Java.

The colour

"colour" is the field that defines the colour of the block in the Blockly editor. You can use built-in Blockly colours or use the HUE.

Read this page to have more information about colours with Bockly.

Built-in Blockly colours

"%{BKY_MATH_HUE}" for blocks related to maths or numbers.

"%{BKY_LOGIC_HUE}" for blocks related to logic.

"%{BKY_TEXTS_HUE}" for blocks related to String/texts.

These colours are the built-in colours used in current MCreator blocks, but you can also use the other ones.

HUE

You can also use a custom HUE colour by writing a number between 0 and 360.

Type

There are output blocks (mainly used as getters) and procedure blocks (used to execute an action).

Output

To create an output block, you simply need to add a field named "output" and write the output type of the block. Types can be seen with the default blocks.

Procedural

Procedural blocks will need two fields, "previousStatement" and "nextStatement". The first one will indicate if the block can have other procedural blocks before it (which is always the case, so you need to set its value to null). The second field will indicate if new procedural blocks can be added after this block. This parameter is set to false with the "Cancel action" block.

The MCreator section

Toolbox ID

This field defines the category of the block. You need to write the category's ID. Users will find the block in this category.

Following categories are not created in a plugin, but you can still use them.

  • other
  • apis
  • mcelements
  • mcvariables
  • customvariables
  • logicloops
  • logicoperations
  • math
  • text
  • advanced
Toolbox init

This field is optional as it can only be used with input arguments. This field is a list and is used to add a specific output block in an input argument. If you do not define value, the input value will be empty. The code to add has to be the XML code, so Blockly recognizes it. The simplest way to do it is by creating your block, then add the output block you would like to have and finally, check the XML code of the procedure element (yourWorkspace/elements/yourProcedure.json).

Fields

List all field arguments you defined as arguments in this section. If you add extensions, you will also need to add their field name here. These names have to be the same as you put. This way, MCreator will be able to register these fields to add them to the code template.

Inputs

List all inputs arguments you defined as arguments in this section. These names have to be the same as you put. This way, MCreator will be able to register these inputs to add them to the code template.

Statements

List all input statements arguments you defined as arguments in this section. Instead of the fields and inputs, statements have to be an object. The name will have to be defined with a field named "name". Optionally, you can add a list named "provides" to add a list of dependency objects provided by the statement. See world_entity_inrange_foreach to get an example. This way, MCreator will be able to register these statements to add them to the code template.

Dependencies

A dependency is a variable needed by the block to properly work. If the global or external trigger does not provide this dependency, the procedure will not be called or will return an error in the console.

A dependency has 2 fields, name and type. The name will only be the text displayed on the sidebar of the Blockly editor. The type (the class if you want) is the thing used by MCreator to generate the code and to check if the procedure can be used with a trigger. You can find the types in a mapping file named "types.yaml" inside each generator. You can also add your own dependency type by creating this file in your plugin for each generator you need.

General types (String, number and logic) do not have to be declared as a dependency, except if a specific dependency needs to be used.

Examples

Procedural

(Read JSON procedure block from File Manager)

{
  "args0": [
    {
      "type": "field_input",
      "name": "var"
    },
    {
      "type": "input_statement",
      "name": "values"
    },
    {
      "type": "field_input",
      "name": "jVar"
    }
  ],
  "inputsInline": true,
  "previousStatement": null,
  "nextStatement": null,
  "colour": 260,
  "mcreator": {
    "toolbox_id": "file_manager",
    "statements": [
      {
        "name": "values"
      }
    ],
    "fields": [
      "var",
      "jVar"
    ]
  }
}
Output

(Get JSON logic from File Manager)

{
  "args0": [
    {
      "type": "input_value",
      "name": "name",
      "check": "String"
    },
    {
      "type": "field_input",
      "name": "vars"
    }
  ],
  "output": "Boolean",
  "colour": "%{BKY_LOGIC_HUE}",
  "mcreator": {
    "toolbox_id": "file_manager",
    "toolbox_init": [
    "<value name=\"name\"><block type=\"text\"><field name=\"TEXT\">name</field></block></value>"
    ],
    "inputs": [
      "name"
    ],
    "fields": [
      "vars"
    ]
  }
}

Create your procedure block section

To have your section, return to your ”procedures” folder. Then, create a new JSON file. The name of your file has to start with a $. After, put the name of your section without space. This name (without $) will be the ID of the category. Conventions are the same as the procedure blocks.

{
  "name": "Wiki tutorial",
  "color": 110
}

Name

The name of the category can be localized or defined in the file.

Localized file

It works the same as procedure blocks, except you will have to use "blockly.category.categoryID".

Integrated

As you see on the code before, you simply need to add a field named "name" with the name of the category.

Color

You can only use a HUE value, so a number between 0 and 360.

Make the code of your procedure block

The folder

Each generator you want to support will need to have a template file.

In the generator folder, create a new folder named "procedures" and then, create a new file following this template: blockID.java.ftl.

The code

Values

  • Fields will need to be ${field$fieldName}
  • Inputs will need to be ${input$inputName}
  • Input statements will need to be ${statement$statementName}

FreeMarker code

MCreator uses FreeMarker to generate its code. It allows us to use the amazing things FreeMarker gives.

To see a full guide, read the official guide of Apache here. You can also check other procedure blocks to have real examples.

Example

(Read JSON procedure block from File Manager)

{
	try {
		BufferedReader ${field$var}Reader = new BufferedReader(new FileReader(${field$var}));
		StringBuilder jsonstringbuilder = new StringBuilder();
		String line;
		while((line = ${field$var}Reader.readLine()) != null) {
			jsonstringbuilder.append(line);
		}
		${field$var}Reader.close();

		JsonObject ${field$jVar} = new Gson().fromJson(jsonstringbuilder.toString(), JsonObject.class);
		${statement$values}
  
	} catch (IOException e) {
		e.printStackTrace();
	}
}

Video tutorial

If you prefer to watch the video, you can find the wiki page above summarized in a video:

 
See also
How to use Blockly in plugins
Developing MCreator plugins
Creating new AI task blocks
Creating a new MCreator generator
References
Official Blockly's Documentation https://developers.google.com/blockly/guides/create-custom-blocks/overview
Official FreeMarker's Documentation https://freemarker.apache.org/docs/index.html


Donate to MCreator

By donating to developers you can speed up development, as with more resources, we can dedicate more time to MCreator. It is a free project made by developers working on it in their free time.

Donate now