perf: move nano particles out of sim frame

[bruno-dasilva]

NOTE: Draft until full testing is complete + screenshots/vids are added.

Context

the nano particles GL4 currently runs a bunch of work in the ::GameFrame callin, which runs during sim frames. This slows down sim particularly during catchup. So the idea is: let's move it out of ::GameFrame and into ::Update.

FYI to readers the way that "frames" work inside engine is at the bottom in the "Addendum" section.

Work done

Two things (in two commits):

1. move the nano particle logic out of GameFrame() callin into Update(). This has a slight change in complexity:
   • since an Update() frame can run after potentially many sim frames (in catch-up), we now need to integrate over multiple sim frames, too instead of just over the existing amortization striding.
2. add an explicit ramping down of particles as the pool saturates to match the old (implicit) ramping

Performance Table (TODO)

time	before	after	diff
0-5min
5-10min
10-20min
20-30min
30-60min

Test steps

For all of the above, check behaviour before/after this change (it should look similar if not identical)

• Look at a large number of nanos after at a bunch of different game speeds
• Look at a large number of nanos while paused
• Run replays of a few games at max speed and see what the performance difference is

See videos:
MASTER
- EARLY GAME: https://drive.google.com/file/d/1yuE9dKRcM_90_Ya9ivxHfH8ttSQWjRLb/view?usp=drive_link
- MID GAME: https://drive.google.com/file/d/1FCWuzqZy43l0xsqxS3lNyecWvnd4ofVc/view?usp=drive_link
- LATE GAME: https://drive.google.com/file/d/13IrT1ibgL3_lrLQPxG6UA56-YxcPVPIb/view?usp=drive_link
THIS BRANCH:
- EARLY GAME: https://drive.google.com/file/d/1QjQyhdOIYiO3W40w_1moubon41VUiMpX/view?usp=drive_link
- MID GAME: https://drive.google.com/file/d/1BlqFTP5NYYWZSDTCk5iajYmQADQSW72r/view?usp=drive_link
- LATE GAME: https://drive.google.com/file/d/1fmyun2z7yYc354sZX5DPqNNY735Isz1H/view?usp=drive_link

Screenshots:

BEFORE:

AFTER:

AI / LLM usage statement:

Claude Code to do the initial POC/implementation, significant cleanup and comments by me.

Addendum - how engine runs frames

The main loop is Update → Draw, repeating. Each iteration produces one draw frame and drains any queued sim frame packets first (0..N sim frames per iteration). CGame::Update (synced) dispatches SimFrame() calls as NETMSG_NEWFRAME packets arrive; CGame::Draw then does an unsynced update phase (CGame::UpdateUnsynced: timings, interpolation, camera, GUI, sound, world-drawer prep) followed by rendering (DrawGenesis → DrawScreenPost). The sim burst is capped at ~500 ms (minDrawFPS) so draw always gets to run. It's all one thread — sim and rendering are not concurrent; parallelism only happens inside a phase.

Conversely, if no sim frames are in the queue the main loop runs Draw/UpdateUnsynced as fast as possible — many draw iterations can pass between successive sim frames, with visuals interpolating smoothly in between via globalRendering->timeOffset.

main-loop iteration  (repeats as fast as possible)
├── CGame::Update            (synced)
│   └── SimFrame × 0..N      ← processes queued sim frames capped at
|                              ~500ms per iteration
└── CGame::Draw              (unsynced)
    ├── UpdateUnsynced       ← unsynced update phase
    └── DrawGenesis → DrawScreenPost  ← render world + screen

Phase	Rate	Synced?	Responsibility
Sim frame — CGame::SimFrame	fixed 30 Hz (GAME_SPEED)	yes	advance deterministic state: units, pathing, projectiles, line-of-sight, scripts, Lua GameFrame
Draw frame — CGame::Draw	variable	no	update phase (see below) + render world/screen
Update phase — CGame::UpdateUnsynced (inside draw frame)	per draw frame	no	timings, interpolation, camera, GUI, sound, world-drawer prep

Benchmark names. fightertest reports these phases as three peer buckets Sim / Update / Render — Sim ≈ CGame::SimFrame, Update ≈ CGame::UpdateUnsynced, Render ≈ DrawGenesis → DrawScreenPost.

[github-actions]

Integration Test Results

16 tests  ±0   8 ✅ ±0   3s ⏱️ ±0s
 1 suites ±0   8 💤 ±0 
 1 files   ±0   0 ❌ ±0 

Results for commit 8b81049. ± Comparison against base commit 2b7b14b.

♻️ This comment has been updated with latest results.

[bruno-dasilva]

So one thing that actually makes this maybe not be as much of an improvement is there was already throttling of work for when speed was > 1. So this pushes a usually-once-per-update to a strictly-one-per-update which limits the upside benefit.