Creating new AI task blocks

Making the AI 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 "aitasks". 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

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. You will surely only use this type for AI tasks.

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.

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.

Create your AI task

To have your section, return to your ”aitasks” 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 AI task 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.

Coding your AI task

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}
• ${customBlockIndex+1} will be used to get the position of the task.

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.

Making the code file

When you are inside of the folder, create a new file with the extension .java.ftl. For the name of the file, write the same name you have wrote for the JSON file. Open the file, and write the code of the AI task. This is the code of my block :

this.goalSelector.addGoal(${customBlockIndex+1}, new FollowParentGoal(this, ${field$speed}));

You can see a ${customBlockIndex+1} and a ${field$speed}. The first one is used to set the position number of the task whatever where it will be in the builder. The second is used to set the number (in this case) that the player has put for the argument ”speed”. For your fields, change ”speed” by the name you have set up. If you have inputs, change the ”field” for ”input”.

Save your file and you are done! You can now export your plugin in a .zip file and test it.

Video tutorial

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