shironeko/Hytale-F2P
1
0
Fork 0
mirror of https://github.com/amiayweb/Hytale-F2P.git synced 2026-02-26 10:41:56 -03:00
Code Issues Packages Projects Releases Wiki Activity

Release Build v2.2.0 (#236)

Browse Source 
* fix: resolve cross-platform EPERM permissions errors

modManager.js:
- Switch from hardcoded 'junction' to dynamic symlink type based on OS (fixing Linux EPERM).
- Add retry logic for directory removal to handle file locking race conditions.
- Improve broken symlink detection during profile sync.

gameManager.js:
- Implement retry loop (3 attempts) for game directory removal in updateGameFiles to prevent EBUSY/EPERM errors on Windows.

paths.js:
- Prevent fs.mkdirSync failure in getModsPath by pre-checking for broken symbolic links.

* fix: missing pacman builds

* prepare release for 2.1.1

minor fix for EPERM error permission

* prepare release 2.1.1

minor fix EPERM permission error

* prepare release 2.1.1

* Update README.md Windows Prequisites for ARM64 builds

* fix: remove broken symlink after detected

* fix: add pathexists for paths.js to check symlink

* fix: isbrokenlink should be true to remove the symlink

* add arch package .pkg.tar.zst for release

* fix: release workflow for build-arch and build-linux

* build-arch job now only build arch .pkg.tar.zst package instead of the whole generic linux.
* build-linux job now exclude .pacman package since its deprecated and should not be used.

* fix: removes pacman build as it replaced by tar.zst and adds build:arch shortcut for pkgbuild

* aur: add proper VCS (-git) PKGBUILD

created clean VCS-based PKGBUILD following arch packaging conventions.

this explicitly marked as a rolling (-git) build and derives its version dynamically from git tags and commit history via pkgver(). previous hybrid approach has been changed.

key changes:
- use -git suffix to clearly indicate rolling source builds
- set pkgver=0 and compute the actual version via pkgver()
- build only a directory layout using electron-builder (--dir)
- avoid generating AppImage, deb, rpm, or pacman installers
- align build and package steps with Arch packaging guidelines

note: this PKGBUILD is intended for development and AUR use only and is not suitable for binary redistribution or release artifacts.

* ci: add fixed-version PKGBUILD for Arch Linux releases

this PKGBUILD intended for CI and GitHub release artifacts. targets tagged releases only and uses a fixed pkgver that matches the corresponding git tag. all of the VCS logic has been removed to PKGBUILD-git to ensure reproducible builds and stable versioning suitable for binary distribution.

the build process relies on electron-builder directory output (--dir) and packages only the unpacked application into a standard Arch Linux package (.pkg.tar.zst). other distro format are excluded from this path and handled separately.

this change establishes a clear separation between:
- rolling AUR development builds (-git)
- CI-generated, versioned Arch Linux release packages

the result is predictable artifact naming, correct version alignment, and Arch-compliant packaging for downstream users.

* Update README.md

adds information for Arch build

* Update README.md

BUILD.md location was changed and now this link is poiting to nothing

* Update PKGBUILD

* Update PKGBUILD-git

* chore: fix ubuntu/debian part in README.md

* Polish language support (#195)

* Update support_request.yml

Added hardware specification

* Update bug_report.yml

Add logs textfield to bug report

* chore: add changelog in README.md

* fix screenshot input in feature_request.yml

* add hardware spec input in bug_report.yml

* fix: PKGBUILD pkgname variable fix

* userdata migration [need review from other OS]

* french translate

* Add German and Swedish translations

Added de.json and sv.json locale files for German and Swedish language support. Updated i18n.js to register 'de' and 'sv' as available languages in the launcher.

* Update README.md

* chore: add offline-mode warning to the README.md

* chore: add downloads counter in README.md

* fix: Steam Deck/Ubuntu crash - use system libzstd.so

The bundled libzstd.so is incompatible with glibc 2.41's stricter heap
validation, causing "free(): invalid pointer" crashes.

Solution: Automatically replace bundled libzstd.so with system version
on Linux. The launcher detects and symlinks to /usr/lib/libzstd.so.1.

- Auto-detect system libzstd at common paths (Arch, Debian, Fedora)
- Backup bundled version as libzstd.so.bundled
- Create symlink to system version
- Add HYTALE_NO_LIBZSTD_FIX=1 to disable if needed

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* chore: remove Windows and Linux ARM64 information on the README.md

* Update support_request.yml

* fix: improve update system UX and macOS compatibility

Update System Improvements:
- Fix duplicate update popups by disabling legacy updater.js
- Add skip button to update popup (shows after 30s, on error, or after download)
- Add macOS-specific handling with manual download as primary option
- Add missing open-download-page IPC handler
- Add missing unblockInterface() method to properly clean up after popup close
- Add quitAndInstallUpdate alias in preload for compatibility
- Remove pulse animation when download completes
- Fix manual download button to show correct status and close popup
- Sync player name to settings input after first install

Client Patcher Cleanup:
- Remove server patching code (server uses pre-patched JAR from CDN)
- Simplify to client-only patching
- Remove unused imports (crypto, AdmZip, execSync, spawn, javaManager)
- Remove unused methods (stringToUtf8, findAndReplaceDomainUtf8)
- Move localhost dev code to backup file for reference

Code Quality Fixes:
- Fix duplicate DOMContentLoaded handlers in install.js
- Fix duplicate checkForUpdates definition in preload.js
- Fix redundant if/else in onProgressUpdate callback
- Fix typo "Harwadre" -> "Hardware" in preload.js

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* Add Russian language support

Added Russian (ru) to the list of available languages.

* chore: drafting documentation on SERVER.md

* Some updates in Russian language localization file

* fix

* Update ru.json

* Fixed Java runtime name and fixed typo

* fixed untranslated place

* Update ru.json

* Update ru.json

* Update ru.json

* Update ru.json

* Update ru.json

* fix: timeout getLatestClient 

fixes #138

* fix: change default version to 7.pwr in main.js

* fix: change default release version to 7.pwr

* fix: change version release to 7.pwr

* docs: Add comprehensive troubleshooting guide (#209)

Add TROUBLESHOOTING.md with solutions for common issues including:

- Windows: Firewall configuration, duplicate mods, SmartScreen
- Linux: GPU detection (NVIDIA/AMD), SDL3_image/libpng dependencies,
  Wayland/X11 issues, Steam Deck support
- macOS: Rosetta 2 for Apple Silicon, code signing, quarantine
- Connection: Server boot failures, regional restrictions
- Authentication: Token errors, config reset procedures
- Avatar/Cosmetics: F2P limitations documentation
- Backup locations for all platforms
- Log locations for bug reports

Solutions compiled from closed GitHub issues (#205, #155, #90, #60,
#144, #192) and community feedback.

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

* Standardize language codes, improve formatting, and update all locale files. (#224)

* Update German (Germany) localization

* Update Español (España) localization

* Update French (France) localization

* Update Polish (Poland) localization

* Update Portuguese (Brazil) localization

* Update Russian (Russia) localization

* Update Swedish (Sweden) localization

* Update Turkish (Turkey) localization

* Update language codes, names and alphabetical in i18n system

* Changed Spanish language name to the Formal name "Spanish (Spain)"

* Fix PKGBUILD-git

* Fix PKGBUILD

* delete cache after installation

* Enforce 16-char player name limit and update mod sync

Added a maxlength attribute to the player name input and enforced a 16-character limit in both install and settings scripts, providing user feedback if exceeded. Refactored modManager.js to replace symlink-based mod management with a copy-based system, copying enabled mods to HytaleSaves\Mods and removing legacy symlink logic to improve compatibility and avoid permission issues.

* Update installation subtitle

* chore: update quickstart link in README.md

* chore: delete warning of Ubuntu-Debian at Linux Prequisites section

* added featured server list from api

* Add Featured Servers page to GUI

* Update Discord invite URL in client patcher

* Add differential update system

* Remove launcher chat and add Discord popup

* fix: removed 'check disk space' alert on permission file error

* fix: upgrade tar to ^7.5.6 version

* fix: re-add universal arch for mac

* fix: upgrade electron/rebuild to 4.0.3

* fix: removed override tar version

* fix: pkgbuild version to 2.1.2

* fix: src.tar.zst and srcinfo missing files

* feat: add Indonesian language translation

* fix: GPU preference hint to Laptop-only

* feat: create two columns for settings page

* Add Discord invite link to rpc

* docs: add recordings form, fix OS list

* Release v2.2.0

* Release v2.2.0

* Release v2.2.0

* chore: delete icon.ico, moved to build folder

* chore: delete icon.png, moved to build folder

* fix: build and release for tag push-only in release.yml

* fix: gamescope steam deck issue fixes #186 hopefully

* Support branch selection for server patching

* chose: add auto-patch system for pre-release JAR

---------

Co-authored-by: TalesAmaral <57869141+TalesAmaral@users.noreply.github.com>
Co-authored-by: walti0 <95646872+walti0@users.noreply.github.com>
Co-authored-by: AMIAY <letudiantenrap.collab@gmail.com>
Co-authored-by: sanasol <mail@sanasol.ws>
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Co-authored-by: Terromur <79866197+Terromur@users.noreply.github.com>
Co-authored-by: Zakhar Smokotov <zaharb840@gmail.com>
Co-authored-by: xSamiVS <samtaiebc@gmail.com>
This commit is contained in:
Fazri Gading
2026-01-31 06:19:46 +08:00
committed by GitHub
parent da186333cb
commit d5cc0868e9
50 changed files with 5934 additions and 3631 deletions
Download Patch File Download Diff File Expand all files Collapse all files

460
TROUBLESHOOTING.md Normal file
View File

@@ -0,0 +1,460 @@
# Hytale F2P Launcher - Troubleshooting Guide
This guide covers common issues and their solutions. If your issue isn't listed here, please check [existing issues](https://github.com/amiayweb/Hytale-F2P/issues) or join our [Discord](https://discord.gg/gME8rUy3MB).
---
## Table of Contents
- [Windows Issues](#windows-issues)
- [Linux Issues](#linux-issues)
- [macOS Issues](#macos-issues)
- [Connection & Server Issues](#connection--server-issues)
- [Authentication & Token Issues](#authentication--token-issues)
- [Avatar & Cosmetics Issues](#avatar--cosmetics-issues)
- [General Issues](#general-issues)
- [Known Limitations](#known-limitations)
---
## Windows Issues
### "Failed to connect to server" / Server won't boot
**Symptoms:** Singleplayer world fails to load, "Server failed to boot" error.
**Solution - Whitelist in Windows Firewall:**
1. Open **Windows Settings** > **Privacy & Security** > **Windows Security**
2. Click **Firewall & network protection** > **Allow an app through firewall**
3. Click **Change settings**
4. Find `HytaleClient.exe` and check both **Private** and **Public**
5. If not listed, click **Allow another app** and browse to:
```
%localappdata%\HytaleF2P\release\package\game\latest\Client\HytaleClient.exe
```
### Duplicate mod error
**Symptoms:** `java.lang.IllegalArgumentException: Tried to load duplicate plugin`
**Solution:**
1. Navigate to your mods folder:
```
%localappdata%\HytaleF2P\release\package\game\latest\Client\UserData\Mods
```
2. Remove any duplicate `.jar` files
3. Restart the launcher
### SmartScreen blocks the launcher
**Solution:**
1. Click **More info**
2. Click **Run anyway**
---
## Linux Issues
### GPU not detected / Using software rendering (llvmpipe)
**Symptoms:**
- Game uses integrated GPU instead of dedicated GPU
- Very low FPS / unplayable performance
- Play button not clickable
- Log shows `llvmpipe` instead of your GPU
**Solution for NVIDIA:**
```bash
__EGL_VENDOR_LIBRARY_FILENAMES=/usr/share/glvnd/egl_vendor.d/10_nvidia.json ./HytaleF2P.AppImage
```
**Solution for AMD (hybrid GPU systems):**
```bash
DRI_PRIME=1 ./HytaleF2P.AppImage
```
**Permanent fix - Create a launcher script:**
```bash
#!/bin/bash
export __EGL_VENDOR_LIBRARY_FILENAMES=/usr/share/glvnd/egl_vendor.d/10_nvidia.json
export DRI_PRIME=1
./HytaleF2P.AppImage
```
**Note:** On some desktop systems with AMD iGPU + dGPU, the GPU selector may be inverted (selecting iGPU actually uses dGPU). Use whichever option works.
### SDL3_image / libpng errors
**Symptoms:**
- `DllNotFoundException: Unable to load shared library 'SDL3_image'`
- `libpng` related errors
- Game crashes on startup
**Solution - Install dependencies:**
**Fedora / RHEL:**
```bash
sudo dnf install libpng libpng-devel
```
**Debian / Ubuntu:**
```bash
sudo apt install libpng16-16 libpng-dev libgdiplus libc6-dev
```
**Arch Linux:**
```bash
sudo pacman -S libpng
```
**Alternative - Replace corrupted library:**
```bash
cd ~/.hytalef2p/release/package/game/latest/Client/
mv libSDL3_image.so libSDL3_image.so.bak
wget https://github.com/user-attachments/files/24710966/libSDL3_image.zip
unzip libSDL3_image.zip
chmod 644 libSDL3_image.so
rm libSDL3_image.zip
```
### AppImage won't launch / FUSE error
**Solution:**
```bash
# Debian/Ubuntu
sudo apt install libfuse2
# Fedora
sudo dnf install fuse
# Arch
sudo pacman -S fuse2
```
### Missing libxcrypt.so.1
**Solution:**
```bash
# Fedora/RHEL
sudo dnf install libxcrypt-compat
# Arch
sudo pacman -S libxcrypt-compat
```
### Wayland display issues
**Symptoms:** Game doesn't launch, stuck at loading, or display glitches on Wayland.
**Solution - Force X11:**
```bash
GDK_BACKEND=x11 ./HytaleF2P.AppImage
```
**Alternative - Electron Wayland hint:**
```bash
ELECTRON_OZONE_PLATFORM_HINT=auto ./HytaleF2P.AppImage
```
### Steam Deck / Gamescope issues
**Solution 1 - Add custom launch options in Steam:**
```
ELECTRON_OZONE_PLATFORM_HINT=x11 %command%
```
**Solution 2 - Launch from Desktop Mode** instead of Game Mode.
**Solution 3 - Force X11:**
```bash
GDK_BACKEND=x11 ./HytaleF2P.AppImage
```
### Ubuntu LTS-based distros (Linux Mint, Zorin OS, Pop!_OS)
These distributions may have compatibility issues due to older system packages. This is a limitation of the Hytale game client, not the launcher.
**Workarounds:**
1. Install all dependencies listed above
2. Try the SDL3_image replacement
3. Consider using a more recent distribution or Flatpak/AppImage with bundled dependencies
---
## macOS Issues
### "Butler system error -86" (Apple Silicon)
**Symptoms:** `Butler execution failed: spawn Unknown system error -86` (EXC_BAD_CPU_TYPE)
**Cause:** Butler (the update tool) is x86_64 only.
**Solution - Install Rosetta 2:**
```bash
softwareupdate --install-rosetta
```
Then restart the launcher.
### Auto-update fails with code signature error
**Symptoms:**
```
Code signature at URL did not pass validation
domain: 'SQRLCodeSignatureErrorDomain'
```
**Solution - Manual update:**
1. Download the latest version manually from [Releases](https://github.com/amiayweb/Hytale-F2P/releases/latest)
2. Backup your data first (see [Backup Locations](#backup-locations))
3. Install the fresh download
### "Unidentified developer" warning
**Solution:**
1. Open **System Settings** > **Privacy & Security**
2. Scroll to **Security** section
3. Find the message about "Hytale F2P Launcher"
4. Click **Open Anyway**
5. Authenticate and click **Open**
### App won't open (quarantine)
**Solution:**
```bash
xattr -rd com.apple.quarantine /Applications/Hytale-F2P-Launcher.app
```
---
## Connection & Server Issues
### "Failed to connect to server" in Singleplayer
**Possible causes:**
1. Windows Firewall blocking (see [Windows section](#failed-to-connect-to-server--server-wont-boot))
2. Patched server JAR download failed
3. Regional network restrictions
**Solution - Check patched JAR:**
1. Look for `HytaleServer.jar` in:
- Windows: `%localappdata%\HytaleF2P\release\package\game\latest\Server\`
- Linux: `~/.hytalef2p/release/package/game/latest/Server/`
- macOS: `~/Library/Application Support/HytaleF2P/release/package/game/latest/Server/`
2. If missing or very small, the download may have failed
**Solution - Regional restrictions:**
Some countries (Russia, Turkey, Indonesia, etc.) may have issues accessing download servers.
- Try using a VPN for the initial download
- Once downloaded, the patched JAR is cached locally
### "Infinite Booting Server" / Server stuck loading
**Solution:**
1. Check if the patched JAR downloaded successfully (see above)
2. Ensure your GPU meets minimum requirements
3. Check launcher logs for specific errors
4. Try with a VPN if in a restricted region
### "Connection timed out from inactivity"
**This is expected behavior.** Sessions have a 10-hour TTL and will timeout after extended inactivity. Simply reconnect to continue playing.
---
## Authentication & Token Issues
### "Invalid identity token" / "Failed to start Hytale"
**Solution:**
1. **Restart the launcher** - This fetches fresh tokens
2. **Check system time** - JWT validation requires accurate system time
3. **Clear cached tokens:**
- Delete `config.json` from your HytaleF2P folder
- Restart the launcher
- Re-enter your username
**Locations:**
- Windows: `%localappdata%\HytaleF2P\config.json`
- Linux: `~/.hytalef2p/config.json`
- macOS: `~/Library/Application Support/HytaleF2P/config.json`
### Token refresh errors
If you see issuer mismatch errors in logs:
1. Delete `config.json` and `player_id.json`
2. Restart the launcher
3. This forces a fresh authentication
---
## Avatar & Cosmetics Issues
### Avatar/skin changes not saving
**This is a known F2P limitation:**
- F2P mode has no password protection for usernames
- Anyone can use any username
- Cosmetics are stored server-side by username
- If someone else uses your username, they can change your cosmetics
**Workaround:** Use a unique username that others are unlikely to choose.
### Character invisible / Customization crashes
**Solution:**
1. Use **Repair Game** in launcher Settings
2. Verify `Assets.zip` exists in your game folder
3. Clear cached assets:
- Windows: Delete `%localappdata%\HytaleF2P\release\package\game\latest\Client\UserData\CachedAssets\`
4. Restart the launcher
### Avatar creator shows "Offline Mode"
**Cause:** Cannot connect to auth server.
**Solution:**
1. Check your internet connection
2. Test connectivity: Open `https://auth.sanasol.ws/health` in browser (should show "OK")
3. Check if firewall is blocking the connection
4. Try disabling VPN (or enabling one if in restricted region)
---
## General Issues
### Mods not showing up
**Solution:**
1. Ensure mods are placed in the correct folder:
- Windows: `%localappdata%\HytaleF2P\release\package\game\latest\Client\UserData\Mods\`
- Linux: `~/.hytalef2p/release/package/game/latest/Client/UserData/Mods/`
- macOS: `~/Library/Application Support/HytaleF2P/release/package/game/latest/Client/UserData/Mods/`
2. Verify mod files are `.jar` format
3. Check launcher logs for mod loading errors
### Game updates delete configurations/mods
**This is a known issue being worked on.**
**Prevention - Always backup before updating:**
- Server configs and worlds
- Mods folder
- `config.json` and `player_id.json`
See [Backup Locations](#backup-locations) below.
### Play button not clickable
Usually caused by GPU detection failure. See [GPU not detected](#gpu-not-detected--using-software-rendering-llvmpipe).
**Alternative:**
1. Go to **Settings** > **Graphics**
2. Manually select your GPU
3. Restart the launcher
### Read timeout errors
**Cause:** Network connectivity issues.
**Solutions:**
1. Check your internet connection stability
2. Try using a VPN
3. Check firewall settings
4. Try at a different time (server load varies)
---
## Known Limitations
### Linux ARM64 not supported
Hytale does not provide ARM64 game client builds. The launcher downloads from official Hytale servers which only provide:
- Windows x64
- macOS (Universal/Intel)
- Linux x64
This is outside our control.
### F2P Username System
- No password protection for usernames
- Anyone can claim any username
- Cosmetics shared by username
- UUIDs generated based on username
A per-player password system is planned for future versions.
### Session Timeout
Game sessions have a 10-hour TTL. This is by design for security.
---
## Backup Locations
### Windows
```
%localappdata%\HytaleF2P\
├── config.json # Launcher settings
├── player_id.json # Player identity
└── release\package\game\latest\
├── Client\UserData\ # Saves, settings, mods
└── Server\
├── universe\ # World data
└── config.json # Server config
```
### Linux
```
~/.hytalef2p/
├── config.json
├── player_id.json
└── release/package/game/latest/
├── Client/UserData/
└── Server/
├── universe/
└── config.json
```
### macOS
```
~/Library/Application Support/HytaleF2P/
├── config.json
├── player_id.json
└── release/package/game/latest/
├── Client/UserData/
└── Server/
├── universe/
└── config.json
```
---
## Getting Help
If your issue isn't resolved by this guide:
1. **Check existing issues:** [GitHub Issues](https://github.com/amiayweb/Hytale-F2P/issues)
2. **Join Discord:** [discord.gg/gME8rUy3MB](https://discord.gg/gME8rUy3MB)
3. **Open a new issue** with:
- Your operating system and version
- Launcher version
- Full launcher logs from:
- Windows: `%localappdata%\HytaleF2P\logs\`
- Linux: `~/.hytalef2p/logs/`
- macOS: `~/Library/Application Support/HytaleF2P/logs/`
- Steps to reproduce the issue
---
## Logs Location
For bug reports, please include logs from:
| OS | Path |
|----|------|
| Windows | `%localappdata%\HytaleF2P\logs\` |
| Linux | `~/.hytalef2p/logs/` |
| macOS | `~/Library/Application Support/HytaleF2P/logs/` |