Synchronize vJoy startup behavior across code and docs

Author: AntonW

README.md

@@ -1013,6 +1013,7 @@ Windows uses [vJoy](https://github.com/BrunnerInnovation/vJoy) for virtual joyst
     - `C:\Program Files\vJoy\bin\vJoyInterface.dll`
     - `C:\Program Files (x86)\vJoy\bin\vJoyInterface.dll`
     - System PATH
+    - After first successful load, OmniPanel-go keeps the DLL loaded for the process lifetime to avoid repeated vJoy reinitialization issues on some systems.
 4.  **Build with CGO (if building from source):**
     Install MinGW-w64 or MSYS2 GCC. Use the maintained build script for reliable builds:
     ```bash

docs/tutorials/08-virtual-input.md

@@ -354,7 +354,7 @@ vJoy is a signed kernel driver that creates up to 16 virtual joystick devices. E
 
 #### CGO Integration and DLL Loading
 
-The Windows joystick implementation uses CGO to call `vJoyInterface.dll`. To improve reliability across different Windows installations and build environments, the code uses a **multi-path DLL loading strategy**:
+The Windows joystick implementation uses CGO to call `vJoyInterface.dll`. To improve reliability across different Windows installations and build environments, the code uses a **multi-path DLL loading strategy** and **caches the loaded DLL handle for the process lifetime**:
 
 ```go
 //go:build windows && cgo
@@ -369,7 +369,11 @@ package devices
 // 2. Standard vJoy x64 install paths
 // 3. Standard vJoy bin paths
 // Returns the loaded module handle, or NULL if all paths fail.
+// The handle is cached to avoid repeated load/unload reinitialization.
 HMODULE load_vJoyInterface(void) {
+    static HMODULE cached = NULL;
+    if (cached) return cached;
+
     HMODULE h = NULL;
     const char* paths[] = {
         "vJoyInterface.dll",              // Current dir / PATH
@@ -381,7 +385,10 @@ HMODULE load_vJoyInterface(void) {
     };
     for (int i = 0; paths[i] != NULL; i++) {
         h = LoadLibraryA(paths[i]);
-        if (h) return h;
+        if (h) {
+            cached = h;
+            return cached;
+        }
     }
     return NULL;
 }
@@ -391,9 +398,8 @@ int wrap_vJoyEnabled(void) {
     HMODULE h = load_vJoyInterface();
     if (!h) return 0;
     vJoyEnabled_t fn = (vJoyEnabled_t)GetProcAddress(h, "vJoyEnabled");
-    if (!fn) { FreeLibrary(h); return 0; }
+    if (!fn) return 0;
     BOOL result = fn();
-    FreeLibrary(h);
     return result ? 1 : 0;
 }
 */
@@ -403,12 +409,21 @@ import "C"
 > **Why wrapper functions?**
 > Go CGO can't directly call `__cdecl` functions from a dynamically loaded DLL. The C wrapper functions use `LoadLibraryA`/`GetProcAddress` to dynamically load the DLL at runtime, then call the vJoy functions. This avoids requiring the DLL at link time.
 
+> **Concept (Go/C interop): process-lifetime resource caching**
+> In `internal/devices/windows.go`, `load_vJoyInterface` stores the first successful `HMODULE` in a static variable and reuses it. This avoids repeated DLL initialization/cleanup cycles, which can trigger startup dialog errors in some `vJoyInterface.dll` builds.
+
 > **Why multi-path loading?**
 > vJoy installs to different paths depending on Windows version, user permissions, and upgrade history. By checking multiple paths in order (PATH first for flexibility, then standard install directories), the code gracefully handles various configurations without requiring users to manually add vJoy to PATH or move DLLs around.
 
 > **Key Pattern: Graceful fallback chains**
 > The path array is a fallback chain — try the easiest option first, then progressively try more specific locations. This pattern appears throughout systems engineering: DNS resolution, environment variable lookup, and configuration file discovery all use similar strategies to maximize compatibility.
 
+> **Concept (JavaScript): stable transport contract**
+> In `static/client/client.js` (`initJoystick`), the browser only sends normalized `simulate-joystick` messages (`0-255` axis range). It does not know about DLL paths or OS APIs. This separation keeps frontend behavior stable while backend internals evolve.
+
+> **Key Pattern (JavaScript): protocol-first design**
+> Keep wire messages small and consistent (`type` + `data` payload), and isolate platform-specific details in backend adapters. The same UI code works for Linux `uinput` and Windows vJoy because both consume the same protocol.
+
 #### Axis Mapping
 
 OmniPanel-go's 8 axes (0-255 range) are mapped to vJoy HID usage codes:

docs/tutorials/19-windows-build-and-ci.md

@@ -57,7 +57,18 @@ This ensures the built binary has all required runtime dependencies. At runtime,
 2. Standard vJoy installation directories
 3. System PATH
 
-This two-pronged approach — build-time bundling + runtime multi-path search — maximizes compatibility across different Windows configurations.
+After the first successful load, the DLL handle is cached and reused for the rest of the process. This avoids repeated load/unload cycles that can produce vJoy startup dialog errors on some systems.
+
+This two-pronged approach — build-time bundling + runtime multi-path search with process-lifetime caching — maximizes compatibility across different Windows configurations.
+
+> **Concept (Go): cache once, reuse many times**
+> `internal/devices/windows.go` keeps the vJoy module handle after the first successful `LoadLibraryA`. Reusing one handle is safer than repeatedly loading and unloading a DLL that does global initialization.
+
+> **Concept (JavaScript): no frontend coupling to runtime DLL state**
+> The panel client (`static/client/client.js`) continues sending the same joystick WebSocket payloads regardless of how Windows loads vJoy. This keeps client behavior predictable for users.
+
+> **Key Pattern (Go + JavaScript): transport and adapter split**
+> The frontend speaks a stable protocol (`simulate-joystick` messages), while the backend adapter handles platform-specific DLL and driver details. This split reduces regressions when platform internals change.
 
 ## CI vs Local Script
 

docs/user-manual/de/12-virtual-joysticks.md

@@ -77,6 +77,8 @@ Nach der Installation von vJoy findet OmniPanel-go automatisch die `vJoyInterfac
 
 Wenn du OmniPanel-go von der Quelle mit dem Script `scripts/build-with-vosk.ps1` gebaut hast, wird die DLL automatisch neben deiner ausführbaren Datei kopiert. Andernfalls findet OmniPanel-go die DLL beim ersten Start im vJoy-Installationsverzeichnis.
 
+OmniPanel-go lädt diese DLL einmal und behält sie, solange die App läuft. Dadurch wird eine wiederholte vJoy-Neuinitialisierung beim Start vermieden und die Stabilität auf manchen Windows-Systemen verbessert.
+
 **Hinweis:** vJoy wird nur für virtuelle Joysticks benötigt. Virtuelle Maus- und Tastatureingaben nutzen die eingebaute `SendInput`-Funktion von Windows und brauchen keine zusätzlichen Treiber.
 
 ### macOS
@@ -258,6 +260,8 @@ In den Steuerelement-Einstellungen deines Spiels:
 - Starte OmniPanel-go nach der Installation von vJoy neu
 - Prüfe, dass die DLL nicht von Antivirus-Software unter Quarantäne gestellt wurde
 
+Wenn beim Start Popups von `vJoyInterface DLL` erscheinen (zum Beispiel `RegisterClassEx failed` oder `Creation of dummy window failed`), beende OmniPanel-go vollständig und starte es erneut, nachdem du die vJoy-Installation geprüft hast. Aktuelle OmniPanel-go-Versionen laden die DLL pro Lauf nur einmal, um dieses Problem zu reduzieren.
+
 **Linux:**
 - Prüfe, ob du Berechtigung für den Zugriff auf `/dev/uinput` hast
 - Versuche, OmniPanel-go mit `sudo` zu starten

docs/user-manual/en/12-virtual-joysticks.md

@@ -77,6 +77,8 @@ After installing vJoy, OmniPanel-go will automatically find the `vJoyInterface.d
 
 If you built OmniPanel-go from source using the `scripts/build-with-vosk.ps1` script, the DLL will be automatically copied next to your executable. Otherwise, OmniPanel-go will find it in the vJoy installation directory the first time it runs.
 
+OmniPanel-go loads this DLL once and keeps it loaded while the app is running. This avoids repeated vJoy re-initialization on startup and improves stability on some Windows systems.
+
 **Note:** vJoy is only needed for virtual joysticks. Virtual mouse and keyboard input use Windows' built-in `SendInput` function and don't require any extra drivers.
 
 ### macOS
@@ -258,6 +260,8 @@ In your game's control settings:
 - Restart OmniPanel-go after installing vJoy
 - Check that the DLL is not quarantined by antivirus software
 
+If you see startup popups from `vJoyInterface DLL` (for example `RegisterClassEx failed` or `Creation of dummy window failed`), fully close OmniPanel-go and start it again after verifying your vJoy install. Current versions of OmniPanel-go keep the DLL loaded once per run to reduce this issue.
+
 **Linux:**
 - Check that you have permission to access `/dev/uinput`
 - Try running OmniPanel-go with `sudo`

internal/devices/windows.go

@@ -22,10 +22,12 @@ package devices
 // CGO wrapper functions for vJoyInterface.dll calls
 // These are needed because Go CGO can't directly call __cdecl DLL functions
 // Attempts to load vJoyInterface.dll from multiple paths: current directory, vJoy install dir, and PATH.
+// The loaded module is cached for process lifetime because repeated load/unload cycles
+// can trigger initialization issues inside some vJoyInterface builds.
 
 HMODULE load_vJoyInterface(void) {
+	static HMODULE cached = NULL;
 	HMODULE h = NULL;
-	// Try: current directory, then vJoy standard install paths
 	const char* paths[] = {
 		"vJoyInterface.dll",              // Current dir / PATH
 		"C:\\Program Files\\vJoy\\x64\\vJoyInterface.dll",
@@ -34,9 +36,18 @@ HMODULE load_vJoyInterface(void) {
 		"C:\\Program Files (x86)\\vJoy\\bin\\vJoyInterface.dll",
 		NULL
 	};
+
+	if (cached) {
+		return cached;
+	}
+
+	// Try: current directory, then vJoy standard install paths
 	for (int i = 0; paths[i] != NULL; i++) {
 		h = LoadLibraryA(paths[i]);
-		if (h) return h;
+		if (h) {
+			cached = h;
+			return cached;
+		}
 	}
 	return NULL;
 }
@@ -46,9 +57,8 @@ int wrap_vJoyEnabled(void) {
 	HMODULE h = load_vJoyInterface();
 	if (!h) return 0;
 	vJoyEnabled_t fn = (vJoyEnabled_t)GetProcAddress(h, "vJoyEnabled");
-	if (!fn) { FreeLibrary(h); return 0; }
+	if (!fn) { return 0; }
 	BOOL result = fn();
-	FreeLibrary(h);
 	return result ? 1 : 0;
 }
 
@@ -57,9 +67,8 @@ int wrap_AcquireVJD(unsigned int rID) {
 	HMODULE h = load_vJoyInterface();
 	if (!h) return 0;
 	AcquireVJD_t fn = (AcquireVJD_t)GetProcAddress(h, "AcquireVJD");
-	if (!fn) { FreeLibrary(h); return 0; }
+	if (!fn) { return 0; }
 	BOOL result = fn(rID);
-	FreeLibrary(h);
 	return result ? 1 : 0;
 }
 
@@ -68,19 +77,17 @@ void wrap_RelinquishVJD(unsigned int rID) {
 	HMODULE h = load_vJoyInterface();
 	if (!h) return;
 	RelinquishVJD_t fn = (RelinquishVJD_t)GetProcAddress(h, "RelinquishVJD");
-	if (!fn) { FreeLibrary(h); return; }
+	if (!fn) { return; }
 	fn(rID);
-	FreeLibrary(h);
 }
 
 int wrap_SetAxis(long Value, unsigned int rID, unsigned int Axis) {
 	typedef BOOL (__cdecl *SetAxis_t)(long, unsigned int, unsigned int);
 	HMODULE h = load_vJoyInterface();
 	if (!h) return 0;
 	SetAxis_t fn = (SetAxis_t)GetProcAddress(h, "SetAxis");
-	if (!fn) { FreeLibrary(h); return 0; }
+	if (!fn) { return 0; }
 	BOOL result = fn(Value, rID, Axis);
-	FreeLibrary(h);
 	return result ? 1 : 0;
 }
 
@@ -89,9 +96,8 @@ int wrap_SetBtn(int Value, unsigned int rID, unsigned char nBtn) {
 	HMODULE h = load_vJoyInterface();
 	if (!h) return 0;
 	SetBtn_t fn = (SetBtn_t)GetProcAddress(h, "SetBtn");
-	if (!fn) { FreeLibrary(h); return 0; }
+	if (!fn) { return 0; }
 	BOOL result = fn(Value, rID, nBtn);
-	FreeLibrary(h);
 	return result ? 1 : 0;
 }
 */
@@ -110,8 +116,10 @@ type windowsJoystick struct {
 }
 
 // initVJoy checks if the vJoy driver is installed and available.
-// It calls wrap_vJoyEnabled via CGO, which attempts to load vJoyInterface.dll
-// from multiple paths (current directory, vJoy install directories, and PATH).
+// It calls wrap_vJoyEnabled via CGO, which loads vJoyInterface.dll from a
+// fallback path list and keeps the module loaded for the process lifetime.
+// Keeping the module loaded avoids repeated DLL reinitialization side effects
+// seen on some Windows setups.
 // Returns true if vJoy is ready to use, false otherwise.
 // This initialization runs once on package load via sync.Once.
 func initVJoy() bool {

static/client/client.js

@@ -568,6 +568,13 @@ function initButtonLayout(blockWrapper, btn) {
     }
 }
 
+/**
+ * initJoystick wires pointer events to joystick transport messages.
+ *
+ * The client always sends normalized `simulate-joystick` payloads (0-255 axis
+ * values). Backend runtime details (for example how Windows vJoy DLL loading is
+ * handled) stay server-side, so the frontend protocol remains stable.
+ */
 function initJoystick(blockWrapper) {
     const hitbox = blockWrapper.querySelector('.joy-hitbox');
     const base = blockWrapper.querySelector('.joy-base');