Init

2026-01-20 20:33:59 +01:00
commit b16a40e431
583 changed files with 87339 additions and 0 deletions
--- a/content/getting-started/building-and-running.en.md
+++ b/content/getting-started/building-and-running.en.md
@@ -0,0 +1,246 @@
+---
+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