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

Migrate to new Hytale plugin template structure

Browse Source 
Replaces the previous Kotlin-based Gradle build and template files with a new Java-based Gradle build system and updated example plugin code. Removes old build scripts, plugin template, and configuration, and introduces a new ExamplePlugin with updated manifest, command, and recipe example. Updates documentation and project configuration to match the new structure and usage.
This commit is contained in:
Britakee
2026-01-16 07:24:15 +01:00
parent 4f7cabf1d1
commit 41dd40e48b
20 changed files with 367 additions and 786 deletions
Download Patch File Download Diff File Expand all files Collapse all files

442
README.md
View File

@@ -1,371 +1,99 @@
# Hytale Plugin Template
# Hytale Example Plugin
A minimal, ready-to-use template for creating Hytale plugins with modern build tools and automated testing.
An example project that can build and run plugins for the game Hytale!
> **✨ Builds immediately without any changes!** Clone and run `./gradlew shadowJar` to get a working plugin JAR.
> **⚠️ 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.
## Features
## 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.
✅ **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
## Requirements
Please ensure all the requirements are met before getting started.
---
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.
## Quick Start
## 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.
### Prerequisites
### 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.
- **Java 25 JDK** - [Download here](https://www.oracle.com/java/technologies/downloads/)
- **IntelliJ IDEA** - [Download here](https://www.jetbrains.com/idea/download/) (Community Edition is fine)
- **Git** - [Download here](https://git-scm.com/)
### 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.
### 1. Clone or Download
### 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`.
```bash
git clone https://github.com/yourusername/hytale-plugin-template.git
cd hytale-plugin-template
**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.**
## 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.
**If you do not see the `HytaleServer` run configuration, you may need to open
the dropdown or click `Edit Configurations...` once to unhide it.**
## 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");
}
```
**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!)
## 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.
The template works out-of-the-box:
```bash
# 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`:**
```kotlin
rootProject.name = "your-plugin-name"
```
**`gradle.properties`:**
```properties
pluginGroup=com.yourname
pluginVersion=1.0.0
pluginDescription=Your plugin description
```
**`src/main/resources/manifest.json`:**
```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
```bash
# 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](../Documentation/) for examples and patterns.
### 6. Test Your Plugin (Automated!)
```bash
# 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 plugins 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
```bash
# Compile only
./gradlew compileJava
# Build plugin JAR
./gradlew shadowJar
# Clean and rebuild
./gradlew clean shadowJar
```
### Testing
```bash
# Run server with your plugin
./gradlew runServer
# Run unit tests
./gradlew test
# Clean test server
rm -rf run/
```
### Debugging
```bash
# Run server in debug mode
./gradlew runServer -Pdebug
# Then connect your IDE debugger to localhost:5005
```
---
## Customization
### Adding Dependencies
Edit `build.gradle.kts`:
```kotlin
dependencies {
// Hytale API (provided by server)
compileOnly(files("libs/hytale-server.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 `plugins/` folder.
**Usage:**
Edit `build.gradle.kts`:
```kotlin
runHytale {
jarUrl = "url to hytale server jar"
}
```
Run the server with:
```bash
# 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](../Documentation/07-getting-started-with-plugins.md)
- [Advanced Plugin Patterns](../Documentation/12-advanced-plugin-patterns.md)
- [Common Plugin Features](../Documentation/14-common-plugin-features.md)
---
## 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
```bash
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
```bash
# 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](https://github.com/yourusername/hytale-modding/tree/main/Documentation)
- [Getting Started with Plugins](../Documentation/07-getting-started-with-plugins.md)
- [Advanced Plugin Patterns](../Documentation/12-advanced-plugin-patterns.md)
- [Common Plugin Features](../Documentation/14-common-plugin-features.md)
---
## 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](https://github.com/yourusername/hytale-plugin-template/issues)
- **Documentation:** [Hytale Modding Docs](https://github.com/yourusername/hytale-modding)
- **Community:** Join the Hytale modding community
---
## Credits
Created by the Hytale modding community.
Based on best practices from production Hytale plugins.
---
**Happy Modding! 🎮**
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.