The most reliable way to make a first Hytale server plugin is to use the maintained HytaleModding Java/Kotlin template, run it with Java 25, and test it against a local server. The template’s Gradle tasks prepare the development files and launch a server; your finished JAR is then copied to Hytale’s Mods directory. Java is the first-party route because Hytale publishes a Java server API reference. If you already work in web tooling, HytaleJS offers a separate JavaScript/TypeScript bridge, but it has different build and deployment steps.
Playing with friends? Godlike.Host runs hosted Hytale servers from 10 data-center locations, with free DDoS protection.
What a Hytale server plugin is
A server plugin is code loaded by the dedicated Hytale server to add commands, react to events, or implement gameplay systems. It runs on the server rather than inside a player’s client, so a plugin can enforce rules, maintain server-side data, announce player activity, or expose administrative commands without requiring every player to install a matching client mod.
As an Amazon Associate I earn from qualifying purchases.
Recommended Free Tools
Hytale’s official documentation currently labels release 0.7.2 as current (Hypixel Studios, 2026). Treat that label and the Java API reference as the compatibility baseline. API names, manifest requirements, and startup behavior can change between releases, so check the documentation again before changing a dependency or upgrading a production server.
Choose your development route
| Route | Language and tooling | Build result | Where it is deployed | Best fit |
|---|---|---|---|---|
| Official-aligned template | Java or Kotlin with Gradle | Plugin JAR | Hytale server Mods directory | Beginners who want the closest match to Hytale’s published Java API, strong IDE support, and conventional JVM debugging |
| HytaleJS | JavaScript or TypeScript with Node.js, TypeScript, and esbuild | Compiled dist/plugin.js |
hytale-server/mods/bmstefanski_HytaleJS/scripts/ |
Developers already comfortable with web tooling who accept a third-party bridge between scripts and the server API |
The two routes are not interchangeable. A Java build produces a JAR for the normal plugin loader; HytaleJS produces a script that the HytaleJS bridge loads after a restart. Choose one route for a project rather than copying a JAR into the scripts directory or a JavaScript file into the regular Mods directory.
Requirements before you create a project
| Requirement | What the documented setup requires | Why it matters |
|---|---|---|
| Java runtime | Java 25 for the Hytale server and the Java/Kotlin template | The Gradle build and local server must use the same supported Java generation. Verify that your terminal and IDE both select Java 25. |
| Operating system and CPU | x64 or arm64 device | These are the architectures identified by the official server manual. |
| Memory | At least 4 GB RAM | Hypixel Studios states that a Hytale server can run with at least 4 GB. A real development server may need more as player count, entities, view distance, and world loading increase. |
| Build tools | Gradle wrapper supplied by the template; Git or an archive copy of the template | Using the wrapper keeps task execution tied to the project’s expected Gradle configuration. |
| IDE | An IDE with Java or Kotlin support; the template and CurseForge guide recommend IntelliJ IDEA | Code navigation, Gradle integration, and debugger support are especially useful when API signatures change. |
| For HytaleJS | Node.js 18 or newer, @hytalejs.com/core, TypeScript, and esbuild |
These packages compile the script before it is copied into the HytaleJS scripts directory. |
Do not size a production machine from the 4 GB figure alone. It is a documented minimum, not a guarantee for a particular world or player population. Start with a small test world, watch memory use while loading chunks and entities, and increase the allocation when your workload requires it.
Set up the Java or Kotlin template
1. Install and verify Java 25
Install a Java 25 JDK, not only a browser plug-in or an older runtime. Open a new terminal and run:
Free tools Windows power users keep installed
One-click scans. No signup required.
java -versionThe reported major version must be 25. In your IDE, select the same JDK for the project and for Gradle. If the terminal reports 25 but the IDE uses another version, Gradle tasks can fail before your plugin code is compiled.
2. Copy the maintained template
Start with the maintained HytaleModding/plugin-template. It is described as a ready-to-use starting point for Hytale server plugins written in Java or Kotlin. Download or copy the repository, place it in a new project directory, and open that directory in your IDE. Keep the Gradle wrapper and the repository’s existing build files; they provide the tasks used by the Hytale development setup.
3. Set project identity in gradle.properties
Before writing gameplay code, edit gradle.properties and replace the template’s project metadata with your own values. Keep the identifiers consistent with the manifest you will create. Use a stable mod ID rather than changing it between local builds, because server logs and saved configuration often refer to that ID.
The exact property names come from the current template. Do not delete unknown properties merely because they look unused: some are consumed by Gradle tasks or manifest generation. If a new template revision changes a property, follow that revision rather than copying settings from an older tutorial.
4. Prepare the development environment
From the project root, run the wrapper task:
./gradlew setupHytaleDevOn Windows, use the wrapper form supplied with the project (for example, the Windows batch wrapper) if your shell does not execute ./gradlew. The setup task retrieves or prepares the Hytale development files expected by the template. Let it finish before attempting to run the server; a failed setup usually means the project is not ready to resolve the server API.
Rank #2
5. Start a local server
Launch the development server with:
./gradlew runServerThe first run can take longer while Gradle resolves dependencies and creates the server layout. Read the console output instead of assuming a silent process has started. The official server manual documents device authentication; a local development server may ask you to complete that flow before it can start or access the required assets.
Keep the server console visible during development. It is where you will see plugin discovery, manifest errors, class-loading failures, command registration problems, and event exceptions. Stop the server cleanly before rebuilding or replacing a loaded plugin.
Understand the project layout
| Path or file | Purpose | What belongs there |
|---|---|---|
src/main/java |
Java source root | Your plugin classes, command implementations, event handlers, and gameplay systems. |
src/main/resources |
Runtime resources | manifest.json and any other files your plugin must read at runtime. |
gradle.properties |
Project metadata and Gradle properties | The project identity values consumed by the template’s build configuration. |
| Gradle build files | Repositories, dependencies, plugins, and tasks | The configuration that resolves the Hytale API and creates the JAR. |
| Settings files | Gradle project identity and included configuration | The project name and settings expected by the template. |
Keep Java packages aligned with their directory path. A class declared in a package that does not match its location can compile inconsistently across IDEs and command-line builds. Put non-code files under resources so Gradle includes them in the resulting artifact.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Write the manifest before adding features
The manifest tells the server what your plugin is and which class starts it. The template’s manifest format includes these fields:
- Mod ID
- Main class
- Version
- Author
- Description
- URL
- Dependencies
- Server-version metadata
Create or edit src/main/resources/manifest.json using the exact field names and nesting shown by the current template. The main-class value must match the fully qualified class that implements the plugin entry point. Keep the mod ID unique on the server, use a deliberate version such as an initial development version, and declare dependencies only when the plugin actually requires them.
Server-version metadata is not decorative. It gives you a place to state which Hytale server release the artifact targets and helps you notice an unsafe update. When Hytale moves beyond 0.7.2, review this metadata and the API reference together instead of changing only the version string.
Make a first feature: command or event handler
Start with a small observable behavior
A first plugin should do one thing that is easy to prove in the console or in-game. A custom command is a good first milestone because it has a clear input and output. An event handler is equally useful when you want to learn the server lifecycle: player connection and chat are natural first events.
Use the Java API reference for the current 0.7.2 interfaces and registration method. The template is intended for custom commands, event handling, and broader gameplay systems, but API names can change; copying a class signature from an older example is a common cause of compile errors.
Implement the entry point
- Open the Java source directory and create the package and entry-point class named in your manifest.
- Use the lifecycle method required by the current Java API to obtain the server/plugin context.
- Register exactly one test command or one event listener during startup.
- Give the command a distinctive response, or make the listener log a connection/chat event, so you can distinguish your code from normal server output.
- Keep shutdown handling simple at first: unregister listeners or release resources if the API requires it.
Do not add several systems before the first one works. A single command that registers, executes, and logs correctly isolates manifest, classpath, and permission problems. After that, add argument parsing, permissions, persistent data, or gameplay state one piece at a time.
Test the feature locally
- Stop the running server cleanly.
- Build the project, or let the development task rebuild it according to the template instructions.
- Start the local server again with
./gradlew runServer. - Watch for the plugin’s load message and any stack trace.
- Join the local server and execute the command, or trigger the event you registered.
- Confirm both the expected player-facing result and the server log entry.
If the server starts but the feature does not respond, first confirm that the artifact actually contains the updated class and manifest. Then check the exact command spelling, registration timing, permissions, and the server console for an exception.
Build and deploy the Java plugin
Build a release artifact
From the template root, run:
./gradlew buildGradle places the resulting plugin JAR in the project’s build output. The exact subdirectory is determined by the template and Gradle version; use the newly modified JAR rather than an older file with a similar name. If the build fails, fix compilation or manifest errors before copying anything to a server.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Install it on a Windows server
CurseForge’s plugin guide identifies the local Windows Mods directory as:
%appdata%/Hytale/UserData/Mods- Stop the Hytale server.
- Copy the built JAR into the Mods directory.
- Remove or archive older copies of the same plugin so two versions cannot load together.
- Start the server and read the plugin-loading messages.
- Test the command or event before inviting players.
The path above is for Windows. Other operating systems use the equivalent Hytale user-data location described by the server manual; do not assume that a Windows environment variable exists elsewhere.
Server authentication, assets, and file layout
The official server manual documents device authentication and the --assets launch argument. Authentication is an operational prerequisite, not a plugin feature: complete it with the account and device flow requested by the server, and store credentials or tokens according to your server’s security practices.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minutePC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Rank #4
Keep the required server files in the layout expected by the current manual. If the server cannot find assets, verify that the launch command points to the correct assets location and that the --assets argument is spelled exactly as documented. A plugin cannot load successfully if the server itself stops during asset discovery or authentication.
For production, stage updates rather than replacing a live JAR while the process is running. Build and test the new version on a separate instance, stop the production server, back up its world and configuration, replace the plugin, start the server, and inspect the complete startup log before reconnecting players. Keep the previous JAR available so you can roll back if the new API behavior causes errors.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.The HytaleJS JavaScript and TypeScript route
When it makes sense
HytaleJS is useful if you already know Node.js, TypeScript, and JavaScript build tools. Its maintainers document a /players command and examples for player-connect and chat events. This route is a third-party bridge, not the official Java API path, so its compatibility depends on the bridge and its maintained packages as well as on Hytale itself.
Install and build
- Install Node.js 18 or newer.
- Create or copy the HytaleJS project and install its documented dependencies, including
@hytalejs.com/core, TypeScript, and esbuild. - Implement a small command or event based on the current HytaleJS examples. Start with the documented
/playerscommand or a player-connect log so the result is easy to verify. - Run the project’s build script:
npm run buildThe build produces dist/plugin.js. Copy that file to:
hytale-server/mods/bmstefanski_HytaleJS/scripts/Restart the server to load the new script. HytaleJS scripts are loaded on restart, so editing the source file while the server is running does not by itself update the active plugin. Read the startup output for script compilation or bridge errors, then run the command or trigger the event in-game.
Java/Kotlin versus HytaleJS: a practical decision
| Decision factor | Java/Kotlin template | HytaleJS |
|---|---|---|
| Language familiarity | Best if you know Java or Kotlin, or want conventional JVM development. | Best if you are comfortable with JavaScript or TypeScript and npm scripts. |
| API position | Closest to Hytale’s published Java server API reference. | Third-party bridge documented by its maintainers. |
| Build tooling | Gradle wrapper and the template’s development tasks. | Node.js, TypeScript, esbuild, and npm run build. |
| IDE and debugging | JVM type checking, Gradle integration, and mature Java/Kotlin debugging. | JavaScript/TypeScript editor tooling and Node-oriented debugging; bridge boundaries add another failure point. |
| Deployment target | Compiled plugin JAR in the server’s Mods directory. | dist/plugin.js in the HytaleJS scripts directory. |
| Version maintenance | Follow Hytale’s Java API and update Gradle/template metadata when the server changes. | Track Hytale changes and HytaleJS bridge releases; a break can occur in either layer. |
For a first production plugin, prefer Java or Kotlin unless your team’s strongest skills are in TypeScript and the bridge supports the server version you intend to run. The Java route reduces the number of translation layers you must troubleshoot.
Common failures and recovery steps
Gradle says the Java version is unsupported
Run java -version in the same shell that launches Gradle, then inspect the IDE’s Gradle JDK setting. Install or select Java 25 in both places. Restart the IDE after changing the JDK so it does not retain a stale daemon.
Best Value
setupHytaleDev cannot prepare the project
Check network access, the project’s repository configuration, and the exact template revision. Do not mix build files from different template versions. Delete only generated development output after consulting the template instructions; preserve your source, manifest, and Gradle configuration.
The server starts but does not load the plugin
Check that the JAR is in the correct Mods directory, that only one copy exists, and that manifest.json is under src/main/resources in the project before building. Confirm that the manifest’s main class is fully qualified and that the JAR you copied has a newer build timestamp.
The plugin loads but the command is missing
Look for registration exceptions, a command-name mismatch, and permission requirements. Test with the smallest command implementation first. If you copied an example, compare every API type and registration call with the current 0.7.2 Java reference.
HytaleJS changes do not appear
Run npm run build again, verify that dist/plugin.js changed, copy that exact file into the HytaleJS scripts path, and restart the server. Editing TypeScript without rebuilding leaves the old JavaScript file in place.
The server fails before plugins are mentioned
Resolve authentication, asset, and launch-layout problems first. Confirm the required files and the --assets argument described by the official manual. Plugin debugging cannot begin until the server reaches its plugin-loading phase.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →A safe beginner workflow
- Install Java 25 and verify the version in both terminal and IDE.
- Copy the current HytaleModding/plugin-template and edit its project metadata.
- Run
./gradlew setupHytaleDev. - Launch with
./gradlew runServerand complete any requested device authentication. - Create one command or one event handler using the current Java API reference.
- Build with
./gradlew buildand test the generated JAR locally. - Copy the tested JAR to the appropriate Mods directory only after stopping the server.
- Record the plugin version and target server release in your project and manifest metadata.
- For production updates, test on a separate instance, back up data, stage the replacement, and keep the previous build for rollback.
This sequence keeps environment, API, packaging, and deployment problems separate. It also gives you a repeatable checklist when Hytale releases a new server version.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
