Creating APIs

What is an API?

In MCreator, an Application Programming Interface is an external mod used to use its functionalities. For example, the GeckoLib API allows users (and normal developers) to make custom animated entities without making their own system. Another example is Obfuscate, adding new events to modify the render of the player or an item.

Making the API

The folder

Unlike global triggers or procedure blocks, custom APIs use YAML files. To be seen by MCreator, your custom API files have to be in a folder named apis. The name of the file will be the ID of your API.

Making the YAML file

Name

Simply the displayed name in the workspace settings.

Generator

To support a generator, you simply need to do the following steps with the generator's ID you want.

Required when enabled

(Optional) If this parameter is set to true, this mod (API) will be needed by all workspaces using this API.

Update files

(Optional) When the API will be deleted, these files will also be deleted. Most of the time, you will not use it.

Gradle

The code to execute when a workspace will be set up or a Gradle project will be reloaded (e.g. when adding the API to a workspace). This code will be added in the mcreator.gradlewhich is called with the build.gradle.

Example

Goldfuscate

The following example is the API file used by Goldfuscate to add the Obfuscate API.

The code is a simple implementation of an API with a single generator.

name: Obfuscate
forge-1.15.2:
  gradle: |
      repositories {
        maven {
          url = "https://www.cursemaven.com"
        }
      }
      dependencies {
          compile fg.deobf("curse.maven:obfuscate-289380:2946425")
      }

MCreator Link

The following example is the API file of MCreator Link.

The code is a more complex implementation of an API, using everything explained before and using some special code. You can also have an example of an API using multiple generators.

name: MCreator Link

forge-1.15.2:
  required_when_enabled: true
  update_files:
    - lib/mcreator_link.jar
  gradle: |
    task mcreatorLink(type: DefaultTask) {
      ant.mkdir(dir: 'lib/');
      ant.get(src: 'https://mcreator.net/link/download/dev_1.15.2', dest: 'lib/mcreator_link.jar', skipexisting: 'true');
    }

    compileJava.dependsOn mcreatorLink

    dependencies { compile files("lib/mcreator_link.jar") }

forge-1.16.5:
  required_when_enabled: true
  update_files:
    - lib/mcreator_link.jar
  gradle: |
    task mcreatorLink(type: DefaultTask) {
      ant.mkdir(dir: 'lib/');
      ant.get(src: 'https://mcreator.net/link/download/dev_1.16.5', dest: 'lib/mcreator_link.jar', skipexisting: 'true');
    }

    compileJava.dependsOn mcreatorLink

    dependencies { compile files("lib/mcreator_link.jar") }

Go further

Some APIs may need to add new procedure blocks or triggers to have their full potential.

Required APIs in procedures

Procedure blocks and global triggers have an option to require one or several APIs.

Procedure blocks

In the MCreator section of your procedure block, you can a list of the API IDs you need inside a list named required_apis.

[...]
"mcreator": {
    "toolbox_id": "mcreatorlink",
    "required_apis": [
      "mcreator_link"
    ]
  }
[...]

Global triggers

For global triggers, it works the same as procedure blocks, except you just need to put the required_apis in the main object.

{
  "dependencies_provided": [
    [...]
  ],
  "required_apis": [
    "mcreator_link"
  ]
}