How petyablatnoy/crosshud_by_petyablatnoy-hudsightkiller works
1. Overall shape
- crosshud is a Windows-only desktop app built as two cooperating planes: a QML/PySide6 control UI and a separate Win32 overlay renderer that draws the crosshair above other windows.
2. Entry and process control
- main_file.py is the startup boundary: it handles CLI flags, logging setup, version reporting, and single_instance.py so only one app instance runs at a time.
- app_metadata.py provides version/app identity used across startup and diagnostics.
3. Application orchestrator
- crosshud_app.py is the central controller. It wires together the UI, tray behavior, overlay lifecycle, settings, and runtime toggles like enable/disable and minimize-to-tray behavior.
- This is the main “composition root” for the app.
4. UI boundary
- qml_ui.py is the bridge between Python and QML. It exposes app state/actions to the interface and receives user edits back from QML.
- The visual app lives under qml/, with pages for Aim, Custom, and System, plus reusable controls in qml/components/.
5. Settings and customization model
- settings_manager.py owns the persistent configuration: crosshair shape, color, opacity, point/outline options, pixel-art templates, and dirty/unsaved state.
- It acts as the shared source of truth for both the UI and the renderer, so edits in QML can be applied and saved consistently.
6. Overlay rendering path
- crosshair_renderer.py converts the current settings into an image buffer for the crosshair.
- The readme and tests indicate this renderer outputs into a BGRA buffer, with Pillow as the drawing dependency.
7. Overlay window and display layer
- overlay_window.py encapsulates the Win32 layered window that presents the rendered image on top of the target content.
- overlay_manager.py coordinates the overlay window, rendering updates, visibility changes, and the runtime conditions that determine when the overlay should be shown.
8. Input and hotkey subsystem
- input_hooks.py handles global input hooks such as mouse/right-button behavior, hotkeys, and active-window tracking.
- hotkeys.py appears to define the app’s hotkey bindings/logic, while input_hooks.py is the runtime hook layer that drives enable/disable and hide/show behavior.
9. Windows-specific system boundary
- win32_api.py contains the low-level ctypes-based WinAPI structures and function wrappers used by the overlay, hooks, and window management code.
- resolution_detector.py helps keep the overlay aligned with the current screen/window resolution and layout context.
10. Diagnostics and support data
- diagnostics.py generates system information, user/app identifiers, and zip reports for support.
- This is a separate operational path from rendering: it collects logs and environment data rather than affecting the overlay itself.
11. Build and release pipeline
- build.py, build.bat, installer.nsi, installer_version.nsh, and sign_app.ps1 form the release toolchain.
- The repo targets packaged Windows distribution via PyInstaller and NSIS, with signing steps called out in the readme.
12. Tests and quality boundaries
- tests/ covers the renderer, diagnostics, logging rotation, QML bridge, and settings manager.
- This reflects the main risk areas of the architecture: drawing correctness, state persistence, UI/backend integration, and support tooling.
13. Primary runtime flow
- User changes settings in QML → qml_ui.py passes them to settings_manager.py → overlay_manager.py refreshes the renderer/overlay → crosshair_renderer.py redraws the buffer → overlay_window.py displays the updated overlay.
- Input hooks and hotkeys can interrupt that flow by toggling visibility or enable state at runtime.
14. Key architectural boundary
- The important separation is between configuration/UI state and native overlay rendering. The QML side is for editing and control, while the Win32 side is responsible for always-on-top display and input interception on Windows.
Main entry points: crosshud_app.py App core · Main.qml Main QML · overlay_manager.py Overlay mgr · main_file.py Main
Components 22
Runtime control
Process startup, app composition, settings, and runtime toggles.
- Main · CLI entrypoint, logging, version reporting, and single-instance startup.
main_file.py - App core · Central composition root wiring UI, tray, overlay, settings, and runtime behavior.
crosshud_app.py - Settings · Persistent crosshair configuration and dirty-state management.
settings_manager.py - Single instance · Ensures only one app instance is running.
single_instance.py - Metadata · App version and identity information used at startup and in diagnostics.
app_metadata.py
QML UI
The PySide6/QML interface and reusable visual components.
- QML bridge · Exposes Python state/actions to QML and receives user edits back.
qml_ui.py - Main QML · Top-level QML application shell and navigation.
qml/Main.qml - Aim page · QML page for aim/crosshair-related controls.
qml/pages/AimPage.qml - Custom page · QML page for custom crosshair editing and presets.
qml/pages/CustomPage.qml - System page · QML page for runtime and system controls.
qml/pages/SystemPage.qml - Components · Reusable QML controls shared across pages.
qml/components
Native overlay
Windows overlay rendering, windowing, and input integration.
- Overlay mgr · Coordinates overlay visibility, refresh, and rendering lifecycle.
overlay_manager.py - Renderer · Draws the current crosshair settings into a BGRA buffer.
crosshair_renderer.py - Overlay window · Win32 layered window that displays the rendered crosshair above other windows.
overlay_window.py - Input hooks · Global input hooks, button behavior, and active-window tracking.
input_hooks.py - Hotkeys · Defines hotkey bindings and toggle behavior.
hotkeys.py - WinAPI · Low-level Win32 structures and function wrappers used by overlay and hooks.
win32_api.py - Resolution · Detects screen/window resolution context for overlay alignment.
resolution_detector.py
Operations
Diagnostics, packaging, and release tooling.
- Diagnostics · Collects system data and produces support archives.
diagnostics.py - Build script · PyInstaller-oriented build automation.
build.py - Installer · NSIS installer definition for Windows distribution.
installer.nsi - Sign app · PowerShell signing step for packaged releases.
sign_app.ps1
Connections 26
- Main → Single instance: guards · Startup prevents multiple concurrent instances.
- Main → Metadata: reads · Startup reports version and identity data.
- Main → App core: starts · Entry point creates the application controller.
- App core → QML bridge: binds · Composes the QML bridge with application state.
- App core → Settings: owns · Central controller manages persisted configuration.
- App core → Overlay mgr: drives · Controller coordinates overlay lifecycle and toggles.
- App core → Input hooks: enables · Controller activates global input behavior.
- App core → Diagnostics: exposes · Controller surfaces support/diagnostic actions.
- QML bridge → Main QML: renders · Python bridge backs the top-level QML shell.
- Main QML → Aim page: navigates · Main shell hosts the Aim page.
- Main QML → Custom page: navigates · Main shell hosts the Custom page.
- Main QML → System page: navigates · Main shell hosts the System page.
- Main QML → Components: uses · Pages share reusable QML controls.
- QML bridge → Settings: edits · UI reads and updates the shared settings model.
- Settings → Overlay mgr: feeds · Configuration changes trigger overlay updates.
- Overlay mgr → Renderer: renders via · Manager requests redraws from the renderer.
- Renderer → Overlay window: outputs to · Rendered BGRA buffer is presented by the layered window.
- Overlay mgr → Overlay window: shows · Manager controls overlay visibility and lifecycle.
- Input hooks → Hotkeys: uses · Runtime hooks rely on hotkey definitions and toggles.
- Input hooks → WinAPI: calls · Hook layer uses native Win32 wrappers.
- Overlay window → WinAPI: calls · Overlay window is built on low-level Win32 APIs.
- Overlay mgr → Resolution: consults · Overlay alignment depends on display context.
- Diagnostics → Metadata: includes · Reports app identity alongside system data.
- Build script → Installer: packages for · Build tooling feeds the Windows installer flow.
- Build script → Sign app: releases via · Packaging is followed by signing in release flow.
- Installer → Sign app: depends on · Installer output is signed as part of distribution.