Cursor rule

1---
2description: Universal Game Translator Live project overview and structure
3globs: ["**/*.cs", "**/*.xaml"]
4alwaysApply: false
5---
6 
7# Universal Game Translator Live - Project Guide
8 
9## Overview
10Universal Game Translator Live (UGTLive) is a Windows WPF application that provides real-time screen translation using OCR and Large Language Models (LLMs). The application captures screen regions, performs OCR, and translates text using services like Gemini, ChatGPT, Ollama, Google Translate, or llama.cpp.
11 
12## Project Structure
13 
14### Core Application Files
15- [src/App.xaml](mdc:src/App.xaml) - WPF application entry point
16- [src/MainWindow.xaml.cs](mdc:src/MainWindow.xaml.cs) - Main application window and control logic
17- [src/Logic.cs](mdc:src/Logic.cs) - Core translation and OCR processing logic
18- [src/ConfigManager.cs](mdc:src/ConfigManager.cs) - Settings and configuration management
19 
20### UI Components
21- [src/MonitorWindow.xaml.cs](mdc:src/MonitorWindow.xaml.cs) - Screen capture preview window
22- [src/ChatBoxWindow.xaml.cs](mdc:src/ChatBoxWindow.xaml.cs) - Translation overlay/chat display
23- [src/SettingsWindow.xaml.cs](mdc:src/SettingsWindow.xaml.cs) - Application settings interface
24- [src/ChatBoxOptionsWindow.xaml.cs](mdc:src/ChatBoxOptionsWindow.xaml.cs) - ChatBox customization options
25- [src/ChatBoxSelectorWindow.xaml.cs](mdc:src/ChatBoxSelectorWindow.xaml.cs) - ChatBox region selector
26- [src/LogWindow.xaml.cs](mdc:src/LogWindow.xaml.cs) - Log viewer window
27 
28### Dialog Windows
29- [src/UpdateAvailableDialog.xaml.cs](mdc:src/UpdateAvailableDialog.xaml.cs) - Version update notification
30- [src/TtsVoiceSelectorDialog.xaml.cs](mdc:src/TtsVoiceSelectorDialog.xaml.cs) - TTS voice selection
31- [src/ServiceInstallDialog.xaml.cs](mdc:src/ServiceInstallDialog.xaml.cs) - Python service installation
32- [src/ServiceDiagnosticDialog.xaml.cs](mdc:src/ServiceDiagnosticDialog.xaml.cs) - Service diagnostics
33- [src/ServerSetupDialog.xaml.cs](mdc:src/ServerSetupDialog.xaml.cs) - Server setup wizard
34- [src/OllamaModelSelectorWindow.xaml.cs](mdc:src/OllamaModelSelectorWindow.xaml.cs) - Ollama model selection
35- [src/GoogleVisionSetupDialog.xaml.cs](mdc:src/GoogleVisionSetupDialog.xaml.cs) - Google Vision setup
36- [src/ShutdownDialog.xaml.cs](mdc:src/ShutdownDialog.xaml.cs) - Shutdown confirmation
37- [src/NoTextInfoDialog.xaml.cs](mdc:src/NoTextInfoDialog.xaml.cs) - No text detected notification
38 
39### OCR Services
40- [src/WindowsOCRManager.cs](mdc:src/WindowsOCRManager.cs) - Windows built-in OCR integration
41- [src/GoogleVisionOCRService.cs](mdc:src/GoogleVisionOCRService.cs) - Google Cloud Vision OCR
42- [src/UniversalBlockDetector.cs](mdc:src/UniversalBlockDetector.cs) - Advanced text block detection and grouping
43- [src/PythonServicesManager.cs](mdc:src/PythonServicesManager.cs) - Manages Python OCR services (EasyOCR, MangaOCR, PaddleOCR, DocTR)
44- [src/PythonService.cs](mdc:src/PythonService.cs) - Individual Python service wrapper
45 
46### Translation Services
47- [src/ITranslationService.cs](mdc:src/ITranslationService.cs) - Translation service interface
48- [src/GeminiTranslationService.cs](mdc:src/GeminiTranslationService.cs) - Google Gemini API integration
49- [src/ChatGptTranslationService.cs](mdc:src/ChatGptTranslationService.cs) - OpenAI ChatGPT integration
50- [src/OllamaTranslationService.cs](mdc:src/OllamaTranslationService.cs) - Local Ollama LLM integration
51- [src/GoogleTranslateService.cs](mdc:src/GoogleTranslateService.cs) - Google Translate integration
52- [src/LlamaCppTranslationService.cs](mdc:src/LlamaCppTranslationService.cs) - llama.cpp local translation
53- [src/TranslationServiceFactory.cs](mdc:src/TranslationServiceFactory.cs) - Factory for creating translation services
54 
55### Audio Services
56- [src/GoogleTTSService.cs](mdc:src/GoogleTTSService.cs) - Google Text-to-Speech
57- [src/ElevenLabsService.cs](mdc:src/ElevenLabsService.cs) - ElevenLabs TTS integration
58- [src/OpenAIRealtimeAudioService.cs](mdc:src/OpenAIRealtimeAudioService.cs) - OpenAI real-time audio transcription
59- [src/AudioPlaybackManager.cs](mdc:src/AudioPlaybackManager.cs) - Audio playback management
60- [src/AudioPreloadService.cs](mdc:src/AudioPreloadService.cs) - TTS audio preloading
61 
62### Utilities and Managers
63- [src/HotkeyManager.cs](mdc:src/HotkeyManager.cs) - Global keyboard shortcuts management
64- [src/MouseManager.cs](mdc:src/MouseManager.cs) - Mouse input handling
65- [src/LogManager.cs](mdc:src/LogManager.cs) - Application logging
66- [src/SplashManager.cs](mdc:src/SplashManager.cs) - Splash screen management
67- [src/TextObject.cs](mdc:src/TextObject.cs) - Text region data structure
68- [src/ErrorPopupManager.cs](mdc:src/ErrorPopupManager.cs) - Error popup management
69- [src/GamepadManager.cs](mdc:src/GamepadManager.cs) - Gamepad input management
70- [src/WebViewEnvironmentManager.cs](mdc:src/WebViewEnvironmentManager.cs) - WebView2 environment management
71- [src/WebViewPool.cs](mdc:src/WebViewPool.cs) - WebView2 instance pooling
72- [src/OverlayProfiler.cs](mdc:src/OverlayProfiler.cs) - Overlay performance profiling
73- [src/CondaHelper.cs](mdc:src/CondaHelper.cs) - Conda environment management
74- [src/ServiceConfigParser.cs](mdc:src/ServiceConfigParser.cs) - Python service config parsing
75- [src/ServiceItemViewModel.cs](mdc:src/ServiceItemViewModel.cs) - Service UI view model
76- [src/OllamaModelDownloader.cs](mdc:src/OllamaModelDownloader.cs) - Ollama model download management
77- [src/HotkeyEntry.cs](mdc:src/HotkeyEntry.cs) - Hotkey entry data structure
78- [src/TranslationEventArgs.cs](mdc:src/TranslationEventArgs.cs) - Translation event arguments
79 
80### Python Services
81- `app/services/EasyOCR/` - EasyOCR Python service
82- `app/services/MangaOCR/` - MangaOCR Python service
83- `app/services/PaddleOCR/` - PaddleOCR Python service
84- `app/services/DocTR/` - DocTR Python service
85- `app/services/shared/` - Shared Python utilities
86- `app/services/util/` - Python installation utilities
87 
88Each Python service directory contains:
89- `server.py` - FastAPI server implementation
90- `service_config.txt` - Service configuration
91- `Install.bat` - Installation script
92- `RunServer.bat` - Server launch script
93- `DiagnosticTest.bat` - Diagnostic test script
94- `Uninstall.bat` - Uninstallation script
95 
96## Key Architectural Patterns
97 
98### Singleton Pattern
99The application uses singleton pattern for core managers:
100- `Logic.Instance` - Main application logic
101- `ConfigManager.Instance` - Configuration management
102- `UniversalBlockDetector.Instance` - Text block detection (replaces BlockDetectionManager)
103- `LogManager.Instance` - Logging
104- `HotkeyManager.Instance` - Keyboard shortcuts (replaces KeyboardShortcuts)
105- `PythonServicesManager.Instance` - Python OCR service management
106- `AudioPlaybackManager.Instance` - Audio playback
107- `AudioPreloadService.Instance` - Audio preloading
108- `GamepadManager.Instance` - Gamepad input
109 
110### Window Management
111Each window inherits from WPF Window class and follows these patterns:
112- Windows are typically created once and shown/hidden as needed
113- Settings are persisted through ConfigManager
114- Windows communicate through events and direct method calls on Logic.Instance
115 
116### Translation Flow
1171. Screen capture → OCR (Windows OCR, EasyOCR, MangaOCR, PaddleOCR, DocTR, or Google Vision) → Universal Block Detection → Translation Service → Display
1182. Text blocks are grouped by UniversalBlockDetector
1193. Translation includes context from previous translations
1204. Results are displayed in ChatBox or as overlay
121 
122## Development Guidelines
123 
124### Code Style
125- **Naming**: PascalCase for public members, camelCase for private, underscore prefix for fields
126- **Layout**: 4-space indentation, Allman braces, System namespaces first
127- **Properties**: Use GetVariableName/SetVariableName pattern in ConfigManager
128- **UI Properties**: Direct Get/Set to GUI elements when possible
129- **Error Handling**: Avoid try/catch blocks, check for null, log errors via LogManager
130 
131### Project Configuration
132- **Framework**: .NET 8.0 Windows
133- **Output**: `app/` directory
134- **Assembly**: `ugtlive.exe` (or `ugtlive_debug.exe` in Debug)
135- **Dependencies**: NAudio, Microsoft.Windows.CsWinRT, WebView2
136 
137### Key Features
138- Multiple OCR backends (Windows OCR, EasyOCR, MangaOCR, PaddleOCR, DocTR, Google Vision)
139- Multiple translation services (Gemini, ChatGPT, Ollama, Google Translate, llama.cpp)
140- Real-time screen capture and translation
141- Customizable overlay windows
142- Audio transcription and TTS
143- Context-aware translations
144- Global keyboard shortcuts (via HotkeyManager)
145- Gamepad support
146- Python service management UI
147 
148## Common Development Tasks
149 
150### Adding a New Translation Service
1511. Create a new class implementing `ITranslationService`
1522. Add service configuration to `ConfigManager`
1533. Update `TranslationServiceFactory` to create instances
1544. Add UI controls in `SettingsWindow.xaml`
155 
156### Adding New Settings
1571. Add property to `ConfigManager` with getter/setter
1582. Add UI controls to `SettingsWindow.xaml`
1593. Wire up events in `SettingsWindow.xaml.cs`
1604. Settings are automatically persisted
161 
162### Adding a New Python OCR Service
1631. Create service directory in `app/services/` (e.g., `app/services/NewOCR/`)
1642. Create `service_config.txt` with required fields
1653. Create `server.py` implementing FastAPI endpoints
1664. Create batch scripts: `Install.bat`, `RunServer.bat`, `DiagnosticTest.bat`, `Uninstall.bat`
1675. Service will be automatically discovered by `PythonServicesManager`
168 
169### Debugging OCR Issues
1701. Check `LogManager` output for errors
1712. Use Monitor window to preview capture area
1723. Verify Python server is running (for Python OCR services)
1734. Check service diagnostics dialog
1745. Review UniversalBlockDetector settings
175 
176## Version Management
177 
178When incrementing the version number, you must update it in **THREE places**:
179 
1801. **[src/SplashManager.cs](mdc:src/SplashManager.cs)** - `CurrentVersion` constant
181```csharp
182   public const double CurrentVersion = 0.60;  // Update this value
183```
184 
1852. **[media/latest_version_checker.json](mdc:media/latest_version_checker.json)** - `latest_version` field
186```json
187   {
188       "name":"Universal Game Translator Live",
189       "latest_version":0.60,  // Update this value
190       "message":"Download V{VERSION_STRING} now from rtsoft.com?\n\nV0.60: "  // Update version in message
191   }
192```
193 
1943. **[README.md](mdc:README.md)** - Version badge and history entry
195   - Update the version badge: `[![Version](https://img.shields.io/badge/version-0.60-blue.svg)]`
196   - Add a new history entry at the top: `**V0.60** - [description]`
197 
198### Version Increment Rules
199- Default increment: **0.01** (e.g., 0.25 → 0.26)
200- Major features: **0.10** (e.g., 0.25 → 0.35)
201- Complete rewrites: **1.00** (e.g., 0.99 → 1.00)
202- **ALWAYS update all three files** to keep them in sync
203- Version format is a double/float (e.g., 0.60, not "0.60")
204 
205## Important Notes
206- Application is Windows-only due to WPF and Windows OCR dependencies
207- Python OCR services run locally on configurable ports
208- First run downloads OCR language models
209- Settings stored in `app/` directory (config.txt, service configs)
210- All web calls are for version checking and API services only
211