Creating a new MCreator generator

Works with
2021.1
Section
MCreator plugins

If you want to see a generator example, you can check the Fabric Generator GitHub page here or go inside the MCreator folder/plugins. However, you can’t redistribute the official generators.

Before starting

Making a new generator can be very complex and very long. You need, at least, to know the basic structure of plugins. It's highly recommended to be able to make simple a plugin. You will also need to understand how a JSON file work and Java knowledge. Finally, each generator type is different, so you will have to adapt the elements explained on this page.

Let’s start now!

The folder

Generators don't have to be inside a specific folder like procedure blocks or global triggers. However, the first part of the folder has to be a built-in generator type (forge, fabric, spigot, datapack or addon). It also requires a Minecraft (e.g. 1.16.5). These two elements have to be separated with a hyphen.

Examples: forge-1.15.2, fabric-1.16.5

Generator.yaml

The generator.yaml defines several elements of the generator. It contains its basic information, paths for the asset and data folder and many other things.

Generator selector window

name: Minecraft Forge for @minecraft (@buildfileversion)
basefeatures: [variables, model_json, model_java, model_obj]
partial_support: [item, textures]
status: stable
buildfileversion: 36.1.0
subversion: 1.0.1

Name

This name is the displayed text when the user selects a generator.

@minecraft is replaced by the version of Minecraft wrote in the generator's folder name.

@buildfileversion takes the value of the field

Base features

Basic features are the supported file types (JSON, Java and OBJ) by this generator, variables and textures. All features inside this parameter will be marked as fully supported by the generator.

Partial support

This list can contain the previous base feature, but also the mod elements. Elements in this list will be marked as supported partially (the yellow icon).

Status

The current status of the generator. Supported status are: deprecated, dev(In development), experimental, legacy, lts (Long Term Support) and stable

Build file version

If your generator uses an API like Forge or Fabric, this parameter takes the version of this API. However, if your generator doesn't use an external API, you should put this value to 1.0.

When a newer version is set, all workspaces using this generator will be re-compiled, the same way MCreator does when you install a new version.

Subversion

It works the same as the previous parameter, except it can be used to set up another time the workspace, even if the build file version is the same one.

Gradle tasks

# gradle task definitions
gradle:
  setup_task: eclipse
  run_client: runClient
  run_server: runServer
  export_file: "build/libs/modid-1.0.jar"

Setup task

(Optional) This Gradle task will be executed every time a workspace will be set up.

Run client

(Optional) The task to execute when the user clicks on the "Run client" icon.

Run Server

(Optional) The task to execute when the user clicks on the "Run server" icon.

Export file

This is the location of the file to export when the user clicks on the "Export modification" icon. This file has to be inside the workspace folder.

Roots

Basic generator roots

# base generator roots
source_root: "@WORKSPACEROOT/src/main/java"
res_root: "@WORKSPACEROOT/src/main/resources"
mod_assets_root: "@RESROOT/assets/@modid"
mod_data_root: "@RESROOT/data/@modid"

@WORKSPACEROOT can't be changed as it is the path to the current workspace.

Source root

The folder where MCreator will save code files. For example, in the Forge and Fabric generators, Java files and packages are saved in this root.

Res root

The folder where MCreator will save all resource files.

Mod assets root

The folder used for the asset files (e.g. textures and sounds).

Mod data root

The folder used for the data files (e.g. structure files and tags).

Specific directories

# specific resource folders
structures_dir: "@MODDATAROOT/structures"
sounds_dir: "@MODASSETSROOT/sounds"
other_textures_dir: "@MODASSETSROOT/textures"
block_textures_dir: "@MODASSETSROOT/textures/blocks"
item_textures_dir: "@MODASSETSROOT/textures/items"
armor_textures_dir: "@MODASSETSROOT/textures/models/armor"
Structures

The directory for the structure files. If not defined, structures won't be available with this generator.

Sounds

The directory for the sound files. If not defined, sounds won't be available with this generator.

Other

The directory for the textures added in Other.

Block

The directory for the textures added in Block.

Item

The directory for the textures added in Item.

Armor

The directory for the _layer_1 and _layer_2 textures of armors.

Base templates

For this part, I won’t put everything on the Forge generator because there are too many things. If you want to have all of them, I suggest you to go check into the generator-1.14.4 in the MCreator plugin folder (< install dir>/plugins).

#Some templates of the Forge 1.16.5 generator
base_templates:
  - template: modbase/mod.java.ftl
    name: "@SRCROOT/@BASEPACKAGEPATH/@JavaModName.java"
    canLock: true
  - template: modbase/mods.toml.ftl
    writer: file
    name: "@RESROOT/META-INF/mods.toml"
  - template: json/fluidtag.json.ftl
    writer: json
    condition: hasFluids()
    deleteWhenConditionFalse: true
    variables: "type=lava"
    name: "@RESROOT/data/minecraft/tags/fluids/lava.json"

Base templates are basic files needed by the modification to work properly. These files are only added one time and can't be seen by users in the workspace UI. They can have some parameters.

Template

Every time a template line is added, a new template file is defined. This line has to contain the path of the template file inside the templates folder of the generator.

Name

The name and the location of the generated file when the setup task is executed.

Can lock

(Optional) A boolean value defining if this file can be locked (from the Workspace setting option).

Writer

(Optional) The default writer used by MCreator is Java. However, if the file is not a Java file, you can use another writer. json and file can be used.

Condition

(Optional) The needed condition to generate the file. Only built-in conditions can be used.

Delete when condition false

(Optional) The value has to be used with the condition parameter. If the condition is not met, does MCreator delete the file?

Variables

(Optional) If some variables are needed for FreeMarker in the template file, you can add them there.

Resource tasks

resources_setup_tasks:
# Forge 1.16.5
  - task: copy_file
    from: "@MODASSETSROOT/textures/@modpicture.png"
    to: "@RESROOT/logo.png"
  - task: copy_models
    type: OBJ_inlinetextures
    prefix: "@modid:blocks/"
    to: "@MODASSETSROOT/models/item"
  - task: copy_models
    type: JSON_noinlinetextures
    to: "@MODASSETSROOT/models/custom"

# Addons 1.16.5
  - task: copy_and_resize_image
    width: 128
    height: 128
    from: "@MODASSETSROOT/textures/@modpicture.png"
    to: "@RESROOT/pack_icon.png"
  - task: copy_and_resize_image
    width: 128
    height: 128
    from: "@MODASSETSROOT/textures/@modpicture.png"
    to: "@SRCROOT/pack_icon.png"

Several tasks can be used, but the main ones are shown above. Available tasks can be found here.

Language files

language_file:
  format: json
  root_folder: "@MODASSETSROOT/lang/"
  langfile_name: "@langname.json"

Workspace Base folder

This folder (workspacebase) contains every file needed to create the workspace. Files contained in this directory can't be explained because each generator type works differently, so they will have different files. However, gradle/wrapper should be the Gradle wrapper used by the generator type (e.g. Forge and Fabric don't use the same Gradle wrapper).

Definition files

To support a mod element, you have to add its definition file (`modelementid`.definition.yaml). Inside the file, you will have to write the template file(s) of this mod element, including the path to the file. However, all template files have to be saved inside the templates folder of the generator.

templates:
  - template: armor.java.ftl
    name: "@SRCROOT/@BASEPACKAGEPATH/item/@NAMEItem.java"
  - template: json/item.json.ftl
    writer: json
    condition: enableHelmet
    deleteWhenConditionFalse: true
    variables: "item=helmet"
    name: "@MODASSETSROOT/models/item/@registryname_helmet.json"

Localization keys

Some mod elements contain translatable texts. So, to be added in the Localization tab of the workspace, every translatable option has to be added here.

localizationkeys:
  - key: item.@modid.@registryname_helmet
    mapto: helmetName

Key

The key is used in the language file and in the code to get the text for each language. This key can also be seen in the localization tab of the workspace.

Mapto

The name of the variable saving the value of the mod element's UI.

Templates

This folder contains all template files used by the generator. To organize the folder, you can create your own folders. However, the location of the files will also have to contain this folder.

Mod base

modbase is the folder containing all templates you defined sooner in the base_templates of the generator.yaml.

Utils

When making a big generator, we often need to generate the same code in several template files. So, in this folder, you can also add template files helping to generate a specific code.

Examples

Bounding boxes

For example, with MCreator 2021.1, a new bounding box editor has been made. This new editor has also been implemented for custom plants. As bounding boxes can now be very complex, a new util file has been created (boundingboxes.java.ftl). This file contains some FreeMarker macros generating a specific code allowing users to create very complex shapes as these same macros are executed for every bounding box entry.

MCItems

Blocks and items are used everywhere in Minecraft and MCreator. However, to generate the proper code every time, this file has been created. This file is a simple FreeMarker file containing exclusively the code of FreeMarker. Using several functions and conditions, the mapping name will always be transformed for the right code.

See also
Developing MCreator plugins
Creating new procedure blocks
Creating new AI task blocks
Creating global triggers
Creating APIs
Mod Element Types
How to make a Fabric based mod for Minecraft
How to make a Spigot plugin for Minecraft Server
References
Default MCreator plugins https://github.com/MCreator/MCreator/tree/master/plugins
The Fabric Generator https://github.com/ClothCreators/Fabric-Generator-MCreator


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