Skip to content

Tutorial: Your First Mod

Jump to bottom
Eric edited this page Nov 10, 2023 · 8 revisions

Step 1. Download Prerequisites

You will first need to download the following programs:

Step 2. Setup PickHaxe

Run the following command to check that Haxe is installed properly:

haxe -version

Once you verify it is installed, you can download PickHaxe via HaxeLib. HaxeLib will automatically install any Haxe dependencies for you:

haxelib install pickhaxe

Step 2.1. Setup PickHaxe Nightly (Optional)

If you wish to download and use the latest development version of PickHaxe, you may run into some bugs, but also benefit from the latest features and bugfixes.

To use nightly releases, install PickHaxe from this repository:

haxelib git pickhaxe https://github.com/EliteMasterEric/PickHaxe develop

Step 3. Install PickHaxe Tool

You can improve the convenience of using the PickHaxe build tool by adding it to your system path.

haxelib run pickhaxe setup

NOTE: This step is optional but highly recommended. NOTE: On previous versions, this command needed to be rerun every update, but this is no longer the case.

Step 4. Initialize a New Project (or Download a Sample Project)

Once you are ready to start, create an empty folder for your project and run:

pickhaxe init

The setup should walk you through choosing a mod ID, and other steps to initialize your basic project.

The project files will generate in your current folder. Once you are done, it will look like this:

|- .vscode/
  |- settings.json
|- src/
  |- <mod-path>
    |- ModIdMod.hx
|- resources/
  |- assets/
    |- <mod-id>
  |- data/
    |- <mod-id>
|- .gitignore
|- project.xml

If you wish, you may instead download one of PickHaxe's sample projects. These are available on their repository, or via the pickhaxe template command:

// View the list of templates
pickhaxe template --list
// Download a specific template
pickhaxe template madeinhaxe

Step 5. Develop

Write code into the files in your source path.

Via Haxe's automatic extern generation, you can directly access any classes which are available in your target version of Minecraft (use the official Mojang mappings or Parchment mappings when looking up documentation). You can also access classes for your target loader.

import net.minecraft.world.entity.EntityType;
import net.minecraft.world.entity.monster.Creeper;

var creeper:Creeper = new Creeper(EntityType.CREEPER, level);
creeper.setPosition(player.getPos());
world.spawnEntity(creeper);

Note that PickHaxe provides a body of compatibility shims for many common use cases. These are available in the net.pickhaxe.compat package, and more are being added all the time. They strive to provide the full functionality of the parent classes, in a manner which matches the latest release version of Minecraft, while attempting to standardize functionality across versions of Minecraft and across mod loaders.

If a compatibility shim class does not exist for a given class, or lacks functionality you need, this does not mean PickHaxe does not support those features, but rather, that it is on the developer using PickHaxe to make their mod to either develop for a single Minecraft version and mod loader, or to utilize compile defines to include or exclude code for specific builds.

If you are targeting a single Minecraft version and mod loader this way, the net.pickhaxe.compat package can be completely ignored, and you may simply access Minecraft's APIs and your loader's APIs directly; with this workflow, the mod's source becomes extremely similar to a standard Java project, except the resulting source code can make use of Haxe's syntax and language features. See the madeinhaxe-bare sample projects for examples of this.

If you want to distinguish between mod loaders in your own code, use the provided compile defines:

#if fabric
LOGGER.info('Hello Fabric World! Welcome to Minecraft ${Environment.MINECRAFT_VERSION}!');
#end

#if forge
LOGGER.info('Hello Forge World! Welcome to Minecraft ${Environment.MINECRAFT_VERSION}!');
#end

If you want to distinguish between Minecraft versions, use the provided compile defines:

#if minecraft_gteq_1_19_3
LOGGER.info('Hello, Minecraft 1.19.3 or newer!');
#end

#if minecraft_lt_1_19_3
LOGGER.info('Hello, Minecraft before 1.19.3!');
#end

Step 6. Build and Make

Building the project is simple. First run the following command:

pickhaxe build fabric 1.20.2

The build command takes two arguments; the mod loader to target, and the Minecraft version to target. This generates a deobfuscated, "development" mod JAR in your ./build/fabric/1.20.2/ folder, or the appropriate folder for the loader and version you selected.

To create an obfuscated JAR that is ready for use in Minecraft, use the make command. The resulting JAR will be placed alongside the -dev.jar.

pickhaxe make fabric 1.20.2

Pro Tip: You can run the build command with the --make argument to automatically perform the make step after build is complete.

PickHaxe Wiki

Tutorials

Documentation

Clone this wiki locally