Files
airdef/docs/measurements/issue-147-instancing/README.md
T
chexit c08b737296
build / mod (push) Failing after 32s
Reproducible raid/replay render bench and #147 instancing measurements
tools/raid_bench.py (+ tests): the #147 step-0 driver replaces the #126
scratch script. One battle at fixed ticks (waves inside resident terrain —
far waves stall at the unknown-chunk edge and no fight happens), fingerprint
chat lines at control ticks, then the raid's own recording replayed. Both
render paths are benched on the SAME recording in ONE process via the
engine's diagnostic `model-instancing off|on` toggle (cross-process battles
diverge in event timing: 16 vs 32 kills at one control tick), pairs in
alternating order; idle cold/warm, mid-battle window, reload (F3+T), replay
seek, away-camera checks, and static off/on stills for pixel parity
(hd_bench motion-mask methodology). report.json carries gitlinks, device,
mod_models counters, CPU/GPU p50/p95/p99/max, raw frame times, >25/33 ms
frame counts, guest fuel and streaming queues.

Engine gitlink: one mass mod-model group GPU-instanced (retained mesh per
pack generation, current/previous pose/id/light instance stream shared by
main, motion and shadow passes, per-vertex fallback to parity, runtime
diagnostic toggle, stats raw + guest fuel reporting).

Measurements: docs/measurements/issue-147-instancing/ (M5/Metal, 2560x1440;
RTX 3060 pending). docs/REPO-MAP.md and docs/ENGINE.md pin updated.

Co-Authored-By: Kimi Code <noreply@moonshot.ai>
2026-11-21 11:39:43 +03:00

229 lines
19 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Issue #147, шаг 1: GPU-instancing одной массовой группы моделей мода — замеры
> Основа: engine `3428a571b` (instancing #147 поверх `8e711f969` — decode motion
> buffer по history grid #143 и порядок DLSS-кадра #137), AirDef `32748b116`
> (#145/#149). Замеры ниже сняты на этой основе; контракт motion buffer #143
> (current-to-previous в jittered render pixels) instanced-путь наследует без
> изменений — decode исправлен на стороне TAA/TAAU и применяется к обоим путям.
После retained-геометрии #126 (`a861c1ed2`) кадр всё ещё собирал и загружал вершины
каждой модели каждый кадр (~3,1 МБ vertex + ~4,0 МБ motion на кадр в замере #126).
Этот этап убирает поток повторных вершин для **одной массовой группы** одинаковых
моделей: меш группы резолвится против атласа и загружается на GPU один раз на
generation пака, кадр пишет только instance records (current/previous pose, ID, свет),
и один и тот же instance stream рисует main, motion и тени. Остальные модели и весь
кадр при выключенном instancing идут прежним покадровым путём — fallback до паритета
(вершины бит-в-бит, тест `retained_emit_matches_the_per_frame_bake` #126 не менялся).
## Что изменилось (engine)
- `crates/horizon-client/src/model_instance.rs` — `ModelMeshVertex` (40 Б: model-space
pos/normal, atlas UV, material, emission) и `ModelInstance` (80 Б: current/previous
pose+quat, light, id, flags), минимум группы 8 моделей.
- `entity.wgsl` — `vs_model_instance` / `vs_model_instance_motion`: тот же трансформ
(quat о центре единичного куба), квантование нормалей trunc×127 как CPU `as i8`,
упаковка light/emission/glow как `emit_mod_mesh`; motion через previous pose того же
record. Неподвижная модель несёт идентичные pose → нулевая object velocity (#143).
- `gfx.rs` — retained GPU-меши по состояниям (`upload_model_mesh`/`forget_model_meshes`),
instance buffer, 4 пайплайна (HD gbuffer, HD motion, HD тени, classic/main+mod-камеры)
с общим слотом меша и слотом записей; draws во всех пассах, где рисуется entity stream,
включая камеры мода и каскады теней (модели за main camera рисуются там же).
- `game/mod_models.rs` — выбор группы (больше всего моделей одного state, тай-брейк по
меньшему state id), подготовка pose/light на модель (не на вершину), instance records
для группы, прежний CPU-путь для остальных; счётчики `instanced_models/instanced_quads/
instance_bytes/gpu_mesh_builds`; инвалидация GPU-мешей на reload/unload вместе с #126.
- Fallback: `HORIZON_MODEL_INSTANCING=0` (стартовое значение) или runtime-toggle
`model-instancing off|on` (control-команда, диагностика), группа < 8, shader pack
рисует entities, нет renderer — весь кадр прежним путём. История drawn pose общая
для обоих путей, поэтому переключение не размазывает motion.
- Драйвер-поддержка: `stats raw` (сырые frame/cpu/gpu времена), `HORIZON_MOD_FUEL_PROFILE=1`
→ `stats` отдаёт `mod_fuel` (calls/max_used/budget/failures по callback) и `mod_cost_ms`.
## Стенд
- Apple M5 (10 ядер), macOS, Metal. **Ryzen 5600X / RTX 3060 не профилировались** —
приёмка на целевом железе pending (как в #126).
- 2560×1440 offscreen (окно 1280×720 @2x), HD (`/airdef shader hd`), `HORIZON_HD_SCALE=1`,
in-frame, `HORIZON_NO_AUDIO=1`, `HORIZON_SPIKES=0`, `HORIZON_MOD_FUEL_PROFILE=1`.
- Мир `Polygon` (копия `run-home/saves/Polygon`), свежий `HORIZON_HOME` на прогон.
Камера `tp @s 40 76 40 135 25`, `time set 6000`, `advance_time/advance_weather false`,
`weather clear`, creative, HUD скрыт — сцена замера #126.
- Один и тот же `airdef.hmod` во всех окнах (собран один раз, не пересобирался).
- A/B — один бинарник, один процесс, одна запись боя: `model-instancing off`
(fallback, вершины бит-в-бит равны до-правочному пути) против `on` (instancing),
toggle переключается между окнами без перезапуска.
## Драйвер (шаг 0): `tools/raid_bench.py`
Воспроизводимый драйвер вместо scratch-скрипта #126. Один бой по фиксированным тикам
(расписание в `BATTLE_SCHEDULE`: 14 батарей, волны shahed 40/160, kh101 16/180,
mix 24/140), отпечаток боя — строки `airdef stats` на контрольных тиках; затем прогон
**той же записи** (`airdef replay full`): призраки летят по записанным трекам.
**Оба пути замеряются на одной записи в одном процессе.** Драйвер переключает
`model-instancing off|on` (диагностический toggle движка, #147) и проигрывает запись
заново каждым путём: окна `replay_before`/`replay_after` и вторая пара в обратном
порядке (проверка прогрева/очередей). Межпроцессные бои расходятся по таймингу
событий (стриминг/акустика): первый вариант драйвера (A/B двумя прогонами) дал
16 против 32 сбитых на одном контрольном тике и разные записи — такое сравнение
не изолирует рендер, поэтому оставлен только как кросс-проверка (`--compare` двух
отчётов честно показывает несовпадение отпечатков).
Окна: idle_cold 4 с (сразу после загрузки), idle_warm 6 с (после 500 тиков
сходимости LOD), battle 10 с (середина боя, в потоке, чтобы расписание тиков не
плыло), replay 12 с на путь. Проверки: reload (F3+T), seek (стрелки ±5 с в replay),
камера в сторону от боя (тени/чужая камера), статичные кадры off/on после reload
для пиксельного паритета (`--stills`, методика hd_bench: движущиеся пиксели
маскируются по размаху между кадрами одного пути). Отчёт `report.json`: gitlink'и,
устройство, счётчики `mod_models`, CPU/GPU p50/p95/p99/max, сырые frame time,
кадры >25/33 мс, fuel гостей (`HORIZON_MOD_FUEL_PROFILE=1`), очереди стриминга.
Дальности волн — в пределах резидентного террейна (render distance 12 = 192 блока):
на дальностях #126 (700–1400) дроны ждут ответа земли на краю неизвестных чанков
(`sim/terrain.rs`, #61) и бой не состоится — первый прогон драйвера это показал
(8 дронов висят на краю, 0 пусков, запись без событий). В пределах резидентного
террейна бой идёт по тикам детерминированно.
```sh
python3 tools/raid_bench.py --label m5 --out run-home-bench/out/147-m5
python3 tools/raid_bench.py --compare run-home-bench/out/147-m5/report.json
python3 tools/raid_bench.py --stills run-home-bench/out/147-m5
```
## Результаты (M5/Metal, 2560×1440, один процесс, одна запись; основа #137/#143)
Прогон: `report.json` рядом с этим README (сырые frame time включены; рабочий каталог
прогона — `run-home-bench/out/147-m5`, gitignore). Чистый паритет — `static-parity.json`
(прогон `run-home-bench/out/147-static`). Отчёт снят на дереве `8835e5f04` (engine
`3428a571b`); последующие amend'ы коммита меняли только docs/JSON, код драйвера,
мода и движка идентичны финальному коммиту.
Бой на новой основе (#145/#149): 14 батарей, волны на тиках 60/140/220; отпечаток —
43 сбитых к тику 800, 76 к тику 1200, ракеты в воздухе; конец боя тик 1594. Группа
instancing — самая массовая state летящих моделей (~24 одинаковых дроона/кадр из
~113 моделей записи); крупные модели батарей (штучные) остаются на CPU-пути.
### Replay, одна запись, пары off→on (порядок пар чередуется)
| Метрика | before (off) | after (on) | B/A |
|---|---|---|---|
| моделей/кадр | 112.7 | 113.3 | 1.005 |
| instanced/кадр | 0 | 24.6 | — |
| vertex байт/кадр | 1 919 038 | 1 864 573 | 0.972 |
| motion байт/кадр | 2 442 411 | 2 373 093 | 0.972 |
| instance байт/кадр | 0 | 1 969 | — |
| CPU avg, мс | 27.2 | 26.1 | 0.961 |
| CPU p50 / p95 / p99, мс | 26.7 / 41.6 / 46.9 | 24.6 / 44.7 / 50.3 | 0.92 / 1.07 / 1.07 |
| фаза prepare avg, мс | 1.89 | 1.73 | 0.92 |
| фаза render avg, мс | 15.22 | 14.49 | 0.95 |
| frame p95 / p99, мс | 141.7 / 153.5 | 135.2 / 253.6 | 0.95 / 1.65 |
| GPU p95 / p99, мс | 143.8 / 175.7 | 127.3 / 154.6 | 0.89 / 0.88 |
Вторая пара (on→off→on→off): vertex/motion ×0.967, instance 1 909 Б/кадр,
CPU avg 23.1→24.9 (×1.08), p95 ×1.03, p99 ×1.10; prepare 1.72→1.69, render
14.08→14.05; frame/GPU p95 ×1.13/1.24. Кадров в окнах 122–143, моделей/кадр
112.4–113.7 — одна и та же запись.
**Байты — устойчивый выигрыш**: группа ~24 моделей × ~2.3 КБ vertex + ~2.9 КБ motion
≈ 123 КБ/кадр заменены на ~1.9 КБ записей (~65× для группы); суммарный upload кадра
−2.8…3.3% в обеих парах, потому что группа — мелкие летящие модели (24 из 113),
а крупные батарейные остаются на CPU-пути (следующие этапы #147).
**CPU prepare/render — мал, но в ту же сторону в обеих парах** (prepare −8%/−2%,
render −5%/−0.2%). Перцентили CPU/frame в окнах гуляют ±10% между парами: их
доминируют не-рендерные фазы (tick/update/стриминг) и дрейф сессии (окна идут
подряд, первые несут остаточную нагрузку после боя; в до-ребейзном прогоне первая
пара давала CPU p99 ×0.61, вторая ×0.95 — тот же порядок-эффект). На M5 в этой
сцене кадр GPU-bound (~95 мс HD освещение/дым на 1440p), почти все кадры >33 мс;
хвост frame p99 в первой паре хуже (253 мс — одиночный GPU-спайк), во второй
×1.08. Устойчивого улучшения худших кадров на M5 instancing одной группы не даёт —
критерий #147 по худшим кадрам требует GPU-работы (шаги 2–3) и/или CPU-bound
железа (5600X/3060, pending), где снятие prepare должно быть виднее.
### Бой (live, instancing on) и idle
- battle: 131 модель/кадр, 27.5 instanced, vertex 2.08 МБ/кадр, motion 2.64 МБ/кадр,
instance 2.2 КБ/кадр; CPU p95 118 / p99 130 мс (max 1023 — catch-up спайк),
frame p99 131 мс; фазы: render 32.7, update 22.5, tick 15.6 мс.
- idle_cold: CPU p95 22.2 / p99 41.3 мс; idle_warm: p95 16.2 / p99 16.9 мс (моделей нет).
- reload_warm (после F3+T, instancing on): 48 моделей/кадр, 12 instanced,
CPU p95 20.1 / p99 21.9 мс, frame p99 26.8 мс.
### Проверки
- **Reload (F3+T)**: `atlas_scans` 0→1, `mesh_builds` 0→17, `gpu_mesh_builds` 0→1 —
GPU-меши пересозданы против нового атласа, модели рисуются (74 720 за окно после).
- **Seek (стрелки ±5 с в replay)**: модели рисуются до и после (22 863 → 24 771,
instanced 808 → 1 073); переключение пути не размазывает motion (общая история
drawn pose).
- **Камера в сторону от боя**: 27 085 моделей / 1 516 instanced подготовлены, пока
main camera смотрит в другую сторону — тени и чужая камера их рисуют; сам
`replay full` снимает через камеру мода.
- **Fuel гостей** (`HORIZON_MOD_FUEL_PROFILE=1`): tick max_used 12.73M при бюджете
300M, frame 1 927/10M, command 551 395/1G, failures 0.
- **Стриминг/очереди**: после settle `pending_chunks` 0.
### Пиксельный паритет fallback ↔ instancing
Чистый прогон `--static-parity` (`static-parity.json`, рабочий каталог
`run-home-bench/out/147-static`): батареи, без боя,
`HORIZON_HD_TAA=0 HORIZON_HD_WIND=0 HORIZON_HD_CLOUDS=0 HORIZON_HD_VOLFOG=0`
(методика #126), settle 2×500 тиков, `pauseOnLostFocus:false`, по 3 кадра на путь:
- **off ↔ on: 0.0005% статичных пикселей с разницей >20/255** (проверено 93.5% кадра,
~2 пикселя из 3.4 млн), mean abs diff 0.717; движущиеся пиксели (вода, 6.5%)
маскируются по размаху.
- Шум пола: off↔off 0.000% (mean 0.686), on↔on 0.000% (mean 3.135) — паритет на
уровне пола; fallback бит-в-бит равен до-правочному
(`retained_emit_matches_the_per_frame_bake`, #126, не менялся).
- На до-ребейзном прогоне паритет был 0.103% (TAA-история после переключения пути
не сошлась); с #143 (decode по history grid) и выключенным TAA в чистом прогоне —
0.0005%.
### Методика: почему одна запись в одном процессе
Первый вариант драйвера (A/B двумя прогонами, `HORIZON_MODEL_INSTANCING=0` против
включённого) дал расходящиеся бои: 16 против 32 сбитых на контрольном тике 400 —
тайминг событий зависит от стриминга/акустики, записи разные, сравнение не изолирует
рендер. Также волны на дальностях #126 (700–1400) не состоялись: дроны висят на краю
неизвестных чанков (0 пусков). Итог: волны в резидентном террейне, бой один,
оба пути на его записи через runtime-toggle, пары чередуются. Кросс-прогонные
отчёты первого варианта лежат в `run-home-bench/out/147-before|after` (не коммитятся).
## Тесты
```sh
cd horizon
cargo test -p horizon-client --features mods --lib --bins model_instance # 2: раскладки буферов
cargo test -p horizon-client --features mods --bin horizon-client mod_models::tests # 6
cargo test -p horizon-client --features mods --lib entity_shader_validates # WGSL (naga)
python3 tools/test_raid_bench.py # 7: драйвер
```
- `retained_emit_matches_the_per_frame_bake` (#126, не менялся) — fallback путь бит-в-бит.
- `instance_group_picks_the_most_models_deterministically` — выбор группы и тай-брейк.
- `gpu_mesh_vertices_match_the_retained_faces` — GPU-меш = те же грани/UV/материалы.
- `instanced_shader_math_matches_the_cpu_bake` — трансформ шейдера против CPU-матрицы
(f32-округление, <1e-5 относительной ошибки) и квантование нормалей (≤1 шага i8).
- `static_instance_keeps_zero_object_velocity` — неподвижная модель: identical poses,
нулевая object velocity (#143), moved model несёт последний drawn pose.
- `model_instance_attributes_follow_their_structs`, `records_are_tightly_packed_for_the_vertex_layout`
— раскладки буферов против struct offset'ов.
- `entity_shader_validates_with_its_overlay_constants` — WGSL валиден (naga).
На основе #137/#143 также прогнаны: `dlss_submission_orders_consumers_after_ngx`
(#137) — ok; `airdef-core` cargo test — 326+8 passed, 0 failed (8 ignored);
`airdef-mod` cargo test — 113+1+2+5 passed, 0 failed (включая saturation #145 и
smart #149); смок-запуск ребейзнутого бинарника с toggle off/on — ok.
## Ограничения и что дальше
- Замеры только на M5/Metal; 5600X/3060 — pending acceptance.
- GPU-трансформ отличается от CPU в последних ulp f32 (порядок округления), поэтому
паритет instanced-пути — визуальный (пиксельный A/B), не бит-в-бит; бит-в-бит паритет
гарантирован fallback-пути.
- HD smoke (направление B) и worker rewrite не тронуты (шаги 2–3 #147 отдельно).
- Координатный контракт motion buffer #143 (jitter native TAAU) не менялся: instanced
motion пишет тот же контракт (jittered prev_view_proj + camera_delta), что и CPU-путь;
decode по history grid из #143 применяется к обоим путям одинаково.