Update fastutil classloader issue docs: outdated HytaleServer.jar identified as root cause, add fix steps for users

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)