Build and Test Your Mod

If you followed along with the Setting Up Your Development Environment page, you should now be able to build your project.

Building Your Mod

In our case, we've used Gradle as the build system. Gradle is a powerful build automation tool that manages dependencies, compiles your code, and packages everything into a distributable JAR file.

Understanding Gradle

Gradle can use a build.gradle.kts file (Kotlin DSL) and gradle.properties to define your project's configuration, dependencies, and build settings. You can learn more about Gradle at the official Gradle website.

Building with Gradle

To build your mod, open a terminal in your project directory and run:

// Windows
gradlew.bat build

// Linux/MacOS
./gradlew build

This command will:

Compile your Java source code
Run any tests (if present)
Package everything into a JAR file

Info

If you are using the plugin template from the Setting Up Your Development Environment guide, then the build script is already set up for you. It automatically grabs Hytale server jar/assets and handles the packaging of your mod, managing hytale dependencies and manifest changes.

You can change the project to using your game installs Asset zip by uncommenting a property to your gradle.properties file:

hytaleHomeOverride=/path/to/Hytale/install/release/package/game/latest/Assets.zip

and build.gradle.kts file:

hytaleHomeOverride = property("hytaleHomeOverride").toString()

Build Output

Once the build completes successfully, your mod will be located in the build/libs directory and named:

ExamplePlugin-1.0.jar

Info

The exact name may vary depending on what you configured in your gradle.properties file. Check the mod_name and version fields to see what your JAR will be named.

Testing Your Mod

Now that you've built your mod, it's time to test it in Hytale!

1. Locate the Mods Folder

First, you need to find Hytale's mods directory:

Go to your Hytale installation directory (The default location is usually in your AppData folder)

On Windows, you can access it by clicking windows + R and typing %appdata%.
Navigate to: /UserData/Mods

The default path would look like:

C:\Users\YourUsername\AppData\Roaming\Hytale\UserData\Mods

Warning

If the Mods folder doesn't exist, you may need to create it manually or launch Hytale at least once.

2. Copy Your Mod

Copy the ExamplePlugin-1.0.jar file from your project's build/libs directory into the Mods folder you just located.

3. Launch Hytale and Verify

Start Hytale
Click "Create a New World"
Click the settings cog
Click "Mods"
See your mod in the list!

If your mod appears in the list, congratulations! Your mod has been successfully loaded by Hytale.

Testing Your Mod Without Building

Now that you have verified your project builds and runs in Hytale, you'll want to test it as you do development. To do this, simply run the runServer task or manually via:

// Windows
gradlew.bat runServer

// Linux/MacOS
./gradlew runServer

This will start and run a local Hytale server. You'll connect in your game adding a private server pointing to localhost. This server will run your mod and any dependencies you have added via your build.gradle.kts file.

Troubleshooting

If your mod doesn't appear in the mods list:

Make sure the JAR file is in the correct Mods folder
Check that your manifest.json file is properly configured
Look for any error messages in the Hytale logs
Verify that you're using the correct version of Java and Gradle

Next Steps

Now that you can build and test your mod, you're ready to start adding functionality! Check out these guides:

Create Commands - Add custom commands to your mod
Create Events - React to in-game events

Happy modding!

Build and Test Your Mod

On this page