v2.4.7: Fix Linux SDL3_image crash and NVIDIA Wayland stability

- Add LD_LIBRARY_PATH with Client directory so the dynamic linker finds
  bundled native libraries (libSDL3_image.so.0, etc). Official Hytale
  uses Flatpak which provides these; F2P runs natively and needs this.
- Add __NV_DISABLE_EXPLICIT_SYNC=1 for NVIDIA on Wayland to prevent
  crashes on Hyprland and other Wayland compositors.

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

backend/managers/gameLauncher.js

@@ -445,6 +445,17 @@ async function launchGame(playerNameOverride = null, progressCallback, javaPathO
 
   const env = { ...process.env };
 
+  // Linux: Add Client directory to LD_LIBRARY_PATH so the dynamic linker can find
+  // bundled native libraries (e.g. libSDL3_image.so.0). The .NET DllImport only tries
+  // bare names like "SDL3_image.so" which don't match versioned .so.0 files.
+  // LD_LIBRARY_PATH lets dlopen() find them via standard library resolution.
+  if (process.platform === 'linux') {
+    const clientDir = path.dirname(clientPath);
+    const existing = env.LD_LIBRARY_PATH || '';
+    env.LD_LIBRARY_PATH = existing ? `${clientDir}:${existing}` : clientDir;
+    console.log(`Linux: LD_LIBRARY_PATH includes ${clientDir}`);
+  }
+
   const waylandEnv = setupWaylandEnvironment();
   Object.assign(env, waylandEnv);
   const gpuEnv = setupGpuEnvironment(gpuPreference);

backend/utils/platformUtils.js

@@ -594,6 +594,10 @@ function setupGpuEnvironment(gpuPreference) {
     if (detected.vendor === 'nvidia') {
       envVars.__NV_PRIME_RENDER_OFFLOAD = '1';
       envVars.__GLX_VENDOR_LIBRARY_NAME = 'nvidia';
+      // Prevent Wayland explicit sync crashes on NVIDIA (Hyprland, etc.)
+      if (isWaylandSession()) {
+        envVars.__NV_DISABLE_EXPLICIT_SYNC = '1';
+      }
       const nvidiaEglFile = '/usr/share/glvnd/egl_vendor.d/10_nvidia.json';
       if (fs.existsSync(nvidiaEglFile)) {
         envVars.__EGL_VENDOR_LIBRARY_FILENAMES = nvidiaEglFile;

docs/FASTUTIL_CLASSLOADER_ISSUE.md

@@ -1,6 +1,6 @@
 # Singleplayer Server Crash: fastutil ClassNotFoundException
 
-## Status: Open — NO SOLUTION (Feb 24-27 2026)
+## Status: Open — likely outdated HytaleServer.jar (Feb 24-28 2026)
 
 ## Symptom
 
@@ -20,9 +20,10 @@ Server exits with code 1. Multiplayer works fine for the same user.
 
 1. **ヅ𝚃 JAYED !** (Feb 24) — Windows x86_64, had AOT cache errors before fastutil crash
 2. **Asentrix** (Feb 27) — Windows x86_64 (NT 10.0.26200.0), RTX 4060, Launcher v2.4.4, NO AOT cache errors
+3. **7645754** (Feb 28) — Standalone server on localhost, **FIXED by updating HytaleServer.jar**
 
-- Reproduces 100% on singleplayer, every attempt
-- Multiplayer works fine for both users
+- Reproduces 100% on singleplayer, every attempt (users 1-2)
+- Multiplayer works fine for users 1-2
 - macOS/Linux users are NOT affected
 
 ## Ruled Out (confirmed via debug builds)
@@ -37,26 +38,30 @@ Server exits with code 1. Multiplayer works fine for the same user.
 | **ARM64/Parallels** | User is on standard Windows x86_64 | Not applicable. |
 | **AOT cache** | Asentrix has no AOT errors (JAYED did), both crash the same way | Not the root cause. |
 
+## Key Finding: Outdated HytaleServer.jar (Feb 28)
+
+User `7645754` had the **exact same error** on their standalone localhost server but NOT on their VPS. **Fixed by replacing `HytaleServer.jar` with the current version.** The old JAR used to work but stopped — likely the bundled JRE was updated and is now incompatible with older JAR versions.
+
+This strongly suggests the root cause for F2P launcher users is also a **stale/mismatched `HytaleServer.jar`**. The launcher may report the correct version but the actual file on disk could be from an older download.
+
 ## What We Know
 
-- `fastutil` is bundled inside `HytaleServer.jar` (fat/shaded JAR) — same JAR for all users
+- `fastutil` is bundled inside `HytaleServer.jar` (fat/shaded JAR)
 - JVM's `BuiltinClassLoader` cannot find `it.unimi.dsi.fastutil.objects.ObjectArrayList` despite it being in the JAR
 - Crash happens at `EarlyPluginLoader` static initializer (line 34) which imports `ObjectArrayList`
-- The bundled JRE is identical for all users (downloaded by launcher)
-- The issue is **not** caused by anything the F2P launcher adds — it's the vanilla server JVM failing to load its own classes
+- **Replacing `HytaleServer.jar` with a fresh copy fixes the issue** (confirmed by user 3)
+- The issue is NOT caused by the DualAuth agent or any launcher modification
 
-## Remaining Theories
+## Fix for Users
 
-1. **Antivirus/security software** — Windows Defender or third-party AV intercepting JAR file reads. Real-time scanning + fat JAR = known conflict. **Untested** — user should try disabling AV temporarily.
-2. **Windows Insider build** — Asentrix is on NT 10.0.26200.0 (Windows 11 Dev/Insider). Bleeding-edge Windows may have JVM compatibility issues.
-3. **File locking** — Stalled `java.exe` processes holding `HytaleServer.jar` open (Asentrix had stalled processes killed at every launch).
-4. **Corrupted JRE on disk** — Despite being the same download, filesystem or AV may have corrupted specific JRE files on their system.
+### F2P Launcher users (Asentrix, JAYED)
+1. **Delete the entire game folder**: `%LOCALAPPDATA%\HytaleF2P\release\package\game\`
+2. Relaunch — launcher will re-download everything fresh
+3. NOT just "repair" — full delete to ensure no stale files remain
 
-## Next Steps to Try
-
-1. **Disable Windows Defender** temporarily — the only quick test left
-2. **Delete bundled JRE** and let launcher re-download — rules out local JRE corruption
-3. **Ask if official Hytale singleplayer works** — if it also crashes, it's their system (but F2P users may not have access)
+### Standalone server users
+1. Download fresh `HytaleServer.jar` from current game version
+2. Replace the old JAR file
 
 ## Update History
 
@@ -70,6 +75,12 @@ User reported singleplayer crash. Initial investigation found AOT cache errors +
 - **Conclusion**: Neither the agent nor CDS is the cause. The JVM itself cannot load classes from the fat JAR on these specific Windows systems.
 - Note: wrapper `injectArgs` append AFTER `-jar`, so they cannot inject JVM flags — only `JAVA_TOOL_OPTIONS` works for JVM flags
 
+### Feb 28: Third user (7645754) — FIXED by replacing HytaleServer.jar
+- Standalone server user had same crash on localhost, VPS worked fine
+- **Fixed by updating `HytaleServer.jar` to match VPS version**
+- Root cause likely: outdated JAR incompatible with current/updated JRE
+- For F2P launcher users: need to delete game folder and force fresh re-download
+
 ## Related
 
 - Java wrapper config: `backend/core/config.js` (stripFlags / injectArgs)

package.json

@@ -1,6 +1,6 @@
 {
   "name": "hytale-f2p-launcher",
-  "version": "2.4.6",
+  "version": "2.4.7",
   "description": "A modern, cross-platform launcher for Hytale with automatic updates and multi-client support",
   "homepage": "https://git.sanhost.net/sanasol/hytale-f2p",
   "main": "main.js",