hytale-f2p/docs/LAUNCHER_TERMINATION_ANALYSIS.md

# Launcher Process Termination & Cleanup Analysis

## Overview
This document analyzes how the Hytale-F2P launcher handles process cleanup, event termination, and resource deallocation during shutdown.

## Shutdown Flow

### 1. **Primary Termination Events** (main.js)

#### Event: `before-quit` (Line 438)
```javascript
app.on('before-quit', () => {
  console.log('=== LAUNCHER BEFORE QUIT ===');
  cleanupDiscordRPC();
});
```
- Called by Electron before the app starts quitting
- Ensures Discord RPC is properly disconnected and destroyed
- Gives async cleanup a chance to run

#### Event: `window-all-closed` (Line 443)
```javascript
app.on('window-all-closed', () => {
  console.log('=== LAUNCHER CLOSING ===');
  app.quit();
});
```
- Triggered when all Electron windows are closed
- Initiates app.quit() to cleanly exit

#### Event: `closed` (Line 174)
```javascript
mainWindow.on('closed', () => {
  console.log('Main window closed, cleaning up Discord RPC...');
  cleanupDiscordRPC();
});
```
- Called when the main window is actually destroyed
- Additional Discord RPC cleanup as safety measure

---

## 2. **Discord RPC Cleanup** (Lines 59-89, 424-436)

### cleanupDiscordRPC() Function
```javascript
async function cleanupDiscordRPC() {
  if (!discordRPC) return;
  try {
    console.log('Cleaning up Discord RPC...');
    discordRPC.clearActivity();
    await new Promise(r => setTimeout(r, 100));  // Wait for clear to propagate
    discordRPC.destroy();
    console.log('Discord RPC cleaned up successfully');
  } catch (error) {
    console.log('Error cleaning up Discord RPC:', error.message);
  } finally {
    discordRPC = null;  // Null out the reference
  }
}
```

**What it does:**
1. Checks if Discord RPC is initialized
2. Clears the current activity (disconnects from Discord)
3. Waits 100ms for the clear to propagate
4. Destroys the Discord RPC client
5. Nulls out the reference to prevent memory leaks
6. Error handling ensures cleanup doesn't crash the app

**Quality:** ✅ **Proper cleanup with error handling**

---

## 3. **Game Process Handling** (gameLauncher.js)

### Game Launch Process (Lines 356-403)

```javascript
let spawnOptions = {
  stdio: ['ignore', 'pipe', 'pipe'],
  detached: false,
  env: env
};

if (process.platform === 'win32') {
  spawnOptions.shell = false;
  spawnOptions.windowsHide = true;
  spawnOptions.detached = true;      // ← Game runs independently
  spawnOptions.stdio = 'ignore';     // ← Fully detach stdio
}

const child = spawn(clientPath, args, spawnOptions);

// Windows: Release process reference immediately
if (process.platform === 'win32') {
  child.unref();  // ← Allows Node.js to exit without waiting for game
}
```

**Critical Analysis:**
- ✅ **Windows detached mode**: Game process is spawned detached and stdio is ignored
- ✅ **child.unref()**: Removes the Node process from the event loop
- ⚠️ **No event listeners**: Once detached, the launcher doesn't track the game process

**Potential Issue:**
The game process is completely detached and unrefed, which is correct. However, if the game crashes and respawns (or multiple instances), these orphaned processes could accumulate.

---

## 4. **Download/File Transfer Cleanup** (fileManager.js)

### setInterval Cleanup (Lines 77-94)
```javascript
const overallTimeout = setInterval(() => {
  const now = Date.now();
  const timeSinceLastProgress = now - lastProgressTime;
  
  if (timeSinceLastProgress > 900000 && hasReceivedData) {
    console.log('Download stalled for 15 minutes, aborting...');
    controller.abort();
  }
}, 60000);  // Check every minute
```

### Cleanup Locations:

**On Stream Error (Lines 225-228):**
```javascript
if (stalledTimeout) {
  clearTimeout(stalledTimeout);
}
if (overallTimeout) {
  clearInterval(overallTimeout);
}
```

**On Stream Close (Lines 239-244):**
```javascript
if (stalledTimeout) {
  clearTimeout(stalledTimeout);
}
if (overallTimeout) {
  clearInterval(overallTimeout);
}
```

**On Writer Finish (Lines 295-299):**
```javascript
if (stalledTimeout) {
  clearTimeout(stalledTimeout);
  console.log('Cleared stall timeout after writer finished');
}
if (overallTimeout) {
  clearInterval(overallTimeout);
  console.log('Cleared overall timeout after writer finished');
}
```

**Quality:** ✅ **Proper cleanup with multiple safeguards**
- Intervals are cleared in all exit paths
- No orphaned setInterval/setTimeout calls

---

## 5. **Electron Auto-Updater** (Lines 184-237)

```javascript
autoUpdater.autoDownload = true;
autoUpdater.autoInstallOnAppQuit = true;

autoUpdater.on('update-downloaded', (info) => {
  // ...
});
```

**Auto-Updater Cleanup:** ✅
- Electron handles auto-updater cleanup automatically
- No explicit cleanup needed (Electron manages lifecycle)

---

## Summary: Process Termination Quality

| Component | Status | Notes |
|-----------|--------|-------|
| **Discord RPC** | ✅ **Good** | Properly destroyed with error handling |
| **Main Window** | ✅ **Good** | Cleanup called on closed and before-quit |
| **Game Process** | ✅ **Good** | Detached and unref'd on Windows |
| **Download Intervals** | ✅ **Good** | Cleared in all exit paths |
| **Event Listeners** | ⚠️ **Mixed** | Main listeners properly removed, but IPC handlers remain registered (normal) |
| **Overall** | ✅ **Good** | Proper cleanup architecture |

---

## Potential Improvements

### 1. **Add Explicit Process Tracking (Optional)**
Currently, the launcher doesn't track child processes. We could add:
```javascript
// Track all spawned processes for cleanup
const childProcesses = new Set();

app.on('before-quit', () => {
  // Kill any remaining child processes
  for (const proc of childProcesses) {
    if (proc && !proc.killed) {
      proc.kill('SIGTERM');
    }
  }
});
```

### 2. **Auto-Updater Resource Cleanup (Minor)**
Add explicit cleanup for auto-updater listeners:
```javascript
app.on('before-quit', () => {
  autoUpdater.removeAllListeners();
});
```

### 3. **Graceful Shutdown Timeout (Safety)**
Add a safety timeout to force exit if cleanup hangs:
```javascript
app.on('before-quit', () => {
  const forceExitTimeout = setTimeout(() => {
    console.warn('Cleanup timeout - forcing exit');
    process.exit(0);
  }, 5000);  // 5 second max cleanup time
});
```

---

## Relationship to Ghost Process Issue

### Previous Issue (PowerShell processes)
- **Root cause**: Spawned PowerShell processes weren't cleaned up in `platformUtils.js`
- **Fixed by**: Replacing `execSync()` with `spawnSync()` + timeouts

### Launcher Termination
- **Status**: ✅ **No critical issues found**
- **Discord RPC**: Properly cleaned up
- **Game process**: Properly detached
- **Intervals**: Properly cleared
- **No memory leaks detected**

The launcher's termination flow is solid. The ghost process issue was specific to PowerShell process spawning during GPU detection, not the launcher's shutdown process.

---

## Testing Checklist

To verify proper launcher termination:

- [ ] Start launcher → Close window → Check Task Manager for lingering processes
- [ ] Start launcher → Launch game → Close launcher → Check for orphaned processes
- [ ] Start launcher → Download something → Cancel mid-download → Check for setInterval processes
- [ ] Disable Discord RPC → Start launcher → Close → No Discord processes remain
- [ ] Check Windows Event Viewer → No unhandled exceptions on launcher exit
- [ ] Multiple launch/close cycles → No memory growth in Task Manager

---

## Conclusion

The Hytale-F2P launcher has **good shutdown hygiene**:
- ✅ Discord RPC is properly cleaned
- ✅ Game process is properly detached
- ✅ Download intervals are properly cleared
- ✅ Event handlers are properly registered

The ghost process issue was **not** caused by the launcher's termination logic, but by the PowerShell GPU detection functions, which has already been fixed.