Hytale-F2P/README.md

<div align="center">

<header>
  <h1>🎮 Hytale F2P Launcher 🚀</h1>
  <h2>💻 Cross-Platform Multiplayer 🖥️</h2>
  <h3>Available for Windows 🪟, macOS 🍎, and Linux 🐧</h3>
  <p><small>An unofficial cross-platform launcher for Hytale with automatic updates and multiplayer support!</small></p>
</header>

![GitHub Downloads](https://img.shields.io/github/downloads/amiayweb/Hytale-F2P/total?style=for-the-badge)
![Version](https://img.shields.io/badge/Version-2.1.1-green?style=for-the-badge)
![Platform](https://img.shields.io/badge/Platform-Windows%20%7C%20macOS%20%7C%20Linux-orange?style=for-the-badge)
![License](https://img.shields.io/badge/License-Educational-blue?style=for-the-badge)

[![GitHub stars](https://img.shields.io/github/stars/amiayweb/Hytale-F2P?style=social)](https://github.com/amiayweb/Hytale-F2P/stargazers)
[![GitHub forks](https://img.shields.io/github/forks/amiayweb/Hytale-F2P?style=social)](https://github.com/amiayweb/Hytale-F2P/network/members)

⭐ **If you find this project useful, please give it a STAR!** ⭐

### ⚠️ **READ [QUICK START](README.md#-quick-start) before Downloading & Installing the Launcher!** ⚠️

#### 🛑 **Found a problem? Join the Discord and Select #Open-A-Ticket!: https://discord.gg/gME8rUy3MB** 🛑

<p>
  👍 If you like the project, <b>feel free to support us via Buy Me a Coffee!</b> ☕<br>
  Any support is appreciated and helps keep the project going.
</p>

<a href="https://buymeacoffee.com/hf2p">
  <img src="https://media3.giphy.com/media/v1.Y2lkPTc5MGI3NjExem14OW1tanN3eHlyYmR4NW1sYmJkOTZmbmJxejdjZXB6MXY5cW12MSZlcD12MV9pbnRlcm5hbF9naWZfYnlfaWQmY3Q9cw/TDQOtnWgsBx99cNoyH/giphy.gif" width="120">
</a>

</div>

---
## 📸 Screenshots

<div align="center">
  <img src="https://i.imgur.com/xW9do3d.png" alt="Hytale F2P Launcher" width="1000">
  <details>
    <summary><b>View Gallery</b></summary>
    <table style="width: 100%; border-spacing: 15px; border-collapse: separate;">
      <tr>
        <td align="center" style="vertical-align: top; width: 50%;">
          <b>Mods Preview</b><br>
          <img src="https://i.imgur.com/f8qyIJy.png" alt="Hytale F2P Mods" width="100%">
        </td>
        <td align="center" style="vertical-align: top; width: 50%;">
          <b>Latest News</b><br>
          <img src="https://i.imgur.com/qu0HltD.png" alt="Hytale F2P News" width="100%">
        </td>
      </tr>
      <tr>
        <td align="center" style="vertical-align: top; width: 50%;">
          <b>Social & Chat</b><br>
          <img src="https://i.imgur.com/t3GmbfF.png" alt="Hytale F2P Chat" width="100%">
        </td>
        <td align="center" style="vertical-align: top; width: 50%;">
          <b>Settings</b><br>
          <img src="https://i.imgur.com/uUD7lDB.png" alt="Hytale F2P Settings" width="100%">
        </td>
      </tr>
      <tr>
        <td align="center" style="vertical-align: top; width: 50%;">
          <b>In-Game Screenshot - Spawn Point</b><br>
          <img src="https://i.imgur.com/X8lNFQ7.png" alt="Hytale F2P In-Game Screenshot-1" width="100%">
        </td>
        <td align="center" style="vertical-align: top; width: 50%;">
          <b>In-Game Screenshot - Gameplay Terrain</b><br>
          <img src="https://i.imgur.com/3iRScPa.png" alt="Hytale F2P In-Game Screenshot-2" width="100%">
        </td>
      </tr>
    </table>
  </details>
</div>

---
## ✨ Features

🎯 **Core Features**
- 🔄 **Automatic Updates** - Smart version checking and seamless game updates
- 💾 **Data Preservation** - Intelligent UserData backup and restoration during updates
- 🌐 **Cross-Platform** - Full support for Windows, Linux (X11/Wayland), and macOS
- ☕ **Java Management** - Automatic Java runtime detection and installation
- 🎮 **Multiplayer Support** - Automatic multiplayer client installation (Windows, macOS & Linux !)

🛡️ **Advanced Features**
- 📁 **Custom Installation** - Choose your own installation directory
- 🔍 **Smart Detection** - Automatic game and dependency detection
- 🗂️ **Mod Support** - Built-in mod management system
- 💬 **Player Chat** - Integrated chat system for community interaction
- 📰 **News Feed** - Stay updated with the latest Hytale news
- 🎨 **Modern UI** - Clean, responsive interface with dark theme

---

# 🚀 Quick Start

## 🖥️ System Requirements

### 🎮 Hytale Hardware Requirements

> [!IMPORTANT]
> Hytale is designed to be accessible while scaling for high-end performance. 
> Below are the [official system requirements for the Early Access](https://hytale.com/news/2025/12/hytale-hardware-requirements) release.

<div align="center">

<table>
  <thead>
    <tr>
      <th>Component</th>
      <th>🥉 Minimum (1080p @ 30 FPS)</th>
      <th>🥈 Recommended (1080p @ 60 FPS)</th>
      <th>🥇 Best (1440p @ 60 FPS)</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><b>🖥️ OS</b></td>
      <td colspan="3" align="center">
        Windows 10/11 (64-bit X64) | Linux (x64) | macOS (ARM64/Apple Silicon)
        <br />
        <small><i>⚠️ Note: ARM64 (Windows & Linux), macOS (x86/Intel) <b>are not supported!</b> ⚠️</i></small>
      </td>
    </tr>
    <tr>
      <td><b>⚙️ CPU</b></td>
      <td>Intel i5-7500 / Ryzen 3 1200 / Apple M1</td>
      <td>Intel i5-10400 / Ryzen 5 3600 / Apple M2</td>
      <td>Intel i7-10700K / Ryzen 9 3800X / Apple M3</td>
    </tr>
    <tr>
      <td><b>🧠 RAM</b></td>
      <td>8GB (dGPU) / 12GB (iGPU)<sup><a href="#fn1" id="ref1">1</a></sup></td>
      <td>16 GB</td>
      <td>32 GB</td>
    </tr>
    <tr>
      <td><b>🎮 GPU</b></td>
      <td>GTX 900 / RX 400 / UHD 620</td>
      <td>GTX 1060 / RX 580 / Iris Xe</td>
      <td>RTX 30 Series / RX 7000 Series</td>
    </tr>
    <tr>
      <td><b>💾 Storage</b></td>
      <td>20 GB (SATA SSD)</td>
      <td>20 GB (NVMe SSD)</td>
      <td>50 GB+ (NVMe SSD)</td>
    </tr>
    <tr>
      <td><b>🌐 Network</b></td>
      <td>2 Mbit/s</td>
      <td>8 Mbit/s</td>
      <td>10+ Mbit/s</td>
    </tr>
  </tbody>
</table>
</div>
<p id="fn1"><sup>Note 1</sup> Using Discrete/Dedicated GPU (dGPU) must have 8 GB RAM minimum, while using Integrated GPU (iGPU) must have 12 GB RAM.</p>

> [!WARNING]
> Our launcher has **not yet** supported Offline Mode (playing Hytale without internet).
> We will surely add the feature as soon as possible. Kindly wait for the update.

---

### 🪟 Windows Prequisites
* **Java JDK 25:**
  * [Oracle](https://www.oracle.com/java/technologies/downloads/#jdk25-windows)
  * [Adoptium](https://adoptium.net/temurin/releases/?version=25)
  * [Microsoft](https://learn.microsoft.com/en-us/java/openjdk/download), has Windows ARM64 support in version 25.
* **Latest Visual Studio Redist:** 
  * Download via [Microsoft Visual C++ Redistributable](https://aka.ms/vc14/vc_redist.x64.exe)
  * Or [All-in-One by Techpowerup](https://www.techpowerup.com/download/visual-c-redistributable-runtime-package-all-in-one/)

### 🐧 Linux Prequisites

* Make sure you have already installed newest **GPU driver** especially proprietary NVIDIA, consult your distro docs or wiki.
  * Also make sure that your GPU can be connected to EGL, try checking it first (again, consult your distro docs or wiki) before installing Hytale game via our launcher.
* Install `libpng` package to avoid `SDL3_Image` error:
  * `libpng16-16 libpng-dev` for Ubuntu/Debian-based Distro
  * `libpng libpng-devel` for Fedora/RHEL-based Distro
  * `libpng` for Arch-based Distro

---

## 📥 Installation

### 🪟 Windows Installation

1. **Prerequisites:** Ensure you have installed all [**Windows Prerequisites**](https://github.com/amiayweb/Hytale-F2P/tree/main?tab=readme-ov-file#-windows-prequisites) listed above.
2. **Download:** Get the latest `Hytale-F2P-Launcher.exe` from the [**Releases**](https://github.com/amiayweb/Hytale-F2P/releases/latest/) page.
3. **SmartScreen Note:** Since the executable is currently unsigned, Windows may show a "Windows protected your PC" popup.
    * Click **More info**, then click **Run anyway**.
4. **Launch:** Once installed, you can launch the app directly from your Desktop or the Start menu.
5. **Whitelist in Windows Firewall** [#192](https://github.com/amiayweb/Hytale-F2P/issues/192#issuecomment-3803042908)
    * Open the Windows Start Menu and search for `Allow an app through Windows Firewall`
    * Click "Change settings" (you may need Admin privileges) and Locate `HytaleClient.exe` in the list.
    * Ensure both the Private and Public checkboxes are checked. Click OK to save.

### 🐧 Linux Installation

1. **Prerequisites:** Ensure you have installed all [**Linux Prerequisites**](https://github.com/amiayweb/Hytale-F2P/tree/main?tab=readme-ov-file#-linux-prequisites) above.
2. **Download:** Choose the package that fits your distribution from the [**Releases**](https://github.com/amiayweb/Hytale-F2P/releases/latest/) page:
   * **Universal:** `.AppImage`
   * **Arch Linux:** `.pkg.tar.zst`
   * **Fedora/RHEL/openSUSE:** `.rpm`
   * **Debian/Ubuntu:** `.deb`
3. **Permissions & Execution:**
   * **AppImage:** Make the file executable and run it:
     ```bash
     chmod +x hytale-f2p-launcher.AppImage
     ./hytale-f2p-launcher.AppImage
     ```
   * **Ubuntu/Debian-based or Fedora/RHEL-based:** Install the DEB/RPM:
     ```bash
     # Fedora/RHEL-based
     sudo dnf install hytale-f2p-launcher.rpm
     # Debian/Ubuntu
     sudo apt install -y libasound2 libpng16-16 libpng-dev libicu76
     sudo dpkg -i hytale-f2p-launcher.deb
     ```
   * **Arch Linux (pacman):** Install the package using:
     ```bash
     # Stable Build
     sudo pacman -U hytale-f2p-launcher.pkg.tar.zst
     # Development Build
     yay -S hytale-f2p-git # or
     paru -S hytale-f2p-git
     # Manual Build
     git clone https://aur.archlinux.org/hytale-f2p-git.git
     cd hytale-f2p-git
     makepkg -si
     ```

> [!NOTE]
> Make sure to adjust the filename correctly with the version and the architecture type. TIP: Use `cd` command to the package location.

4. **Troubleshooting:**
   * **FUSE:** If the AppImage fails to launch on newer distributions, ensure `libfuse2` (or `fuse2` on Arch/Fedora) is installed.
   * **Desktop Entry:** After installing via `.rpm`, `.deb`, or `.pkg.tar.zst`, the launcher should automatically appear in your App Library/Grid.
   * Missing libxcrypt.so.1: Install `libxcrypt-compat` using your package manager

### 🍎 macOS Installation  

> [!NOTE]
> Apple Silicon Users: If you are on an M1, M2, or M3 Mac, you may be prompted to install Rosetta 2 the first time you run the launcher. This is normal and required for compatibility.

1. **Download:** Get the latest `.dmg` file from the [**Releases**](https://github.com/amiayweb/Hytale-F2P/releases/latest/) page.
2. **Mount:** Double-click the `.dmg` file to open it.
3. **Install:** Drag the **Hytale F2P Launcher** icon into your **Applications** folder.
4. **First Run:** If macOS prevents the app from opening because it is from an "unidentified developer":
    * Open **System Settings** > **Privacy & Security**.
    * Scroll down to the **Security** section.
    * Look for the message regarding "Hytale F2P Launcher" and click **Open Anyway**.
    * Authenticate with your password and click **Open**.

#### **Advanced: Manual Installation (.zip)**
The `.zip` version is useful for users who prefer a portable installation or need to bypass specific permission issues.

1. **Extract:** Download and unzip the file to your desired location (e.g., `~/Applications`).
2. **Remove Quarantine:** macOS often "quarantines" apps downloaded via browser. If the app won't open, open **Terminal** and run:
   ```bash
   xattr -rd com.apple.quarantine /path/to/Hytale-F2P-Launcher.app
   ```
> [!TIP]
> Type the first part of the command, then drag the app icon into the Terminal window to auto-fill the path.

--- 

# 📢 How to Host a Server

## 🌐 Host your Singleplayer Server (Online-Play Feature)

> [!NOTE]
> You have to play the game to host the server. See Dedicated Server section below if you want to host it without you playing as the host.

1. Open your Singleplayer World
2. Pause the game (Esc) > select Online Play > Turn on `Allow Other Players to Join` > Set password if needed > Press `Save`.
3. Check the status `Connected via STUN` or `Connected via UPnP`.

## 🖧 Host a Dedicated Server

> [!NOTE]
> If you already have the patched `HytaleServer.jar` in `HytaleF2P/{release/pre-release}/package/game/latest/Server`, you can use it to host local dedicated server. 

> [!TIP]
> Use services like Playit.gg, Tailscale, Radmin VPN to share UDP connection if setting up router as an admin is not possible.

> [!WARNING]
> `Hytale-F2P-Server.rar` file is needed to set up a server on non-playing hardware (such as VPS/server hosting). Linux ARM64 is supported for server only.

> [!IMPORTANT]
> See detailed information of setting up a server here: [SERVER.md](SERVER.md). Download the latest patched JAR, the patched RAR, or the SH/BAT scripts from channel `#open-public-server` in our Discord Server. 

---

## 🔧 Troubleshooting

See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for detailed Troubleshooting guide.

---

## 🔨 Building from Source

See [BUILD.md](docs/BUILD.md) for comprehensive build instructions.

---

## 📋 Changelog

### 🆕 v2.1.1
- 🛠️ **Fix Bug EPERM**: EPERM or Error Permission in creating/removing process in reinstalling is now fixed.
- 🅰️ **Adds .pkg.tar.zst Build for Arch Users**: This Arch-package has been needed since the first release.  
- ❎ **Removes .pacman Build for Arch**: Based on the established conventions within the Arch Linux community, the file extension .pacman should not be used for package files.
- 🌎 **New Translation**: New Polish 🇵🇱 Translation added to the Launcher. 

<details>
<summary>Click here to see older Changelogs</summary>

### 🔄 v2.1.0
- 🚨 **Auto-Retry Downloads and Auto-Patch Files** — 
- ⚡ **Hardware Acceleration** — 
- 🔎 **Browse CurseForge Mods** — Browsing mods now easier with our dedicated CurseForge API Key.
- 🌎 **Fixes and Release New Translation** — Fixed 🇪🇸 🇧🇷 and added more translation for current build. Turkish 🇹🇷 language now added.

### 🔄 v2.0.2b *(Minor Update: Performance & Utilities)*  
- 🌎 **Language Translation** — A big welcome for Spanish 🇪🇸 and Portuguese (Brazil) 🇧🇷 players! **Language setting can be found in the bottom part of Settings pane.**
- 💻 **Laptop/Hybrid GPU Performance Issue Fix** — Added automatic GPU detection system and options to choose which GPU will be used for the game, *specifically for Linux users*.
- 👨‍💻 **In-App Logging** — Reporting bugs and issues to `Github Issues` tab or `Open A Ticket` channel in our Discord Server has been made easier for players, no more finding logs file manually.
- 🛠️ **Repair Button** — Your game's broken? One button will fix them, go to Settings pane to Repair your game in one-click, **without losing any data**. If doing so did not fix your issue, please report it to us immediately!
- 🐛 **Fixed Bugs** — Fixed issue [#84](https://github.com/amiayweb/Hytale-F2P/issues/84) where mods disappearing when game starts in previous launcher (v2.0.2a).


### 🔄 v2.0.2a *(Minor Update)*  
- 🧑‍🚀 **Profiles System** — Added proper profile management: create, switch, and delete profiles. Each profile now has its own **isolated mod list**.  
- 🔒 **Mod Isolation** — Fixed ModManager so mods are **strictly scoped to the active profile**. Browsing and installing now only affects the selected profile.  
- 🚨 **Critical Path Fix** — Resolved a macOS bug where mods were being saved to a Windows path (`~/AppData/Local`) instead of `~/Library/Application Support`.
- 🛡️ **Stability Improvements** — Added an **auto-sync step before every launch** to ensure the physical mods folder always matches the active profile.  
- 🎨 **UI Enhancements** — Added a **profile selector dropdown** and a **profile management modal**.
  
### 🔄 v2.0.2 
- 🎮 **Discord RPC Integration** - Added Discord Rich Presence with toggle in settings (enabled by default)
- 🌐 **Cross-Platform Multiplayer** - Added multiplayer patch support for Windows, Linux, and macOS
- 🎨 **Chat Improvements** - Simplified chat color system
- 🏆 **Badge System Expansion** - Added new FOUNDER UUID to the badge system
- 🔧 **Progress Bar Fix** - Resolved issue where download progress bar stayed active after game launch
- 🐛 **Bug Fixes**: General fixes

### 🔄 v2.0.1
- 📊 **Advanced Logging System** - Complete logging with timestamps, file rotation, and session tracking
- 🔧 **Play Button Fix** - Resolved issue where play button could get stuck in "CHECKING..." state  
- 💬 **Discord Integration** - Added closable Discord notification for community engagement
- 📁 **Game Location Access** - New "Open Game Location" button in settings for easy file access
- 🎯 **UI Polish** - Removed bounce animation from player counter for smoother experience
- 🛡️ **Stability Improvements** - Enhanced error handling and process lifecycle management
- ⚡ **Performance Optimizations** - Faster startup times and better resource management
- 🔄 **Timeout Protection** - Added safety timeouts to prevent launcher freezing

### 🔄 v2.0.0
- ✅ **Automatic Game Update System** - Smart version checking and seamless updates
- ✅ **Partial Automatic Launcher Update System** - This will inform you when I release a new update.
- 🛡️ **UserData Preservation** - Intelligent backup/restore of game saves during updates
- 🐧 **Enhanced Linux Support** - Full Wayland and X11 compatibility  
- 🔄 **Multiplayer Auto-Install** - Automatic multiplayer client setup on updates (Windows)
- 📡 **API Integration** - Real-time version checking and client management
- 🎨 **UI Improvements** - Added contributor credits footer
- 🔄 **Complete Launcher Overhaul** - Total redesign of the launcher architecture and interface
- 🗂️ **Integrated Mod Manager** - Built-in mod installation, management
- 💬 **Community Chat System** - Real-time chat for launcher users to connect and communicate

### 🔧 v1.0.1
- 📁 **Custom Installation** - Choose installation directory with file browser
- 🏠 **Always on Top** - Launcher stays visible during installation
- 🧠 **Smart Detection** - Automatic game detection and UI adaptation  
- 🗑️ **Uninstall Feature** - Easy game removal with one click
- 🔄 **Dynamic UI** - "INSTALL" vs "PLAY" button based on game state
- 🛠️ **Path Management** - Proper custom directory handling
- 💫 **UI Polish** - Improved layout and overflow prevention

### 🎉 v1.0.0 *(Initial Release)*
- 🎮 **Offline Gameplay** - Play Hytale without internet connection
- ⚡ **Auto Installation** - One-click game setup
- ☕ **Java Management** - Automatic Java runtime handling
- 🎨 **Modern Interface** - Clean, intuitive design
- 🌟 **First Release** - Core launcher functionality
</details>
---

## 👥 Contributors

<div align="center">

**Made with ❤️ by the community**

[![Contributors](https://contrib.rocks/image?repo=amiayweb/Hytale-F2P)](https://github.com/amiayweb/Hytale-F2P/graphs/contributors)

</div>

### 🏆 Project Creator
- [**@amiayweb**](https://github.com/amiayweb) - *Lead Developer & Project Creator | Windows*
- [**@Relyz1993**](https://github.com/Relyz1993) - *Server Helper & Second Developer & Project Creator*

### 🌟 Contributors  
- [**@sanasol**](https://github.com/sanasol) - *Main Issues fixer | Multiplayer Patcher*
- [**@Terromur**](https://github.com/Terromur) - *Main Issues fixer | Beta tester*
- [**@fazrigading**](https://github.com/fazrigading) - *Main Issues fixer | Beta tester*
- [**@ericiskoolbeans**](https://github.com/ericiskoolbeans) - *Beta Tester*
- [**@chasem-dev**](https://github.com/chasem-dev) - *Issues fixer*
- [**@crimera**](https://github.com/crimera) - *Issues fixer*  
- [**@Citeli-py**](https://github.com/Citeli-py) - *Issues fixer*
- [**@Rahul-Sahani04**](https://github.com/Rahul-Sahani04) - *Issues fixer*
- [**@xSamiVS**](https://github.com/xSamiVS) - *Language Translator*
- [**@BlackSystemCoder**](https://github.com/BlackSystemCoder) - *Language Translator*

---

## 📊 GitHub Stats

<div align="center">

![GitHub stars](https://img.shields.io/github/stars/amiayweb/Hytale-F2P?style=for-the-badge&logo=github)
![GitHub forks](https://img.shields.io/github/forks/amiayweb/Hytale-F2P?style=for-the-badge&logo=github)
![GitHub issues](https://img.shields.io/github/issues/amiayweb/Hytale-F2P?style=for-the-badge&logo=github)
![GitHub downloads](https://img.shields.io/github/downloads/amiayweb/Hytale-F2P/total?style=for-the-badge&logo=github)

</div>


## 📞 Support

<div align="center">

**Need help?** Join us: https://discord.gg/gME8rUy3MB

</div>

---

## ⚖️ Legal Disclaimer

<div align="center">

⚠️ **Important Notice** ⚠️

</div>

This launcher is created for **educational purposes only**.

🏛️ **Not Official** - This is an independent fan project **not affiliated with, endorsed by, or associated with** Hypixel Studios or Hytale.

🛡️ **No Warranty** - This software is provided **"as is"** without any warranty of any kind.

📝 **Responsibility** - The authors take no responsibility for how this software is used.

🛑 **Takedown Policy** - If Hypixel Studios or Hytale requests removal, this project will be taken down immediately.

❤️ **Support Official** - Please support the official game by **purchasing** it legally when available.

---

<div align="center">

**⭐ Star this project if you found it helpful! ⭐**

*Made with ❤️ by [@amiayweb](https://github.com/amiayweb) and the legendary contributors with amazing community*

[![Star History Chart](https://api.star-history.com/svg?repos=amiayweb/Hytale-F2P&type=date&legend=top-left)](https://www.star-history.com/#amiayweb/Hytale-F2P&type=date&legend=top-left)
</div>