Game Detection Failure on macOS and App Freezing During Game Load

[secede-clo]

Hello, I'm reporting two critical bugs I've encountered while using TFT Hextech Helper:

1. Game detection failure on macOS - The application fails to detect the League of Legends client on macOS systems, preventing it from working at all on macOS.
2. Application freezing when game loads - The app becomes completely unresponsive after the game client loads into a match, requiring a force-quit.

---

Bug #1: Game Detection Failure on macOS

Description

The application is unable to detect the League of Legends client when running on macOS. After launching the League client and then launching TFT Hextech Helper, the app continuously reports that the client is not detected and never establishes a connection.

Environment

• OS: macOS (tested on macOS 14+ with Apple Silicon)
• League Client: Latest version
• Application Version: 0.1.0
• Architecture: arm64 (Apple Silicon)

Steps to Reproduce

1. Launch League of Legends client on macOS (ensure it's fully logged in)
2. Launch TFT Hextech Helper application
3. Wait for client detection - it never happens
4. Check console logs - you'll see repeated "LOL客户端未启动，一秒后将再次检查..." messages indefinitely

Expected Behavior

The application should detect the League client within 1-2 seconds after launch and establish an LCU connection, similar to how it works on Windows.

Actual Behavior

• The application continuously polls for the client but never successfully detects it
• Console shows repeated "client not found" messages
• The app never progresses past the initial connection phase
• No error messages explaining why detection fails

Technical Details Observed

I investigated the issue and found the problem appears to be in the process detection logic. The getLCUInfoFromProcess() method in src-backend/lcu/utils/LcuConnector.ts seems to have issues on macOS:

1. Process command returns multiple processes: When running ps x -o args | grep 'LeagueClientUx' on macOS, it returns multiple processes (the main LeagueClientUx process plus helper processes like GPU, Renderer, Utility helpers, etc.), and the code doesn't properly filter to find just the main process.

2. Regex pattern issue with paths: The regex pattern for extracting --install-directory expects quoted paths (like "--install-directory=/path"), but on macOS the process command line doesn't use quotes around the path value. Additionally, macOS paths can contain spaces (e.g., /Applications/League of Legends.app/Contents/LoL), which the current regex pattern --install-directory=(.*?)" doesn't handle because it stops at the first space.

3. Grep command self-match: The grep command itself can appear in the process list, adding noise to the output that needs to be filtered out.

Steps to Reproduce

1. Launch League of Legends client on macOS
2. Launch TFT Hextech Helper application
3. Observe that the app never detects the client connection
4. Check console logs - you'll see repeated "LOL客户端未启动，一秒后将再次检查..." messages

Expected Behavior

The application should detect the League client within 1-2 seconds and establish an LCU connection.

Actual Behavior

The application continuously polls for the client but never successfully parses the process information, resulting in indefinite "client not found" messages.

Suggested Fix

Based on my investigation, here are potential fixes that might resolve the issue:

1. Improve process filtering: Update the process detection command to use grep '[L]eagueClientUx' (the [L] bracket trick prevents grep from matching itself) and filter out helper processes by checking for --type= parameter or Frameworks in the process path.

2. Fix regex for install directory: Update the regex pattern to handle unquoted paths with spaces. A pattern like /--install-directory=(.+?)(?=\s+--|$)/ would match from --install-directory= until the next -- parameter or end of line, handling both quoted and unquoted paths.

3. Better error logging: Add more detailed logging to help debug when process detection fails, such as logging the raw process output and which regex matches succeeded/failed.

Code Location

• File: src-backend/lcu/utils/LcuConnector.ts
• Method: static getLCUInfoFromProcess()
• Lines: Approximately 61-109

---

Bug #2: Application Freezing When Game Loads

Description

After successfully detecting the client and starting a match, the application becomes completely unresponsive when the game loads into the match. The UI freezes completely and the application stops responding to any user input. This occurs right when transitioning from the loading screen into the actual game.

Environment

• OS: macOS / Windows (observed on both platforms)
• Application Version: 0.1.0
• Trigger: When the game client finishes loading and transitions into the match (when GameLoadingState transitions to GameRunningState)

Steps to Reproduce

1. Launch League of Legends client
2. Launch TFT Hextech Helper application (ensure client is detected)
3. Start the helper and let it create a lobby and queue for a match
4. Accept the match when found
5. Wait for champion select to complete
6. Game loads into the match
7. Bug occurs: Application UI completely freezes, becomes unresponsive immediately upon game load

Expected Behavior

The application should continue running smoothly, monitoring game stages and executing strategies without any freezing or performance issues. The UI should remain responsive throughout the match.

Actual Behavior

• Application UI becomes completely frozen/unresponsive
• No error messages appear in the console (or errors are not being logged)
• Application appears to hang/freeze completely
• User must force-quit the application to recover
• This happens consistently - it's reproducible every time

Investigation Notes

I've observed that the freeze occurs specifically when the game loads into the match, which corresponds to the transition from GameLoadingState to GameRunningState. Possible causes could include:

1. Blocking operations: Heavy operations like screen capture or OCR processing might be blocking the main thread, causing the UI to freeze.

2. Event listener issues: Multiple event listeners may be registered without proper cleanup, or there could be event listener leaks that cause issues.

3. Promise/async issues: A promise might be hanging indefinitely (e.g., waitForGameToEnd() waiting for an event that never arrives), causing the application to become unresponsive.

4. Resource-intensive operations: Screen capture and OCR operations that start when the game loads might be too resource-intensive and blocking the main thread.

Code Locations That May Need Investigation

Based on when the freeze occurs, these areas might be worth investigating:

• src-backend/states/GameRunningState.ts - The action() method and waitForGameToEnd() promise
• src-backend/services/GameStageMonitor.ts - Screen capture and polling logic that starts when game loads
• src-backend/services/StrategyService.ts - Event subscription logic
• src-backend/tft/recognition/ScreenCapture.ts - Screen capture operations
• src-backend/tft/recognition/OcrService.ts - OCR processing operations

Suggested Fixes

These are suggestions based on the symptoms - you'll know best how to fix them:

1. Make operations non-blocking: Ensure all heavy operations (screen capture, OCR) are properly async/await and not blocking the main thread. Consider using Web Workers for CPU-intensive operations.

2. Add timeouts and error handling: Add timeouts to promises that wait for events (like waitForGameToEnd()), and ensure all operations are wrapped in try-catch blocks to prevent unhandled errors from freezing the app.

3. Improve resource management: Ensure proper cleanup of event listeners and resources when transitioning states. Check for memory leaks.

4. Add logging: Add comprehensive logging around the transition from GameLoadingState to GameRunningState to identify exactly where the freeze occurs.

5. Optimize screen capture/OCR: If screen capture or OCR operations are too resource-intensive, consider optimizing them or reducing their frequency.

---

Additional Context

System Information

• OS: macOS 14.x (Apple Silicon), also observed on Windows 10/11
• Electron Version: 32.2.2 (from package.json)
• Architecture: arm64 (Apple Silicon) / x64

Additional Notes

• Bug Game Detection Failure on macOS and App Freezing During Game Load #1 (macOS detection) completely prevents the app from working on macOS, making it unusable for macOS users.
• Bug 检测不到客户端 #2 (freezing) makes the app unusable after starting a match, even though it works fine up until that point.
• Both bugs are reproducible consistently.

Logs

Unfortunately, I don't have detailed console logs available at the moment, but I can provide them if needed. The main observable symptoms are:

• For Bug Game Detection Failure on macOS and App Freezing During Game Load #1: Repeated "LOL客户端未启动，一秒后将再次检查..." messages in console
• For Bug 检测不到客户端 #2: Application freezes with no error messages appearing

---

Priority

High - Both bugs are critical and prevent the application from functioning:

• Bug Game Detection Failure on macOS and App Freezing During Game Load #1: Prevents all functionality on macOS (affects all macOS users)
• Bug 检测不到客户端 #2: Prevents application from working after match starts (affects all users after they get into a game)

---

Request

Please investigate and fix these issues. They are blocking core functionality of the application. If you need any additional information, logs, or system details, please let me know and I'll be happy to provide them.

Thank you for your time and for developing this helpful tool!

[WJZ-P]

Hi! Thank you so much for this incredibly detailed and well-written bug report! 🎉

I really appreciate you taking the time to investigate the root causes and provide suggested fixes. This is exactly the kind of high-quality feedback that helps open-source projects improve.

🛠️ Fix for Bug #1: macOS Detection

I've implemented a fix for the macOS client detection issue based on your suggestions. Here is a breakdown of the changes in src-backend/lcu/utils/LcuConnector.ts:

1. Fixed Grep Self-Matching & Filtering

I updated the process lookup command to prevent grep from matching itself and to filter out helper processes.

Before:

ps x -o args | grep 'LeagueClientUx'

After:

# Used the [L] bracket trick and added filters for helper processes
ps x -o args | grep '[L]eagueClientUx' | grep -v 'Helper' | grep -v '/Frameworks/'

2. Handling Multiple Process Lines

Since macOS may return multiple processes (even with filters), I added logic to prioritize the main process line containing the port.

const lines = stdout.split('\n').filter(line => line.trim() && line.includes('--app-port='));
// We now explicitly select the line containing the necessary port info
const processLine = lines[0] || stdout;

3. Regex Support for Unquoted Paths (macOS)

This was the critical failure point. I've updated the regex logic to handle both Windows (quoted) and macOS (unquoted, spaces allowed) paths.

// Try Windows format first (quoted path)
let installDirectoryMatch = processLine.match(/--install-directory=(.*?)"/);

// If failed, try macOS format (unquoted, may contain spaces)
if (!installDirectoryMatch) {
    // The new regex matches everything until the next '--' parameter or end of line
    installDirectoryMatch = processLine.match(/--install-directory=(.+?)(?=\s+--|$)/);
}

• Windows: --install-directory="D:\path\to\game"
• macOS: --install-directory=/Applications/League of Legends.app/Contents/LoL --next-param

---

❄️ Regarding Bug #2: App Freezing & Configuration

Thank you for your patience! I have some insights regarding the freezing issue you encountered.

1. The Language Barrier (Most Likely Cause)

I believe the primary reason for the freeze is a Language Mismatch.
The application's core logic relies heavily on OCR (Optical Character Recognition) and Template Matching. Currently, all templates and OCR keywords are strictly calibrated for the Chinese (Simplified) version of the League client and TFT interface.

• If the game is running in English, the app will fail to recognize any text like champion names, which are important for tft.
• This might be causing the "freeze" if the code enters a loop endlessly waiting for a Chinese keyword that never appears.

Suggestion:
To use this tool correctly, the game client must be set to Chinese.

• On Windows, this is usually done by modifying launch arguments.
• On macOS, the method might differ (you might need to check YouTube for "How to change LoL language to Chinese on Mac").

2. Window Occlusion

Please ensure the game window is never covered by other windows. The app performs real-time screen capture. If the game is occluded, the vision logic will fail.

3. Performance Optimization

The performance overhead should be negligible. The automation is designed to force the game into the lowest quality, lowest resolution, and capped at 25 FPS to minimize resource usage.

4. Platform-Specific Behavior (End of Game)

Currently, the app uses a Windows-specific API to close the game client after a match. On macOS, this command will likely fail, meaning the client won't close automatically.

• Impact: This should be minor. When the automation starts the next game, the new login session should automatically disconnect the previous one.

5. Version Stability

The full game loop logic was only recently finalized (just last week!). You might have been testing a version where the state machine wasn't fully stable yet. It should be much more robust in the latest build.

---

👋 A Personal Note

Thank you again for such a detailed issue report! I'm a 21-year-old developer from China 🇨🇳.
Since this is a solo project, having users like you test the software and provide professional feedback is incredibly helpful to me. It really means a lot! ( •̀ ω •́ )y

Please feel free to reach out if you have any more questions!
Thank you again for your contribution! ⭐