# 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 применяется к обоим путям одинаково.