Updated for hytale-tools

2026-06-03 12:09:19 -04:00
parent fcba26deff
commit 4b4a990bae
10 changed files with 304 additions and 465 deletions
--- a/README.md
+++ b/README.md
@@ -4,52 +4,158 @@ A ready-to-use starting point for creating Hytale server plugins with Java, _or
 been using the Asset Editor and want to start writing server-side logic — custom commands, event
 handling, gameplay systems — this is the simplest place to begin.

-## How to start?
+This template uses the [Hytale Gradle Plugin](https://github.com/AzureDoom/Hytale-Gradle-Plugin),
+a Gradle plugin maintained by AzureDoom for Hytale mod/plugin development. It handles the repetitive
+project setup work for you, including manifest generation, validation, local server runs, IDE source
+setup, and optional hosted Hytale Javadoc injection.

-1. Copy the template by downloading it or using the "Use this template" button.
-2. [Configure or Install the Java SDK](https://hytalemodding.dev/en/docs/guides/plugin/setting-up-env)
-   to use the latest 25 from JetBrains or similar.
-3. Open the project in your favorite IDE, we
-   recommend [IntelliJ IDEA](https://www.jetbrains.com/idea/download).
-4. Optionally, run `./gradlew` if your IDE does not automtically synchronizes.
-5. Run the devserver with the Run Configuration created, or `./gradlew devServer`.
+## How to start

-> On Windows, use `.\gradlew.bat` instead of `./gradlew`, this script is here to run the
-> Gradle without you needing to install the tooling itself, only the Java is required.
+1. Copy the template by downloading it or using the **Use this template** button.
+2. [Configure or install the Java SDK](https://hytalemodding.dev/en/docs/guides/plugin/setting-up-env)
+   to use Java 25. JetBrains Runtime is recommended for the best hot-reload/debugging experience.
+3. Open the project in your favorite IDE. We recommend
+   [IntelliJ IDEA](https://www.jetbrains.com/idea/download).
+4. Update the project values in `gradle.properties`:
+    - `rootProject.name` in `settings.gradle.kts`
+    - `group`
+    - `manifest_group`
+    - `mod_name`
+    - `mod_id`
+    - `main_class`
+    - `mod_author`
+    - `mod_description`
+    - `mod_url`
+5. Optionally run `./gradlew` if your IDE does not automatically sync the project.
+6. Prepare the Hytale development environment:

-With that you will be prompted in the output to authorize your server, and then you can start
-developing your plugin while the server is live reloading the code changes.
+   ```bash
+   ./gradlew setupHytaleDev
+   ```

-From here,
-the [HytaleModding guides](https://hytalemodding.dev/en/docs/guides/plugin/build-and-test) cover
-more details!
+7. Run the local development server:

-## Scaffoldit Plugin
+   ```bash
+   ./gradlew runServer
+   ```

-While there are multiple plugins made for Hytale, the template currently uses a zero-boilerplate one
-where you only need the absolute minimum to start. However, you do have access to everything as
-normal if you know what you are doing.
+> On Windows, use `./gradlew.bat` or `gradlew.bat` instead of `./gradlew`. The Gradle wrapper is
+> included so you do not need to install Gradle separately; only Java is required.

-For in-depth configuration, you can visit the [ScaffoldIt Plugin Docs](https://scaffoldit.dev).
+When the server starts, the output may prompt you to authorize your Hytale server. After that, you
+can begin developing your plugin while the server handles local development runs.
+
+From here, the [HytaleModding guides](https://hytalemodding.dev/en/docs/guides/plugin/build-and-test)
+cover more details.
+
+## Hytale Gradle Plugin
+
+This template is built around AzureDoom's `com.azuredoom.hytale-tools` Gradle plugin.
+
+The plugin is configured in `build.gradle.kts`:
+
+```kotlin
+plugins {
+    idea
+    java
+    id("com.azuredoom.hytale-tools") version "1.+"
+}
+```
+
+The AzureDoom Maven repository is configured in `settings.gradle.kts`:
+
+```kotlin
+pluginManagement {
+    repositories {
+        gradlePluginPortal()
+        mavenCentral()
+        maven {
+            name = "AzureDoom Maven"
+            url = uri("https://maven.azuredoom.com/mods")
+        }
+    }
+}
+```
+
+Most plugin-specific settings are controlled from `gradle.properties` and passed into the
+`hytaleTools` block in `build.gradle.kts`. This keeps common project metadata in one easy-to-edit
+place.
+
+For full plugin documentation, configuration options, tasks, and multi-project setup, visit the
+[Hytale Gradle Plugin repository](https://github.com/AzureDoom/Hytale-Gradle-Plugin).
+
+## Useful commands
+
+```bash
+# Sync/setup the local Hytale development environment
+./gradlew setupHytaleDev
+
+# Run the local Hytale server
+./gradlew runServer
+
+# Run the server with debugging and hot swap enabled
+./gradlew runServer -Ddebug=true -Dhotswap=true
+
+# Check your JVM and hot swap setup
+./gradlew hytaleJvmDoctor
+
+# Build the plugin
+./gradlew build
+
+# Refresh dependencies if something fails to resolve
+./gradlew build --refresh-dependencies
+```
+
+## Project structure
+
+```text
+src/main/java/        Plugin source code
+src/main/resources/   Plugin resources, including manifest.json
+gradle.properties     Main template configuration
+build.gradle.kts      Gradle build and Hytale Gradle Plugin configuration
+settings.gradle.kts   Plugin repositories and project name
+```
+
+## Manifest configuration
+
+The generated `manifest.json` is driven by the values in `gradle.properties`, including:
+
+- `manifest_group`
+- `mod_id`
+- `version`
+- `mod_description`
+- `mod_author`
+- `mod_url`
+- `main_class`
+- `manifest_dependencies`
+- `manifest_opt_dependencies`
+- `manifestServerVersion`
+
+After changing these values, run:
+
+```bash
+./gradlew updatePluginManifest
+```

 ## Troubleshooting

- **Gradle sync fails in IntelliJ** –
-  _Check that Java 25 is installed and configured under File → Project Structure → SDKs._
- **Build fails with missing dependencies** –
-  _Run `./gradlew build --refresh-dependencies`. Make sure you have internet access!_
- **Permission denied on `./gradlew`** –
-  _Run `chmod +x gradlew` (macOS/Linux)._
- **Hot-reload doesn't work** –
-  _Verify you're using JetBrains Runtime, not a regular JDK._
+- **Gradle sync fails in IntelliJ** — Check that Java 25 is installed and configured under
+  **File → Project Structure → SDKs**.
+- **The Hytale Gradle Plugin does not resolve** — Make sure `settings.gradle.kts` includes the
+  AzureDoom Maven repository at `https://maven.azuredoom.com/mods`.
+- **Build fails with missing dependencies** — Run `./gradlew build --refresh-dependencies` and make
+  sure you have internet access.
+- **Permission denied on `./gradlew`** — Run `chmod +x gradlew` on macOS/Linux.
+- **Hot reload or enhanced class redefinition does not work** — Use JetBrains Runtime and try
+  `./gradlew hytaleJvmDoctor` to verify your JVM setup.

 ## Resources

+- [Hytale Gradle Plugin](https://github.com/AzureDoom/Hytale-Gradle-Plugin)
 - [Hytale Modding Guides](https://hytalemodding.dev)
 - [Hytale Modding Discord](https://discord.gg/hytalemodding)
- [ScaffoldIt Plugin Docs](https://scaffoldit.dev)

 ## License

-Add your own after copying the template, though we recommend using MIT, BSD, or Apache to keep
-the modding community open!
+Add your own license after copying the template. We recommend MIT, BSD, or Apache to keep the
+modding community open.