Hytale Plugin Template

A minimal, ready-to-use template for creating Hytale plugins with modern build tools and automated testing.

✨ Builds immediately without any changes! Clone and run ./gradlew shadowJar to get a working plugin JAR.

Features

✅ Modern Build System - Gradle with Kotlin DSL
✅ Automated Testing - Custom Gradle plugin for one-command server testing
✅ Java 25 - Latest Java features
✅ ShadowJar - Automatic dependency bundling
✅ CI/CD Ready - GitHub Actions workflow included
✅ Minimal Structure - Only essential files, write your own code

---

Quick Start

Prerequisites

• Java 25 JDK - Download here
• IntelliJ IDEA - Download here (Community Edition is fine)
• Git - Download here

1. Clone or Download

git clone https://github.com/yourusername/hytale-plugin-template.git
cd hytale-plugin-template

The template builds immediately without any changes!
You can customize it later when you're ready to develop your plugin.

2. Build Immediately (No Changes Needed!)

The template works out-of-the-box:

# Windows
gradlew.bat shadowJar

# Linux/Mac
./gradlew shadowJar

Your plugin JAR will be in: build/libs/TemplatePlugin-1.0.0.jar

3. Customize Your Plugin (Optional)

When ready to customize, edit these files:

settings.gradle.kts:

rootProject.name = "your-plugin-name"

gradle.properties:

pluginGroup=com.yourname
pluginVersion=1.0.0
pluginDescription=Your plugin description

src/main/resources/manifest.json:

{
  "Group": "YourName",
  "Name": "YourPluginName",
  "Main": "com.yourname.yourplugin.YourPlugin"
}

Rename the main plugin class:

• Rename src/main/java/com/example/templateplugin/TemplatePlugin.java
• Update package name to match your pluginGroup

4. Build Your Plugin

# Windows
gradlew.bat shadowJar

# Linux/Mac
./gradlew shadowJar

Your plugin JAR will be in: build/libs/YourPluginName-1.0.0.jar

5. Implement Your Plugin

Write your plugin code in src/main/java/:

• Commands
• Event listeners
• Services
• Storage
• Utilities

See our documentation for examples and patterns.

6. Test Your Plugin (Automated!)

# Windows
gradlew.bat runServer

# Linux/Mac
./gradlew runServer

This will:

1. Download the Hytale server (cached for future runs)
2. Build your plugin
3. Copy it to the server's mods folder
4. Start the server with interactive console

---

Project Structure

TemplatePlugin/
├── .github/workflows/
│   └── build.yml                    # CI/CD workflow
├── buildSrc/
│   ├── build.gradle.kts             # Custom plugin configuration
│   └── src/main/kotlin/
│       └── RunHytalePlugin.kt       # Automated server testing
├── src/main/
│   ├── java/com/example/templateplugin/
│   │   └── TemplatePlugin.java      # Minimal main class (example)
│   └── resources/
│       └── manifest.json            # Plugin metadata
├── .gitignore                       # Git ignore rules
├── build.gradle.kts                 # Build configuration
├── gradle.properties                # Project properties
├── settings.gradle.kts              # Project settings
├── LICENSE                          # MIT License
└── README.md                        # This file

Note: This is a minimal template. Create your own folder structure:

• commands/ - For command implementations
• listeners/ - For event listeners
• services/ - For business logic
• storage/ - For data persistence
• utils/ - For utility classes
• config/ - For configuration management

---

Development Workflow

Building

# Compile only
./gradlew compileJava

# Build plugin JAR
./gradlew shadowJar

# Clean and rebuild
./gradlew clean shadowJar

Testing

# Run server with your plugin
./gradlew runServer

# Run unit tests
./gradlew test

# Clean test server
rm -rf run/

Debugging

# Run server in debug mode
./gradlew runServer -Pdebug

# Then connect your IDE debugger to localhost:5005

---

Customization

Adding Dependencies

Edit build.gradle.kts:

dependencies {
    // Hytale API (provided by server)
    compileOnly(files("./HytaleServer.jar"))

    // Your dependencies (will be bundled)
    implementation("com.google.code.gson:gson:2.10.1")

    // Test dependencies
    testImplementation("org.junit.jupiter:junit-jupiter:5.10.0")
}

Configuring Server Testing

Run Hytale Server - A Gradle plugin to download and run a Hytale server for development and testing purposes. The server files will be located in the run/ directory of the project. Before starting the server it will compile (shadowJar task) and copy the plugin jar to the server's mods/ folder.

Usage:

Edit build.gradle.kts:

runHytale {
    jarUrl = "url to hytale server jar"
}

Run the server with:

# Windows
gradlew.bat runServer

# Linux/Mac
./gradlew runServer

Features:

• ✅ Automatic server JAR download and caching
• ✅ Compiles and deploys your plugin automatically
• ✅ Starts server with interactive console
• ✅ One-command workflow: ./gradlew runServer
• ✅ Server files in run/ directory (gitignored)

Implementing Your Plugin

Recommended folder structure:

src/main/java/com/yourname/yourplugin/
├── YourPlugin.java          # Main class
├── commands/                # Commands
├── listeners/               # Event listeners
├── services/                # Business logic
├── storage/                 # Data persistence
├── config/                  # Configuration
└── utils/                   # Utilities

See our documentation for examples:

• Getting Started with Plugins
• Advanced Plugin Patterns
• Common Plugin Features

---

CI/CD

This template includes a GitHub Actions workflow that:

1. ✅ Builds your plugin on every push
2. ✅ Runs tests
3. ✅ Uploads artifacts
4. ✅ Creates releases (when you tag)

Creating a Release

git tag v1.0.0
git push origin v1.0.0

GitHub Actions will automatically build and create a release with your plugin JAR.

---

Best Practices

✅ DO:

• Use the Service-Storage pattern for data management
• Write unit tests for your business logic
• Use structured logging (not System.out.println)
• Handle errors gracefully
• Document your public API
• Version your releases semantically (1.0.0, 1.1.0, etc.)

❌ DON'T:

• Hardcode configuration values
• Block the main thread with heavy operations
• Ignore exceptions
• Use deprecated APIs
• Commit sensitive data (API keys, passwords)

---

Troubleshooting

Build Fails

# Clean and rebuild
./gradlew clean build --refresh-dependencies

Server Won't Start

1. Check that jarUrl in build.gradle.kts is correct
2. Verify Java 25 is installed: java -version
3. Check logs in run/logs/

Plugin Not Loading

1. Verify manifest.json has correct Main class
2. Check server logs for errors
3. Ensure all dependencies are bundled in JAR

---

Documentation

For detailed guides on plugin development, see:

• Hytale Modding Documentation
• Getting Started with Plugins
• Advanced Plugin Patterns
• Common Plugin Features

---

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

---

License

This template is released under the MIT License. You are free to use it for any purpose.

---

Support

• Issues: GitHub Issues
• Documentation: Hytale Modding Docs
• Community: Join the Hytale modding community

---

Credits

Created by the Hytale modding community.

Based on best practices from production Hytale plugins.

---

Happy Modding! 🎮