🛠️ Hytale Plugin Template

A simple, ready-to-use Java plugin template for Hytale that takes care of the setup so you can focus on making cool stuff.

What it handles for you:

• Classpath configuration
• Running the server
• Bundling assets

⚠️ Early Access Notice
Hytale is in Early Access, so things can change fast. Make sure you’re always using the latest version of this template.

---

📋 Prerequisites

Before you start, make sure you have:

• Hytale Launcher: Installed and updated.
• Java 25+: Required for Hytale development.
• Supported IDE:
  • IntelliJ IDEA (Recommended)
  • VSCode

---

🚀 Quick Start

1️⃣ Configure Your Project

Edit gradle.properties to match your plugin/project:

# Plugin Manifest
plugin_group=ExampleGroup
plugin_name=ExamplePlugin
plugin_description=An example Hytale server plugin.
plugin_author=YourName
plugin_website=https://example.com
plugin_main_entrypoint=com.example.myplugin.ExamplePlugin
plugin_version=1.0.0
server_version=*

Important: Ensure "plugin_main_entrypoint" points exactly to your plugin's main class. After editing, reload Gradle in your IDE to apply changes

2️⃣ Import the Project

1. Open your recommended IDE (IntelliJ IDEA) or supported alternative (VSCode) and select Open Project.
2. Navigate to the template folder and confirm.
3. Wait for Gradle to finish.

3️⃣ Authenticating your Test Server

You must authenticate your local server to connect to it:

1. Launch the HytaleServer configuration in IDEA.
2. Run in the terminal: auth login device.
3. Follow the printed URL to log in via your Hytale account.
4. After verification, run: auth persistence Encrypted.

---

🎮 Developing & Testing

Running the Server

If the Hytale Server option is not visible in the run configuration dropdown, check your IDE’s Gradle panel. Locate the runServer task and run it from there.

Verifying the Setup

1. Launch your standard Hytale Client.
2. Connect to Local Server (127.0.0.1).
3. Type /test in-game. If it returns your plugin version, everything is working!

Bundling Assets

You can include models and textures by placing them in src/main/resources/Common/ or src/main/resources/Server/. These are editable in real-time using the in-game Asset Editor.

Changing the Plugin Icon

You can change the plugin icon by replacing resources/Common/UI/Custom/ExampleGroup_ExamplePlugin.png with your new icon.

Make sure the icon file name follows this format: <Group>_<Name> and matches the values defined in your gradle.properties:

plugin_group=ExampleGroup
plugin_name=ExamplePlugin

---

📦 Building your Plugin

To create a shareable .jar file for distribution:

1. Open the Gradle Tab on the right side of IDEA.
2. Navigate to Tasks -> build -> build.
3. Your compiled plugin will be in: build/libs/your-plugin-name-1.0.0.jar.

To install it manually, drop the JAR into %appdata%/Hytale/UserData/Mods/.

---

📚 Advanced Documentation

For detailed guides on commands, event listeners, and professional patterns, visit our full documentation: 👉 Hytale Modding Documentation

---

🆘 Troubleshooting

• Sync Fails: In Intellij IDEA, Check that your Project SDK is set to Java 25 via File > Project Structure.
• Cannot Connect: Ensure you ran the auth commands in the server console.
• Plugin Not Loading: Double-check your gradle.properties for typos in the "plugin_main_entrypoint" classpath.

---

Need Help? Visit our full guide here: Hytale Modding Documentation