From 3abdd10cabb421a7ed2346ce10fe602d2369f14c Mon Sep 17 00:00:00 2001
From: sanasol <mail@sanasol.ws>
Date: Fri, 27 Feb 2026 21:52:13 +0100
Subject: [PATCH] v2.4.5: Add multi-instance setting for mod developers

Allow running multiple game clients simultaneously via a new
"Allow multiple game instances" toggle in Settings. When enabled,
skips the Electron single-instance lock and the pre-launch process
kill, so existing game instances stay alive.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 GUI/index.html                   | 12 ++++++++++++
 GUI/js/settings.js               | 31 +++++++++++++++++++++++++++++++
 GUI/locales/ar-SA.json           |  2 ++
 GUI/locales/de-DE.json           |  2 ++
 GUI/locales/en.json              |  2 ++
 GUI/locales/es-ES.json           |  2 ++
 GUI/locales/fr-FR.json           |  2 ++
 GUI/locales/id-ID.json           |  2 ++
 GUI/locales/pl-PL.json           |  2 ++
 GUI/locales/pt-BR.json           |  2 ++
 GUI/locales/ru-RU.json           |  2 ++
 GUI/locales/sv-SE.json           |  2 ++
 GUI/locales/tr-TR.json           |  2 ++
 backend/core/config.js           | 11 +++++++++++
 backend/launcher.js              |  6 ++++++
 backend/managers/gameLauncher.js |  7 +++++--
 main.js                          | 16 +++++++++++++---
 package.json                     |  2 +-
 preload.js                       |  2 ++
 19 files changed, 103 insertions(+), 6 deletions(-)

diff --git a/GUI/index.html b/GUI/index.html
index ec5bc27..65314c9 100644
--- a/GUI/index.html
+++ b/GUI/index.html
@@ -592,6 +592,18 @@
                                                 </div>
                                             </label>
                                         </div>
+                                        <div class="settings-option">
+                                            <label class="settings-checkbox">
+                                                <input type="checkbox" id="allowMultiInstanceCheck" />
+                                                <span class="checkmark"></span>
+                                                <div class="checkbox-content">
+                                                    <div class="checkbox-title" data-i18n="settings.allowMultiInstance">Allow multiple game instances</div>
+                                                    <div class="checkbox-description" data-i18n="settings.allowMultiInstanceDescription">
+                                                        Allow running multiple game clients at the same time (useful for mod development)
+                                                    </div>
+                                                </div>
+                                            </label>
+                                        </div>
                                         <div class="settings-option">
                                             <label class="settings-checkbox">
                                                 <input type="checkbox" id="launcherHwAccelCheck" />
diff --git a/GUI/js/settings.js b/GUI/js/settings.js
index d22370a..811a917 100644
--- a/GUI/js/settings.js
+++ b/GUI/js/settings.js
@@ -6,6 +6,7 @@ let browseJavaBtn;
 let settingsPlayerName;
 let discordRPCCheck;
 let closeLauncherCheck;
+let allowMultiInstanceCheck;
 let launcherHwAccelCheck;
 let gpuPreferenceRadios;
 let gameBranchRadios;
@@ -171,6 +172,7 @@ function setupSettingsElements() {
   settingsPlayerName = document.getElementById('settingsPlayerName');
   discordRPCCheck = document.getElementById('discordRPCCheck');
   closeLauncherCheck = document.getElementById('closeLauncherCheck');
+  allowMultiInstanceCheck = document.getElementById('allowMultiInstanceCheck');
   launcherHwAccelCheck = document.getElementById('launcherHwAccelCheck');
   gpuPreferenceRadios = document.querySelectorAll('input[name="gpuPreference"]');
   gameBranchRadios = document.querySelectorAll('input[name="gameBranch"]');
@@ -218,6 +220,10 @@ function setupSettingsElements() {
     closeLauncherCheck.addEventListener('change', saveCloseLauncher);
   }
 
+  if (allowMultiInstanceCheck) {
+    allowMultiInstanceCheck.addEventListener('change', saveAllowMultiInstance);
+  }
+
   if (launcherHwAccelCheck) {
     launcherHwAccelCheck.addEventListener('change', saveLauncherHwAccel);
   }
@@ -415,6 +421,30 @@ async function loadCloseLauncher() {
   }
 }
 
+async function saveAllowMultiInstance() {
+  try {
+    if (window.electronAPI && window.electronAPI.saveAllowMultiInstance && allowMultiInstanceCheck) {
+      const enabled = allowMultiInstanceCheck.checked;
+      await window.electronAPI.saveAllowMultiInstance(enabled);
+    }
+  } catch (error) {
+    console.error('Error saving multi-instance setting:', error);
+  }
+}
+
+async function loadAllowMultiInstance() {
+  try {
+    if (window.electronAPI && window.electronAPI.loadAllowMultiInstance) {
+      const enabled = await window.electronAPI.loadAllowMultiInstance();
+      if (allowMultiInstanceCheck) {
+        allowMultiInstanceCheck.checked = enabled;
+      }
+    }
+  } catch (error) {
+    console.error('Error loading multi-instance setting:', error);
+  }
+}
+
 async function saveLauncherHwAccel() {
   try {
     if (window.electronAPI && window.electronAPI.saveLauncherHardwareAcceleration && launcherHwAccelCheck) {
@@ -587,6 +617,7 @@ async function loadAllSettings() {
   await loadCurrentUuid();
   await loadDiscordRPC();
   await loadCloseLauncher();
+  await loadAllowMultiInstance();
   await loadLauncherHwAccel();
   await loadGpuPreference();
   await loadVersionBranch();
diff --git a/GUI/locales/ar-SA.json b/GUI/locales/ar-SA.json
index a57d87a..3749986 100644
--- a/GUI/locales/ar-SA.json
+++ b/GUI/locales/ar-SA.json
@@ -140,6 +140,8 @@
     "closeLauncher": "سلوك المشغل",
     "closeOnStart": "إغلاق المشغل عند بدء اللعبة",
     "closeOnStartDescription": "إغلاق المشغل تلقائياً بعد تشغيل Hytale",
+    "allowMultiInstance": "Allow multiple game instances",
+    "allowMultiInstanceDescription": "Allow running multiple game clients at the same time (useful for mod development)",
     "hwAccel": "تسريع الأجهزة (Hardware Acceleration)",
     "hwAccelDescription": "تفعيل تسريع الأجهزة للمشغل",
     "gameBranch": "فرع اللعبة",
diff --git a/GUI/locales/de-DE.json b/GUI/locales/de-DE.json
index 530dd1c..c818ea6 100644
--- a/GUI/locales/de-DE.json
+++ b/GUI/locales/de-DE.json
@@ -140,6 +140,8 @@
     "closeLauncher": "Launcher-Verhalten",
     "closeOnStart": "Launcher beim Spielstart schließen",
     "closeOnStartDescription": "Schließe den Launcher automatisch, nachdem Hytale gestartet wurde",
+    "allowMultiInstance": "Allow multiple game instances",
+    "allowMultiInstanceDescription": "Allow running multiple game clients at the same time (useful for mod development)",
     "hwAccel": "Hardware-Beschleunigung",
     "hwAccelDescription": "Hardware-Beschleunigung für den Launcher aktivieren",
     "gameBranch": "Spiel-Branch",
diff --git a/GUI/locales/en.json b/GUI/locales/en.json
index d2da396..829bd52 100644
--- a/GUI/locales/en.json
+++ b/GUI/locales/en.json
@@ -140,6 +140,8 @@
     "closeLauncher": "Launcher Behavior",
     "closeOnStart": "Close Launcher on game start",
     "closeOnStartDescription": "Automatically close the launcher after Hytale has launched",
+    "allowMultiInstance": "Allow multiple game instances",
+    "allowMultiInstanceDescription": "Allow running multiple game clients at the same time (useful for mod development)",
     "hwAccel": "Hardware Acceleration",
     "hwAccelDescription": "Enable hardware acceleration for the launcher",
     "gameBranch": "Game Branch",
diff --git a/GUI/locales/es-ES.json b/GUI/locales/es-ES.json
index d8fccdd..6238372 100644
--- a/GUI/locales/es-ES.json
+++ b/GUI/locales/es-ES.json
@@ -140,6 +140,8 @@
     "closeLauncher": "Comportamiento del Launcher",
     "closeOnStart": "Cerrar Launcher al iniciar el juego",
     "closeOnStartDescription": "Cierra automáticamente el launcher después de que Hytale se haya iniciado",
+    "allowMultiInstance": "Allow multiple game instances",
+    "allowMultiInstanceDescription": "Allow running multiple game clients at the same time (useful for mod development)",
     "hwAccel": "Aceleración por Hardware",
     "hwAccelDescription": "Habilitar aceleración por hardware para el launcher",
     "gameBranch": "Rama del Juego",
diff --git a/GUI/locales/fr-FR.json b/GUI/locales/fr-FR.json
index 3186551..51aa7de 100644
--- a/GUI/locales/fr-FR.json
+++ b/GUI/locales/fr-FR.json
@@ -140,6 +140,8 @@
     "closeLauncher": "Comportement du Launcher",
     "closeOnStart": "Fermer le Launcher au démarrage du jeu",
     "closeOnStartDescription": "Fermer automatiquement le launcher après le lancement d'Hytale",
+    "allowMultiInstance": "Allow multiple game instances",
+    "allowMultiInstanceDescription": "Allow running multiple game clients at the same time (useful for mod development)",
     "hwAccel": "Accélération Matérielle",
     "hwAccelDescription": "Activer l'accélération matérielle pour le launcher",
     "gameBranch": "Branche du Jeu",
diff --git a/GUI/locales/id-ID.json b/GUI/locales/id-ID.json
index 87187a8..5a2144d 100644
--- a/GUI/locales/id-ID.json
+++ b/GUI/locales/id-ID.json
@@ -140,6 +140,8 @@
     "closeLauncher": "Perilaku Launcher",
     "closeOnStart": "Tutup launcher saat game dimulai",
     "closeOnStartDescription": "Tutup launcher secara otomatis setelah Hytale diluncurkan",
+    "allowMultiInstance": "Allow multiple game instances",
+    "allowMultiInstanceDescription": "Allow running multiple game clients at the same time (useful for mod development)",
     "hwAccel": "Akselerasi Perangkat Keras",
     "hwAccelDescription": "Aktifkan akselerasi perangkat keras untuk launcher`",
     "gameBranch": "Cabang Game",
diff --git a/GUI/locales/pl-PL.json b/GUI/locales/pl-PL.json
index 46e7673..8cce253 100644
--- a/GUI/locales/pl-PL.json
+++ b/GUI/locales/pl-PL.json
@@ -140,6 +140,8 @@
     "closeLauncher": "Zachowanie Launchera",
     "closeOnStart": "Zamknij Launcher przy starcie gry",
     "closeOnStartDescription": "Automatycznie zamknij launcher po uruchomieniu Hytale",
+    "allowMultiInstance": "Allow multiple game instances",
+    "allowMultiInstanceDescription": "Allow running multiple game clients at the same time (useful for mod development)",
     "hwAccel": "Przyspieszenie Sprzętowe",
     "hwAccelDescription": "Włącz przyspieszenie sprzętowe dla launchera",
     "gameBranch": "Gałąź Gry",
diff --git a/GUI/locales/pt-BR.json b/GUI/locales/pt-BR.json
index 12f6df1..887de6c 100644
--- a/GUI/locales/pt-BR.json
+++ b/GUI/locales/pt-BR.json
@@ -140,6 +140,8 @@
     "closeLauncher": "Comportamento do Lançador",
     "closeOnStart": "Fechar Lançador ao iniciar o jogo",
     "closeOnStartDescription": "Fechar automaticamente o lançador após o Hytale ter sido iniciado",
+    "allowMultiInstance": "Allow multiple game instances",
+    "allowMultiInstanceDescription": "Allow running multiple game clients at the same time (useful for mod development)",
     "hwAccel": "Aceleração de Hardware",
     "hwAccelDescription": "Ativar aceleração de hardware para o lançador",
     "gameBranch": "Versão do Jogo",
diff --git a/GUI/locales/ru-RU.json b/GUI/locales/ru-RU.json
index 2e82e12..7ee5142 100644
--- a/GUI/locales/ru-RU.json
+++ b/GUI/locales/ru-RU.json
@@ -140,6 +140,8 @@
     "closeLauncher": "Поведение лаунчера",
     "closeOnStart": "Закрыть лаунчер при старте игры",
     "closeOnStartDescription": "Автоматически закрыть лаунчер после запуска Hytale",
+    "allowMultiInstance": "Несколько копий игры",
+    "allowMultiInstanceDescription": "Разрешить запуск нескольких клиентов одновременно (полезно для разработки модов)",
     "hwAccel": "Аппаратное ускорение",
     "hwAccelDescription": "Включить аппаратное ускорение для лаунчера",
     "gameBranch": "Ветка игры",
diff --git a/GUI/locales/sv-SE.json b/GUI/locales/sv-SE.json
index c6fb7ad..30688ee 100644
--- a/GUI/locales/sv-SE.json
+++ b/GUI/locales/sv-SE.json
@@ -140,6 +140,8 @@
     "closeLauncher": "Launcher-beteende",
     "closeOnStart": "Stäng launcher vid spelstart",
     "closeOnStartDescription": "Stäng automatiskt launcher efter att Hytale har startats",
+    "allowMultiInstance": "Allow multiple game instances",
+    "allowMultiInstanceDescription": "Allow running multiple game clients at the same time (useful for mod development)",
     "hwAccel": "Hårdvaruacceleration",
     "hwAccelDescription": "Aktivera hårdvaruacceleration för launchern",
     "gameBranch": "Spelgren",
diff --git a/GUI/locales/tr-TR.json b/GUI/locales/tr-TR.json
index 09c4ab8..ddc64e4 100644
--- a/GUI/locales/tr-TR.json
+++ b/GUI/locales/tr-TR.json
@@ -140,6 +140,8 @@
     "closeLauncher": "Başlatıcı Davranışı",
     "closeOnStart": "Oyun başlatıldığında Başlatıcıyı Kapat",
     "closeOnStartDescription": "Hytale başlatıldıktan sonra başlatıcıyı otomatik olarak kapatın",
+    "allowMultiInstance": "Allow multiple game instances",
+    "allowMultiInstanceDescription": "Allow running multiple game clients at the same time (useful for mod development)",
     "hwAccel": "Donanım Hızlandırma",
     "hwAccelDescription": "Başlatıcı için donanım hızlandırmasını etkinleştir",
     "gameBranch": "Oyun Dalı",
diff --git a/backend/core/config.js b/backend/core/config.js
index 25f4a67..b89ca8d 100644
--- a/backend/core/config.js
+++ b/backend/core/config.js
@@ -708,6 +708,15 @@ function loadLauncherHardwareAcceleration() {
   return config.launcherHardwareAcceleration !== undefined ? config.launcherHardwareAcceleration : true;
 }
 
+function saveAllowMultiInstance(enabled) {
+  saveConfig({ allowMultiInstance: !!enabled });
+}
+
+function loadAllowMultiInstance() {
+  const config = loadConfig();
+  return config.allowMultiInstance !== undefined ? config.allowMultiInstance : false;
+}
+
 // =============================================================================
 // MODS MANAGEMENT
 // =============================================================================
@@ -1105,6 +1114,8 @@ module.exports = {
   loadCloseLauncherOnStart,
   saveLauncherHardwareAcceleration,
   loadLauncherHardwareAcceleration,
+  saveAllowMultiInstance,
+  loadAllowMultiInstance,
 
   // Mods
   saveModsToConfig,
diff --git a/backend/launcher.js b/backend/launcher.js
index 7ef9d4e..bdb90cb 100644
--- a/backend/launcher.js
+++ b/backend/launcher.js
@@ -20,6 +20,8 @@ const {
 
   saveLauncherHardwareAcceleration,
   loadLauncherHardwareAcceleration,
+  saveAllowMultiInstance,
+  loadAllowMultiInstance,
 
   loadConfig,
   saveConfig,
@@ -151,6 +153,10 @@ module.exports = {
   saveLauncherHardwareAcceleration,
   loadLauncherHardwareAcceleration,
 
+  // Multi-instance functions
+  saveAllowMultiInstance,
+  loadAllowMultiInstance,
+
   // Config functions
   loadConfig,
   saveConfig,
diff --git a/backend/managers/gameLauncher.js b/backend/managers/gameLauncher.js
index e3aa072..39c5e32 100644
--- a/backend/managers/gameLauncher.js
+++ b/backend/managers/gameLauncher.js
@@ -30,6 +30,7 @@ const { syncModsForCurrentProfile } = require('./modManager');
 const { getUserDataPath } = require('../utils/userDataMigration');
 const { syncServerList } = require('../utils/serverListSync');
 const { killGameProcesses } = require('./gameManager');
+const { loadAllowMultiInstance } = require('../core/config');
 
 // Client patcher for custom auth server (sanasol.ws)
 let clientPatcher = null;
@@ -464,8 +465,10 @@ async function launchGame(playerNameOverride = null, progressCallback, javaPathO
   }
 
   // Kill any stalled game processes from a previous launch to prevent file locks
-  // and "game already running" issues
-  await killGameProcesses();
+  // and "game already running" issues (skip if multi-instance mode is enabled)
+  if (!loadAllowMultiInstance()) {
+    await killGameProcesses();
+  }
 
   // Remove AOT cache: generated by official Hytale JRE, incompatible with F2P JRE.
   // Client adds -XX:AOTCache when this file exists, causing classloading failures.
diff --git a/main.js b/main.js
index c6e84ce..6b258b0 100644
--- a/main.js
+++ b/main.js
@@ -3,7 +3,7 @@ require('dotenv').config({ path: path.join(__dirname, '.env') });
 const { app, BrowserWindow, ipcMain, dialog, shell } = require('electron');
 const { autoUpdater } = require('electron-updater');
 const fs = require('fs');
-const { launchGame, launchGameWithVersionCheck, installGame, saveUsername, loadUsername, saveJavaPath, loadJavaPath, saveInstallPath, loadInstallPath, saveDiscordRPC, loadDiscordRPC, saveLanguage, loadLanguage, saveCloseLauncherOnStart, loadCloseLauncherOnStart, saveLauncherHardwareAcceleration, loadLauncherHardwareAcceleration, isGameInstalled, uninstallGame, repairGame, getHytaleNews, handleFirstLaunchCheck, proposeGameUpdate, markAsLaunched, loadConfig, saveConfig, checkLaunchReady } = require('./backend/launcher');
+const { launchGame, launchGameWithVersionCheck, installGame, saveUsername, loadUsername, saveJavaPath, loadJavaPath, saveInstallPath, loadInstallPath, saveDiscordRPC, loadDiscordRPC, saveLanguage, loadLanguage, saveCloseLauncherOnStart, loadCloseLauncherOnStart, saveLauncherHardwareAcceleration, loadLauncherHardwareAcceleration, saveAllowMultiInstance, loadAllowMultiInstance, isGameInstalled, uninstallGame, repairGame, getHytaleNews, handleFirstLaunchCheck, proposeGameUpdate, markAsLaunched, loadConfig, saveConfig, checkLaunchReady } = require('./backend/launcher');
 const { retryPWRDownload } = require('./backend/managers/gameManager');
 const { migrateUserDataToCentralized } = require('./backend/utils/userDataMigration');
 
@@ -23,8 +23,9 @@ const profileManager = require('./backend/managers/profileManager');
 
 logger.interceptConsole();
 
-// Single instance lock
-const gotTheLock = app.requestSingleInstanceLock();
+// Single instance lock (skip if multi-instance mode is enabled)
+const multiInstanceEnabled = loadAllowMultiInstance();
+const gotTheLock = multiInstanceEnabled || app.requestSingleInstanceLock();
 
 if (!gotTheLock) {
   console.log('Another instance is already running. Quitting...');
@@ -740,6 +741,15 @@ ipcMain.handle('load-close-launcher', () => {
   return loadCloseLauncherOnStart();
 });
 
+ipcMain.handle('save-allow-multi-instance', (event, enabled) => {
+  saveAllowMultiInstance(enabled);
+  return { success: true };
+});
+
+ipcMain.handle('load-allow-multi-instance', () => {
+  return loadAllowMultiInstance();
+});
+
 ipcMain.handle('save-launcher-hw-accel', (event, enabled) => {
   saveLauncherHardwareAcceleration(enabled);
   return { success: true };
diff --git a/package.json b/package.json
index 8eab73e..b7bd436 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "hytale-f2p-launcher",
-  "version": "2.4.4",
+  "version": "2.4.5",
   "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",
diff --git a/preload.js b/preload.js
index d3e672c..d8d2e18 100644
--- a/preload.js
+++ b/preload.js
@@ -20,6 +20,8 @@ contextBridge.exposeInMainWorld('electronAPI', {
   loadLanguage: () => ipcRenderer.invoke('load-language'),
   saveCloseLauncher: (enabled) => ipcRenderer.invoke('save-close-launcher', enabled),
   loadCloseLauncher: () => ipcRenderer.invoke('load-close-launcher'),
+  saveAllowMultiInstance: (enabled) => ipcRenderer.invoke('save-allow-multi-instance', enabled),
+  loadAllowMultiInstance: () => ipcRenderer.invoke('load-allow-multi-instance'),
   loadConfig: () => ipcRenderer.invoke('load-config'),
   saveConfig: (configUpdate) => ipcRenderer.invoke('save-config', configUpdate),