feat(build): builds leave some CPU threads free and run at low priority, with an opt-in for every thread at full speed #235

Merged
HumanBean merged 1 commit from HumanBean/LongshotLauncher:feat/build-cpu-headroom into main 2026-11-21 19:33:46 +00:00
Owner

Players say their PC is close to unusable while the launcher builds or updates the game: one took five minutes to take a screenshot (#148), and another saw 100% CPU through an update with Build workers on Automatic (#163). Builds now leave some threads free and run at low priority, so the desktop and other programs come first. Anyone who wants the fastest build can still choose every thread.

Fixes #148
Fixes #163

What I found

  • There is one CPU setting, Build workers (step 2, Advanced; LauncherSettings.BuildWorkers, passed as LONGSHOT_JOBS on Windows and --jobs on Linux). Automatic meant "every thread but one" (SystemInfo.AutomaticWorkers). The player in #201 who "lowered the build core count to about 12" was using this setting.
  • #163's "Automatic" is the same setting during an update. An update is a make_game.py run (--update), started exactly like a build. The launcher has no separate copy or update method; its own copying (game files hard-linked through LONGSHOT_ROMFS_FROM, shader caches kept) is file I/O, not CPU work.
  • Leaving threads free is not enough on its own. Several of make_game.py's stages size their pools from os.cpu_count() instead of --jobs: reading the .nup (nx2/chunks.py), discovery and the shader preparation. So the read and copy steps of an update can fill every thread whatever Build workers says. The other fix is low process priority, which covers everything the build starts.

Summary

  • Automatic leaves threads free (SystemInfo.KeptFree). It keeps 1 thread free on 2–4 threads, 2 on 5–8, and a quarter from 9 threads up, so a 16-thread CPU runs 12 compilers (the 5700X3D in #163, and the "about 12" from #201), 24 threads run 18, and a single thread keeps nothing back. A fixed one or two threads is too little headroom on a big CPU. A quarter costs little: threads past the physical cores add less to a build (the forecast already scales by threads^0.85), and the compilers also wait on memory and the disk.
  • Builds run below normal priority (MakeGameRun.Lower, set as soon as make_game.py starts, before it starts any compiler):
    • Windows: BELOW_NORMAL_PRIORITY_CLASS, which the processes it starts inherit.
    • Linux: nice 10 (.NET's BelowNormal), which its processes and threads inherit.
    • On an idle PC this costs nothing, because the build still gets every free cycle. Settings with a number picked also run at low priority. The make_game.py --check run does too.
  • New opt-in: "Every thread, fastest" in the same Build workers dropdown, between Automatic and the numbers. It uses every thread at normal priority. It is saved as BuildWorkers = 0 (LauncherSettings.EveryThread); an older launcher reads 0 as Automatic, so a shared or downgraded settings file is safe.
  • The estimate follows the setting. BuildThreads now goes through SystemInfo.Workers, so the step 2 estimate, BuildProgress and BuildClock use the threads the build will actually run with. On 16 threads it says about 19 min on Automatic and about 16 min on Every thread (screenshots below). The clock still corrects from the measured pace once the build runs.
  • Build log and failure report: the workers line now names the count and priority, e.g. workers automatic (12, low priority).
  • Strings: 3 new English texts, translated into the 12 full catalogs as recent PRs did. scripts/translations.py reports nothing broken.

Testing

  • python -I tests/test_launcher_core.py: 2608 checks passed (Linux, outside the sandbox). New checks:
    • KeptFree, AutomaticWorkers, Workers and LowPriority for each setting and thread count, and the forecast being longer on Automatic than on Every thread (ScreenChecks).
    • A real run at low priority, on Linux: make_game's runner starts sh, which prints its own nice and a child's; both are 10 or more. A run at full speed keeps the test process's own nice (ScreenChecks.RunChecks).
    • MakeGameCommand.For and ForCheck carry LowPriority: on by default, off for a full-speed request (Program.cs).
    • settings.json keeps EveryThread, and a negative value becomes Automatic.
  • LAUNCHER=$PWD python -I ../Tooling/tests/test_release.py: 42 run, 3 fail: test_the_bump, test_the_next_stable, test_check_tag_against_the_published_releases. These 3 fail on unchanged main too, and this PR doesn't touch release code.
  • dotnet build LongshotLauncher.slnx -warnaserror: 0 warnings.
  • Screenshots: new tools/screenshots scenes settings-workers, settings-workers-choices and settings-workers-every, rendered with DOTNET_PROCESSOR_COUNT=16. The pictures are in the first comment.

Not tested:

  • Windows: BELOW_NORMAL inheritance is Windows' documented behaviour, but I couldn't run it here.
  • A full real build or update with the new defaults, timed against main.

🤖 Generated with Claude Code

Players say their PC is close to unusable while the launcher builds or updates the game: one took five minutes to take a screenshot (#148), and another saw 100% CPU through an update with Build workers on Automatic (#163). Builds now leave some threads free and run at low priority, so the desktop and other programs come first. Anyone who wants the fastest build can still choose every thread. Fixes #148 Fixes #163 ## What I found - **There is one CPU setting, Build workers** (step 2, Advanced; `LauncherSettings.BuildWorkers`, passed as `LONGSHOT_JOBS` on Windows and `--jobs` on Linux). Automatic meant "every thread but one" (`SystemInfo.AutomaticWorkers`). The player in #201 who "lowered the build core count to about 12" was using this setting. - **#163's "Automatic" is the same setting during an update.** An update is a make_game.py run (`--update`), started exactly like a build. The launcher has no separate copy or update method; its own copying (game files hard-linked through `LONGSHOT_ROMFS_FROM`, shader caches kept) is file I/O, not CPU work. - **Leaving threads free is not enough on its own.** Several of make_game.py's stages size their pools from `os.cpu_count()` instead of `--jobs`: reading the .nup (`nx2/chunks.py`), discovery and the shader preparation. So the read and copy steps of an update can fill every thread whatever Build workers says. The other fix is low process priority, which covers everything the build starts. ## Summary - **Automatic leaves threads free** (`SystemInfo.KeptFree`). It keeps 1 thread free on 2–4 threads, 2 on 5–8, and a quarter from 9 threads up, so a 16-thread CPU runs 12 compilers (the 5700X3D in #163, and the "about 12" from #201), 24 threads run 18, and a single thread keeps nothing back. A fixed one or two threads is too little headroom on a big CPU. A quarter costs little: threads past the physical cores add less to a build (the forecast already scales by `threads^0.85`), and the compilers also wait on memory and the disk. - **Builds run below normal priority** (`MakeGameRun.Lower`, set as soon as make_game.py starts, before it starts any compiler): - Windows: `BELOW_NORMAL_PRIORITY_CLASS`, which the processes it starts inherit. - Linux: nice 10 (.NET's `BelowNormal`), which its processes and threads inherit. - On an idle PC this costs nothing, because the build still gets every free cycle. Settings with a number picked also run at low priority. The make_game.py `--check` run does too. - **New opt-in: "Every thread, fastest"** in the same Build workers dropdown, between Automatic and the numbers. It uses every thread at normal priority. It is saved as `BuildWorkers = 0` (`LauncherSettings.EveryThread`); an older launcher reads 0 as Automatic, so a shared or downgraded settings file is safe. - **The estimate follows the setting.** `BuildThreads` now goes through `SystemInfo.Workers`, so the step 2 estimate, `BuildProgress` and `BuildClock` use the threads the build will actually run with. On 16 threads it says about 19 min on Automatic and about 16 min on Every thread (screenshots below). The clock still corrects from the measured pace once the build runs. - **Build log and failure report:** the workers line now names the count and priority, e.g. `workers automatic (12, low priority)`. - **Strings:** 3 new English texts, translated into the 12 full catalogs as recent PRs did. `scripts/translations.py` reports nothing broken. ## Testing - `python -I tests/test_launcher_core.py`: **2608 checks passed** (Linux, outside the sandbox). New checks: - `KeptFree`, `AutomaticWorkers`, `Workers` and `LowPriority` for each setting and thread count, and the forecast being longer on Automatic than on Every thread (`ScreenChecks`). - **A real run at low priority, on Linux:** make_game's runner starts `sh`, which prints its own `nice` and a child's; both are 10 or more. A run at full speed keeps the test process's own nice (`ScreenChecks.RunChecks`). - `MakeGameCommand.For` and `ForCheck` carry `LowPriority`: on by default, off for a full-speed request (`Program.cs`). - `settings.json` keeps `EveryThread`, and a negative value becomes Automatic. - `LAUNCHER=$PWD python -I ../Tooling/tests/test_release.py`: 42 run, 3 fail: `test_the_bump`, `test_the_next_stable`, `test_check_tag_against_the_published_releases`. These 3 fail on unchanged main too, and this PR doesn't touch release code. - `dotnet build LongshotLauncher.slnx -warnaserror`: 0 warnings. - Screenshots: new `tools/screenshots` scenes `settings-workers`, `settings-workers-choices` and `settings-workers-every`, rendered with `DOTNET_PROCESSOR_COUNT=16`. The pictures are in the first comment. **Not tested:** - Windows: `BELOW_NORMAL` inheritance is Windows' documented behaviour, but I couldn't run it here. - A full real build or update with the new defaults, timed against main. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
feat(build): builds leave some CPU threads free and run at low priority, with an opt-in for every thread at full speed
All checks were successful
CI / Compile and test (pull_request) Has been skipped
CI / Conventional Commit title (pull_request) Successful in 6s
a3ffaaf722
Build workers' Automatic keeps threads free of compilers (one on 2-4 threads,
two on 5-8, a quarter from 9), and every build and game check runs below
normal priority (Windows BELOW_NORMAL, inherited by the compilers; Linux
nice 10). A new choice, Every thread, fastest, takes all threads at normal
priority. Fixes #148, #163.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Author
Owner

Screenshots from tools/screenshots (the real step 2 view, Windows, rendered as a 16-thread PC with DOTNET_PROCESSOR_COUNT=16).

Automatic (the default): 12 of 16 at once, with 4 threads left free. About 19 min.

settings-workers

The dropdown: Automatic, then Every thread, fastest, then a number.

settings-workers-choices

Every thread, fastest: all 16 at normal priority. About 16 min.

settings-workers-every

Screenshots from `tools/screenshots` (the real step 2 view, Windows, rendered as a 16-thread PC with `DOTNET_PROCESSOR_COUNT=16`). **Automatic (the default):** 12 of 16 at once, with 4 threads left free. About 19 min. ![settings-workers](https://git.magicbean.dev/attachments/419121f3-9833-4ff7-975a-2bafd3d1ec4e) **The dropdown:** Automatic, then Every thread, fastest, then a number. ![settings-workers-choices](https://git.magicbean.dev/attachments/d3275e8d-09f2-4f76-8b39-23611ba51925) **Every thread, fastest:** all 16 at normal priority. About 16 min. ![settings-workers-every](https://git.magicbean.dev/attachments/3dd0735a-6b08-41b1-be9e-22f2b81257c1)
HumanBean force-pushed feat/build-cpu-headroom from a3ffaaf722
All checks were successful
CI / Compile and test (pull_request) Has been skipped
CI / Conventional Commit title (pull_request) Successful in 6s
to 27482159fa
All checks were successful
CI / Compile and test (pull_request) Has been skipped
CI / Conventional Commit title (pull_request) Successful in 14s
2026-11-21 19:18:25 +00:00
Compare
HumanBean deleted branch feat/build-cpu-headroom 2026-11-21 19:33:47 +00:00
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
MagicBeanDev/LongshotLauncher!235
No description provided.