247 lines
5.2 KiB
Markdown
247 lines
5.2 KiB
Markdown
---
|
|
title: Building and Running
|
|
type: docs
|
|
weight: 2
|
|
---
|
|
|
|
This guide covers how to set up your development environment, build your plugin, and deploy it to a Hytale server.
|
|
|
|
## Quick Start with example-mod
|
|
|
|
The easiest way to start plugin development is using the [example-mod](https://github.com/hytale-france/example-mod) template which includes an automated setup script.
|
|
|
|
### 1. Clone the Repository
|
|
|
|
```bash
|
|
git clone https://github.com/hytale-france/example-mod.git
|
|
cd example-mod
|
|
```
|
|
|
|
Or download the latest release from [GitHub Releases](https://github.com/hytale-france/example-mod/releases).
|
|
|
|
### 2. Download Tools (Once)
|
|
|
|
Download the required tools (hytale-downloader and CFR decompiler):
|
|
|
|
```bash
|
|
./setup.sh --download
|
|
```
|
|
|
|
This creates a `.bin/` directory with:
|
|
- `hytale-downloader-*` - Official Hytale server downloader
|
|
- `cfr-0.152.jar` - Java decompiler for reference sources
|
|
|
|
### 3. Download the Server
|
|
|
|
Download and extract the Hytale server:
|
|
|
|
```bash
|
|
./setup.sh --setup
|
|
```
|
|
|
|
The server will be available in `server/Server/HytaleServer.jar`.
|
|
|
|
### 4. Generate Reference Sources (Optional)
|
|
|
|
Decompile the server JAR to get API reference sources:
|
|
|
|
```bash
|
|
./setup.sh --decompile
|
|
```
|
|
|
|
This creates `src-ref/` with decompiled Java sources for IDE autocompletion and documentation.
|
|
|
|
## Project Structure
|
|
|
|
After setup, your project will look like this:
|
|
|
|
```
|
|
example-mod/
|
|
├── app/
|
|
│ ├── src/main/java/org/example/
|
|
│ │ └── ExamplePlugin.java
|
|
│ ├── src/main/resources/
|
|
│ │ └── manifest.json
|
|
│ └── build.gradle.kts
|
|
├── server/
|
|
│ ├── Server/
|
|
│ │ └── HytaleServer.jar
|
|
│ └── Assets.zip
|
|
├── src-ref/ # Decompiled reference sources
|
|
├── .bin/ # Downloaded tools
|
|
├── setup.sh # Setup automation script
|
|
├── build.gradle.kts
|
|
├── settings.gradle.kts
|
|
└── gradlew
|
|
```
|
|
|
|
## Building the Plugin
|
|
|
|
### 1. Build with Gradle
|
|
|
|
```bash
|
|
# On Linux/macOS
|
|
./gradlew build
|
|
|
|
# On Windows
|
|
gradlew.bat build
|
|
```
|
|
|
|
### 2. Locate the Built JAR
|
|
|
|
After a successful build, your plugin JAR will be in:
|
|
|
|
```
|
|
app/build/libs/ExamplePlugin-1.0.0.jar
|
|
```
|
|
|
|
## Running the Server
|
|
|
|
### 1. Initial Server Setup
|
|
|
|
Start the server for the first time:
|
|
|
|
```bash
|
|
cd server
|
|
java -jar Server/HytaleServer.jar --assets Assets.zip
|
|
```
|
|
|
|
### 2. Authenticate
|
|
|
|
Once the server console is ready, run the authentication command:
|
|
|
|
```
|
|
/auth login device
|
|
```
|
|
|
|
Follow the instructions to authenticate with your Hytale account.
|
|
|
|
{{< callout type="warning" >}}
|
|
**Authentication Required:** If no server tokens are configured, you will see a warning at startup:
|
|
```
|
|
No server tokens configured. Use /auth login to authenticate.
|
|
```
|
|
You must authenticate before players can join the server in non-singleplayer mode.
|
|
{{< /callout >}}
|
|
|
|
### 3. Stop the Server
|
|
|
|
After authentication, you can stop the server:
|
|
|
|
- **Linux/macOS:** Press `Ctrl+C`
|
|
- **Windows:** Press `Ctrl+C` or close the terminal
|
|
|
|
## Deploying Your Plugin
|
|
|
|
### 1. Copy the JAR
|
|
|
|
Copy the built JAR to the `mods` folder:
|
|
|
|
```bash
|
|
cp app/build/libs/ExamplePlugin-1.0.0.jar server/mods/
|
|
```
|
|
|
|
### 2. Start the Server
|
|
|
|
```bash
|
|
cd server
|
|
java -jar Server/HytaleServer.jar --assets Assets.zip
|
|
```
|
|
|
|
### 3. Verify Loading
|
|
|
|
You should see your plugin loading in the console:
|
|
|
|
```
|
|
[INFO] [PluginManager] Loading pending plugins from directory: mods
|
|
[INFO] [PluginManager] - org.example:ExamplePlugin from path ExamplePlugin-1.0.0.jar
|
|
```
|
|
|
|
## Updating the Server
|
|
|
|
When a new Hytale version is released:
|
|
|
|
```bash
|
|
./setup.sh --update
|
|
```
|
|
|
|
This will download the latest server version and update your installation.
|
|
|
|
## Common Issues
|
|
|
|
### Java Version Mismatch
|
|
|
|
{{< callout type="error" >}}
|
|
**Error:** `Unsupported class file major version 69`
|
|
{{< /callout >}}
|
|
|
|
Ensure you're using Java 25:
|
|
|
|
```bash
|
|
java --version
|
|
```
|
|
|
|
### Manifest Not Found
|
|
|
|
{{< callout type="error" >}}
|
|
**Error:** `Failed to load manifest file!`
|
|
{{< /callout >}}
|
|
|
|
Make sure `manifest.json` is in `src/main/resources/` and included in the JAR.
|
|
|
|
### Setup Script Not Found
|
|
|
|
{{< callout type="error" >}}
|
|
**Error:** `./setup.sh: Permission denied`
|
|
{{< /callout >}}
|
|
|
|
Make the script executable:
|
|
|
|
```bash
|
|
chmod +x setup.sh
|
|
```
|
|
|
|
## Manual Setup (Alternative)
|
|
|
|
If you prefer manual setup without the script:
|
|
|
|
### Locating Hytale Installation
|
|
|
|
Find your Hytale installation directory:
|
|
|
|
{{< tabs items="Windows,Linux,macOS" >}}
|
|
{{< tab >}}
|
|
```
|
|
%appdata%\Hytale\install\release\package\game\latest
|
|
```
|
|
{{< /tab >}}
|
|
{{< tab >}}
|
|
```
|
|
$XDG_DATA_HOME/Hytale/install/release/package/game/latest
|
|
```
|
|
Or typically:
|
|
```
|
|
~/.local/share/Hytale/install/release/package/game/latest
|
|
```
|
|
{{< /tab >}}
|
|
{{< tab >}}
|
|
```
|
|
~/Application Support/Hytale/install/release/package/game/latest
|
|
```
|
|
{{< /tab >}}
|
|
{{< /tabs >}}
|
|
|
|
### Manual Server Setup
|
|
|
|
1. Copy `Server/` and `Assets.zip` from your Hytale installation
|
|
2. Download CFR from [https://www.benf.org/other/cfr/](https://www.benf.org/other/cfr/)
|
|
3. Decompile: `java -jar cfr.jar HytaleServer.jar --outputdir src-ref`
|
|
|
|
## Next Steps
|
|
|
|
Now that you can build and run your plugin, explore:
|
|
|
|
- [Plugin Lifecycle](../plugin-lifecycle) - Understand setup, start, and shutdown
|
|
- [Commands](../../commands) - Create custom commands
|
|
- [Events](../../events) - Listen to game events
|