liuxiaogang-com/desktop-icon-billiards

What it does

Desktop Icon Billiards turns the icons on a Windows desktop into the balls of a pool game. A transparent overlay lets you aim with the mouse, hold the left button to charge power, and release to shoot. Icons keep their own thumbnails while they roll, collide and drop into pockets. When you exit, the desktop is restored.

The README describes aiming guides (white for the first leg, blue for the cue ball after contact or cushion, green for the hit icon's direction), collision circles, a timer that starts at the first shot, per-shot statistics, and a result card showing time, icons pocketed and optional global ranking. The number of balls is fixed to 15–45 desktop icons; the game copies icons or selects a subset for play without changing the actual desktop.

It is intended for Windows 10/11 x64 users who want a short desktop play session, and for Python developers who want to inspect or modify the source.

Quick start

The README offers a single-file EXE release as the primary entry point, available from GitHub Releases or a CNB mirror. Download and run it on Windows 10/11 x64; there is no separate installation step. The README also points to an official entry page.

To run from source you need Windows 10/11 x64, an Explorer desktop and Python 3.11+ with Tk. The documented path uses uv:

uv venv --managed-python --python 3.12 .venv
uv pip install --python .\.venv\Scripts\python.exe -r requirements.txt
.\run.cmd

If double-clicking run.cmd opens no window, run .\\.venv\\Scripts\\python.exe -X utf8 app.pyw from PowerShell to see the error. The README notes that Explorer access may require the normal desktop session of the logged-in user, and that a .venv created with the Microsoft Store version of Python may need to be removed and rebuilt.

Controls and ranking

After launch, move the mouse to aim, hold the left button to charge, and release to shoot. Use the in-game toggle to turn aiming guides on or off. Press Esc, click Exit, or use Ctrl+Alt+X to restore the desktop. The hidden-desktop toggle is disabled in 0.1.4 per the README, so Exit or Ctrl+Alt+X are the supported ways to leave the game.

Global ranking is off by default and asks once on first launch. If enabled, each cleared round submits round time, icon count, shot count and an anonymized device identifier derived from a salted local system ID. The README says icon names, screenshots and file information are not uploaded. Ranking requires a network connection; offline play still works but that round is not submitted. Ranking credentials are stored in %APPDATA%\DesktopIconBilliards\rank.json.

Constraints and privacy

The game reads desktop icon thumbnails and layout through the Windows Shell and draws an independent desktop layer; blurred table areas come from the local wallpaper file. The README states that it does not capture the screen or audio. Changing resolution, DPI or monitor layout during a round stops the round and restores the desktop. Desktop icons must be visible, and only one instance can run at a time. Diagnostics are written under %TEMP%\DesktopIconBilliards (diag.log, error.log).

Building the EXE requires PowerShell 7 and uv; pwsh -File build.ps1 produces dist/DesktopIconBilliards-<version>-win-x64.exe with a printed size and SHA-256. Tests run with .\\.venv\\Scripts\\python.exe -m unittest discover -s tests -t . -v. Update behavior is documented separately in UPDATE.md and an example update manifest. The project is MIT licensed (LICENSE).

HotRepo's take

The project appeared in HotRepo's new-project list on 2026-11-12 with 106 stars and 11 forks, and a sampling window of about 1.5 hours showed 5 net new stars. That is a short observation window, so the record supports initial attention but not a trend. The repository has no best all-language daily rank recorded, so HotRepo does not have a ranking position to report.

What stands out technically is the separation between the game overlay and the real desktop: icons are read and rendered without altering the desktop, and a watchdog attempts restoration if the game exits abnormally. The release is distributed as a single Windows EXE while the source is Python, so users who care about the binary-to-source link should build from source, which the README supports with a documented build script and tests.