tikaiz/hytale-solar-cell-plugin
1
0
Fork 0
Code Issues 1 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

Revamp README with improved setup and usage instructions

Browse Source 
The README has been rewritten for clarity and ease of use, providing step-by-step setup, authentication, development, and troubleshooting instructions. It now includes clearer prerequisites, quick start, asset bundling, build instructions, and links to full documentation, making it more accessible for new users.
This commit is contained in:
Britakee
2026-01-16 13:57:37 +01:00
parent 082aa83ba9
commit 7a3993766d
1 changed files with 85 additions and 83 deletions
Download Patch File Download Diff File Expand all files Collapse all files

168
README.md
View File

@@ -1,99 +1,101 @@
# Hytale Example Plugin
# 🛠️ Hytale Plugin Template
An example project that can build and run plugins for the game Hytale!
Welcome to the **Hytale Plugin Template**! This project is a pre-configured foundation for building **Java Plugins**. It streamlines the development process by handling classpath setup, server execution, and asset bundling.
> **⚠️ Warning: Early Access**
> The game Hytale is in early access, and so is this project! Features may be
> incomplete, unstable, or change frequently. Please be patient and understanding as development
> continues.
> **⚠️ Early Access Warning**
> Hytale is currently in Early Access. Features, APIs, and this template are subject to frequent changes. Please ensure you are using the latest version of the template for the best experience.
## Introduction
This project contains a Gradle project that can be imported into IDEA and used
as the foundation for custom Hytale plugins. The template will add the Hytale
server to your classpath and create a run configuration that can be used to
run your plugin on the server. It can also be used to build a sharable JAR file
that contains your plugin.
---
## Requirements
Please ensure all the requirements are met before getting started.
## 📋 Prerequisites
1. Download Hytale using the official launcher.
2. Have Intellij IDEA installed. Community edition is fine.
3. Download Java 25 and set it as the SDK in IDEA.
Before you begin, ensure your environment is ready:
## Configuring Template
It is important to configure the project before using it as a template. Doing
this before importing the project will help avoid running into caching issues
later on.
* **Hytale Launcher**: Installed and updated.
* **Java 25 SDK**: Required for modern Hytale development.
* **IntelliJ IDEA**: (Community or Ultimate) Recommended for full feature support.
### 1: Project Name
Set the name of the project in `settings.gradle`. This should be the name of
your plugin. We recommend capitalizing your project name and avoiding
whitespace and most special characters. This will be used as the base name for
any files produced by Gradle, like the sharable JAR file.
---
### 2: Gradle Properties
Review the properties defined in `gradle.properties`. You should change the
`maven_group` to match your project. You should also change the `version`
property before making a new release, or set up CI/CD to automate it.
## 🚀 Quick Start Installation
### 3: Manifest
The manifest file provides important information about your plugin to Hytale.
You should update every property in this file to reflect your project. The
most important property to set is `Main` which tells the game which class
file to load as the entry point for your plugin. The file can be found at
`src/main/resources/manifest.json`.
### 1. Initial Setup (Before Importing)
**This template has configured Gradle to automatically update the `Version` and
`IncludesAssetPack` property to reflect your Gradle properties every time you
run the game in development, or build the plugin. This is a workaround to allow
the in-game asset editor to be used when working on your project.**
To avoid IDE caching issues, configure these files **before** you open the project in IntelliJ:
## Importing into IDEA
When opening the project in IDEA it should automatically create the
`HytaleServer` run configuration and a `./run` folder. When you run the game it
will generate all the relevant files in there. It will also load the default
assets from the games.
* **`settings.gradle`**: Set your unique project name.
```gradle
rootProject.name = 'MyAwesomePlugin'
**If you do not see the `HytaleServer` run configuration, you may need to open
the dropdown in the top middle and select `HytaleServer` and press the green play button to start the server**
## Importing into VSCode
While VSCode is not officially supported, you can generate launch configs by
running `./gradlew generateVSCodeLaunch`.
## Connecting to Server
Once the server is running in IDEA you should be able to connect to
`Local Server` using your standard Hytale client. If the server does not show
up automatically, add the IP as `127.0.0.1` manually.
### You MUST authenticate your test server!
In order to connect to the test server, you must authenticate it with Hytale.
This is done by running the `auth login device` command in the server terminal.
This command will print a URL that you can use to authenticate the server using
your Hytale account. Once authenticated, you can run the
`auth persistence Encrypted` command to keep your server authenticated after
restarting it.
**Never share your encrypted auth file!**
If you are unable to run commands from the IDEA terminal, you can also run the
command from code like this. Make sure to remove the code after your server is
authenticated.
```java
@Override
protected void start() {
CommandManager.get().handleCommand(ConsoleSender.INSTANCE, "auth login device");
}
```
## Verifying The Example Plugin
You can verify the Example plugin has loaded by running the `/test` command
in game. It will print the name and version of your plugin. This is for
demonstration purposes, and should **NOT** be included in your final build.
* **`gradle.properties`**: Set your `maven_group` (e.g., `com.yourname`) and starting version.
* **`src/main/resources/manifest.json`**: Update your plugin metadata.
* **CRITICAL:** Ensure the `"Main"` property points exactly to your entry-point class.
The example plugin also includes a recipe defined by an asset pack. This recipe
allows you to craft 10 dirt into 1 dirt using the crafting window. This is also
an example and should not be removed before you release the plugin.
### 2. Importing the Project
1. Open IntelliJ IDEA and select **Open**.
2. Navigate to the template folder and click **OK**.
3. Wait for the Gradle sync to finish. This will automatically download dependencies, create a `./run` folder, and generate the **HytaleServer** run configuration.
### 3. Authenticating your Test Server
You **must** authenticate your local server to connect to it:
1. Launch the **HytaleServer** configuration in IDEA.
2. In the terminal, run: `auth login device`.
3. Follow the printed URL to log in via your Hytale account.
4. Once verified, run: `auth persistence Encrypted`.
---
## 🎮 Developing & Testing
### Running the Server
If you do not see the **HytaleServer** run configuration in the top-right dropdown, click "Edit Configurations..." to unhide it. Press the **Green Play Button** to start, or the **Bug Icon** to start in Debug Mode to enable breakpoints.
### 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**.
---
## 📦 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](https://britakee-studios.gitbook.io/hytale-modding-documentation)**
---
## 🆘 Troubleshooting
* **Sync Fails**: 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 `manifest.json` for typos in the `"Main"` class path.
---
**Need Help?** Visit our full guide here: **[Hytale Modding Documentation](https://britakee-studios.gitbook.io/hytale-modding-documentation)**