gmod-rs/docs/DIARY.md

# Дневник агента: где я и что дальше

Живой документ. Обновляю по ходу работы, чтобы после автоматического
уплотнения контекста ничего не терялось. Коротко: состояние, замеры, следующий
шаг, грабли.

Обновлён: 2026-10-23, день.

---

## 1. Что просит пользователь (приоритеты)

**Ускоренный путь до Sandbox-UX** (его слова): «быстрее дойти до того, как смогу
спавнить через Q-меню, иметь норм модель игрока, таскать физганом, Weapon всё
сделать». Поэтому очередь переставлена (docs/PARITY.md A25):

1. A23 оружие (SWEP из Lua + вьюмодель + аттачменты) — сюда же A20 (модель
   игрока: один и тот же рендер моделей).
2. A21 физика взаимодействия: физган (луч → проп → таскание, вращение,
   заморозка), без полной гибернации.
3. A24 спавн: сначала консольные команды на данных из Lua (`gm_spawn`,
   `gm_give`, режимы `gmod_tool`), потом окно Q.
4. A22 Sandbox целиком: undo/cleanup/duplicator.
5. Визуальная точность (A10 свет на пиксель, A11–A12 вода, A16 трава/декали,
   A18 скайбокс) — параллельно, Sandbox не блокирует.

## 2. Где я сейчас (в работе)

**A20/A23, первый срез сделан: модель игрока в мире.** Рендер тот же, что у
пропов (статический меш `PropMesh`), скелет и анимации — следующий срез.

Как включается и как проверять:

```bash
SOURCE_RS_PLAYER_MODEL= DISPLAY=:99 SDL_VIDEODRIVER=x11 cargo run -q -p client -- \
  map --assets ~/gmod_server/server gm_construct --hidden --frames 4 --noclip \
  --player-pos="-2438 -966 48" --flythrough /tmp/opencode/pl4 --flythrough-frames 4 \
  --route="-2438 -880 75|6 270; -2438 -1180 75|6 90"
```

Пустое значение — модель по умолчанию (`models/player/police.mdl`), иначе —
путь к модели. Курс разворачивается на 180° (у моделей Source ось Y влево).

Движок: `World::spawn_model_instance` и `World::move_model_instance`,
`ModelInstance` (экземпляр без сущности). Грабли: индексы модели **локальные** —
при вставке в общий буфер к ним обязательно прибавляется `first_vertex`
(без этого был мусор в кадре).

**Спавн пропа из игры сделан (ядро A24).** `World::spawn_prop` (геометрия из
`append_model_geometry`, сущность `prop_physics`, тело в физике, экземпляр
пропа) + в клиенте клавиша `G` (спавн по взгляду) и аргумент
`--spawn <модель>` (отладка и скрипты). Проверено кадром: арбуз заспавнен и
отрисован (`--spawn models/props_junk/watermelon01.mdl`, камера у
`-2500 -1050 60|5 0`).

Грабли: буферы рендера созданы на сборке мира — после спавна рендерер
пересобирается целиком (медленно, но работает); позже нужна до-аллокация
вершин под спавн.

**Физган, первый срез (A21/A23).** ЛКМ — взять ближайшее тело под прицелом
(луч из глаз, расстояние 8..260 юнитов, допуск 40 в стороны), пока держим —
тело каждый кадр телепортируется на луч взгляда на взятом расстоянии; отпустил —
свободно. `SOURCE_RS_PHYSGUN=1` держит ближайшее тело без мыши (для скриптов).

**Нужна интерактивная проверка физгана:** мои скриптовые кадры упираются в
стены — камеру без глаз не навести. Проверять так: встать у кучи пропов
(она в районе `-2930 -1370 -64`), посмотреть на проп, зажать ЛКМ.

**Синхронизация физики и картинки (жалоба «позиция рендера обновляется
только при спавне нового»).** Причина найдена: мир двигал вершины в памяти, а
буфер рендера заливался один раз при сборке — потому спавн (пересборка
рендерера) и «лечил». Сделано: `World::moved_ranges` + `take_moved_ranges()`
(диапазоны заполняет `rewrite_instance`), `WorldRenderer::upload_vertex_ranges`
(точечная заливка `queue.write_buffer`) и вызов в кадре клиента.

**Не сходится (диагностика `probe_moving_prop_reports_vertex_ranges`):**
коробка в тесте задана в мировых координатах, а меш обязан быть в локальных —
видно по двойному смещению вершины; плюс список диапазонов почему-то пуст после
`step_physics` (проверить `is_sleeping` и ранний выход по совпадению позы —
вероятно, тело «спит» после телепорта). Проверять в интерактиве: заспавнить
арбуз, посмотреть, что он падает на экране.

**Найдены и закрыты две поломки по жалобе «физика висит на экране»:**

1. `move_prop` остался со своей копией перезаписи вершин и не запоминал
диапазоны — теперь он идёт через `rewrite_instance` (замер: было «диапазонов 0»
каждый шаг, стало «диапазонов 1 [(39585, 8)]»).
2. Буфер вершин мира создавался **без `COPY_DST`** — заливка падала с ошибкой
wgpu (у пользователя это роняло клиент). Теперь `VERTEX | COPY_DST`, для
индексов `INDEX | COPY_DST` плюс `upload_index_ranges`.

Плюс `WorldRenderer::refresh_batches`: рендерер копировал список батчей при
сборке, поэтому **новая** геометрия (спавн) в кадр не попадала без полной
пересборки. Теперь список обновляется, когда появились новые индексы, а полная
пересборка нужна только при новой текстуре.

**Открытый вопрос: вьюмодель.** Создание работает (модель в буфере, вершины
+1000, батч есть, габарит ±15), но в кадре её нет — при этом модель игрока
рисуется. Разница в том, что модель игрока в том тесте не двигалась (кадры
пролёта), а вьюмодель обязана двигаться каждый кадр. Значит сломано именно
звено «перенос позы каждый кадр + заливка на GPU». Включается
`SOURCE_RS_VIEW_MODEL` (по умолчанию физган, есть откат на монтировку —
`v_physgun.mdl` в ассетах не нашёлся, грузится `v_crowbar.mdl`).

**Вьюмодель: СДЕЛАНО (первый срез).** Механизм проверен кадром: пистолет
(`SOURCE_RS_VIEW_MODEL=models/weapons/v_pistol.mdl`) стоит в кадре. Две причины,
почему раньше не рисовалась: (1) разворот на 180° уводил ствол за камеру —
у моделей оружия Source геометрия вынесена вперёд по оси модели; (2) у моделей
оружия геометрия смещена от начала координат (у пистолета центр габарита
`≈(0,0,47)`, у монтировки `−52` по Y), поэтому привязываться надо к **центру
габарита** модели (`engine::model::rotate_model_vector(centre, ...)`), а не к её
origin. Посадка: глаз + 20 вперёд + 6 вправо − 10 вниз − центр.

Что осталось по вьюмодели: `v_physgun.mdl` в ассетах нет (GMod-модель), поэтому
по умолчанию пистолет; отдельный FOV вьюмодели и анимации — позже.

**Старые факты (сохранены):** Материал вьюмодели в мире —
индекс 54, имя `crowbar_cyl` (виден в `--debug-materials`). Рендер одним этим
материалом (`--only-material 54`) даёт **пустой кадр** — то есть дело не в позе:
батч вьюмодели не доходит до отрисовки. Проверять по порядку: (1) попал ли батч
в `renderer.batches` после `refresh_batches` (он копирует список только когда
`moved_index_ranges` непуст, а они забираются в блоке физики — возможно,
диапазоны берутся ДО того, как `refresh_batches` увидит их); (2) совпадает ли
`batch.material` с позицией материала в `world.materials` (дедупликация по
имени); (3) `--only-material` фильтрует батчи, но не мешает ли ему что-то ещё.

**2026-10-23, сессия по жалобам пользователя.** Закрыто коммитом `f58eafe`:

- падение wgpu на втором спавне («Copy at offset … overrunning the bounds»):
  буферы GPU не росли — добавлены `ensure_capacity` (рост вдвое с перезаливкой)
  и `refresh_materials` (bind group для новых материалов, иначе новые батчи
  молча не рисовались);
- вьюмодель: обновляется после `player.update` и `camera.pos` (раньше
  отставала на кадр — «плывёт при повороте»), по умолчанию `w_pistol.mdl`,
  курс −90° (у модели ствол вдоль +Y, а не +X), дистанция 26, анимация `idle01`;
- `bone_world_transforms` обходит кости рекурсивно (порядок в файле не
  гарантирован);
- HUD: отладочные строки (verts/tris, лог Lua) скрыты по умолчанию, клавиша `.

**Коллизия пропов (2026-10-23).** Коллайдер-коробка ставилась от **нуля
модели**, хотя геометрия часто смещена (у куклы центр AABB на 13,5 юнита выше
нуля) — пропы висели на невидимых выступах. Добавлен
`Physics::add_prop_offset` (смещение коллайдера в координатах модели,
поворачивается вместе с телом), оба места создания тел (пропы карты и спавн)
передают `bounds_center`. Коробки пропов для коллизии игрока теперь тоже
учитывают центр и поворот (`World::prop_collision_boxes`, AABB описанной
коробки по модулю матрицы поворота).

Замер: тест `real_map_props_rest_on_ground` — после 10 с физики низ коробки
каждого пропа лежит на опоре (допуск 4 юнита, луч от центра вниз); кукла
остаётся с зазором 10 юнитов, потому что лежит краем на столе — центровой луч
опору не видит.

**Известная проблема:** `v_pistol.mdl` рисуется плоским «листом» (2157 вершин,
2 меша, 1 материал, скиннинг при этом цел — тест `real_view_model_skin_stays_coherent`
даёт максимальный сдвиг 4 юнита). Похоже на проблему загрузки геометрии именно
этой модели; до выяснения по умолчанию стоит `w_pistol.mdl`.

**Запущены параллельно (воркдеревья от `f58eafe`):** `feat/android` — APK под
Android 12+; `feat/hdr` — HDR, тонмаппинг, bloom и мягкие тени/свет; `feat/anim` —
RAWROT/RAWPOS/RAWROT2, выбор анимации по состоянию (идёт/бежит/приседает/
прыжок), покачивание вьюмодели.

**A26, состояние на 2026-10-17:** сделаны секвенции (с определением шага записи
по данным), кости и веса вершин, слияние включённых моделей (у игрока 465
секвенций), чтение `.ani` (7,1 МБ, 1563 анимации, 247 блоков), декодер кадров
(`mstudioanim_t`, проверен: 280 кадров, 51 дорожка), сборка кватерниона с
нормировкой 1/32768 (выбрана замером: умножение на rot_scale давало 1,63 —
для кватерниона невозможно) и CPU-скиннинг (виден кадром).

**Следующий шаг — проигрывание.** План, чтобы не искать заново:
1. `PropMesh` (или `ModelInstance`) должен держать **данные анимации**:
   `.ani` (7 МБ) + список блоков + описания анимаций, ссылкой `Arc`, — сейчас
   они читаются при загрузке модели и выбрасываются;
2. в движке `pose_model_instance(index, origin, angles, bone_quats: &[[f32;4]])`:
   локальные кватернионы костей в мировые через родителей
   (`world[i] = world[parent] · (T(pos_i) · R(q_i) · T(−pos_i))`), затем скиннинг
   теми же весами (функция скиннинга уже есть — сейчас её ведёт синус);
3. в клиенте: выбрать секвенцию (`@idle_all_01` через последовательность
   activity), взять кадр по времени (`t · fps`, циклом), собрать кватернионы
   костей из дорожек и позвать `pose_model_instance`;
4. затем выбор по состоянию (`ACT_MP_*`) и блендинг, и снять синус.

**A26 «анимации» — план записан** (docs/PARITY.md A26). Ключевое открытие: в
`formats` скелет и веса **уже читаются** (`mdl.bones()`, `vvd.vertices()`,
`vtx.body_parts()`), не хватает разбора секвенций/`.ani`, костей в
`ModelVertex` и CPU-скиннинга. Заливка вершин на GPU для этого уже готова —
тот же путь `moved_ranges`, что у движущихся пропов.

**A26, сделано 2026-10-23 (этот заход):** постоянные дорожки
`RAWROT`/`RAWROT2`/`RAWPOS` разобраны по `compressed_vector.h` (Quaternion48 6
байт, Quaternion64 8, Vector48 — три half-float). Замеры: `v_pistol @idle01` —
10 дорожек, 7 RAWROT + 2 RAWPOS; `m_anm @taunt_muscle_base` — 53 дорожки, 24
RAWROT2, кватернионы единичные, неизвестных флагов нет. `@taunt` теперь
двигает 3145 из 3147 вершин между кадрами 0 и 30.

Выбор анимации по состоянию — `engine::animation`: `idle_all_01`, `a_WalkN`,
`a_RunN`, `@cidle_all`, `a_CwalkN`, `@jump_fist` (первая существующая), восемь
направлений относительно взгляда. Фаза walk↔run сохраняется, смена типа —
сброс. Клиент играет выбранное имя; вьюмодель качается при ходьбе и отстаёт
при повороте, ЛКМ без захвата проигрывает `fire`. Проверки:
`real_animation_raw_flags_decode`, `real_player_taunt_moves_vertices_with_raw_tracks`,
юнит-тесты `engine::animation`.

**Следующее:** (а) до-аллокация вершин под спавн вместо пересборки рендерера;
(б) блендинг анимаций игрока и вьюмодели; (в) вращение пропа колесом и
заморозка у физгана; (г) оружие в руках связывает `@idle_*`/`@jump_*` и
вьюмодель; (д) консольные команды спавна на данных из Lua (`gm_spawn`).

## 3. Что уже сделано и лежит в `main`

Последние коммиты (свежие сверху):

- `4ad0405` очередь: A23 оружие, A24 Q-меню, A25 ускоренный порядок;
- `7a8a750` очередь: A20 модель игрока, A21 полная физика, A22 Sandbox через GLua;
- `257ac07`, `d35efef` **A13 туман сделан** целиком (чтение + шейдер);
- `72bad60` A19: подшаг не гасит скорость о склон (35°: 65 → 147);
- `5bdbdbf`, `e638607` A19: замер по углам + найден `flRedirectCoeff` в движке;
- `3bfd078`, `d88988f` рельеф: треугольники отсекают шаг, нормаль наружу (стены
  по рёбрам полигонов ушли);
- `b74824b` склон: догон земли трассировкой (рампы 242–250 вместо 197,8);
- `23c5034` присед: 250/150/520/216,7 по спеке, камера 46 → 28 (была выше
  хитбокса);
- `aa11713`, `d220b5a` рампы и стыки: отсечение по последней входной грани,
  касание ребром не преграда;
- `86a6cb6`, `5380184` инструменты: слой коллизий, дамп кирпича, обход карты.

Все 23 сьюта и 28 картовых тестов зелёные.

## 4. Замеры, которые нельзя потерять

- **A19 (скорость на склоне)**: замер `probe_slope_angles` (синтетический клин).
  Было: 5° 239, 10° 232, 15° 196, 20° 152, 25° 116, 30° 88, 35° **65**, 40° 49,
  44° 39. Стало: 239 / 233 / 226 / 214 / 195 / 175 / **147** / 132 / 107.
  Цель — 250 до 44°. Остаток теряется на прямом (скользящем) пути: иногда он
  выигрывает выбор у подшага. Инструмент: `SOURCE_RS_TRACE_STEP=1` печатает,
  какой путь победил (`step_move`).
- **Механизм движка для скорости на склоне**: `gamemovement.cpp`, `ClipVelocity`
  (строка ~3144) — блок `flRedirectCoeff`: `out *= (len + |v·n|·coeff)/len`.
  Наивный перенос копит бонус за кадр (15° → 442 юнита/с) — откачен.
- **Туман карты gm_construct**: цвет (0,557 0,643 0,698), start 1024, end
  250000, max_density 1,0, farz −1 (дальний, на ближних дистанциях нейтрален).
- **Габариты/линейки Source**: тело 72/36 (стоя/присед), глаза 64/28
  (`VEC_VIEW`/`VEC_DUCK_VIEW`), `sv_walkable_normal` 0,7 (45,6°), `DIST_EPSILON`
  1/32, `sv_stepsize` 18, воздушный потолок желаемой скорости 30.
- **Коллизия gm_construct**: 2118 кирпичей; 140 за габаритами карты (3D-скайбокс,
  часть с несогласованными плоскостями — см. E19.2); 11776 треугольника рельефа,
  у всех намотка «гео внутрь» (нормаль разворачиваем в `clip_triangle`).
- **Присед**: обрезка `HandleDuckingSpeedCrop` = 0.33333333 только в приседе и
  на земле, желаемая скорость 450 (бег 650), максимум 250 / 520.

## 5. Инструменты диагностики (не переизобретать)

- `SOURCE_RS_DEBUG_COLLISION=<радиус>` — слой коллизий: красные рёбра кирпичей,
  жёлтые габариты, голубой рельеф, зелёное тело.
- `probe_brush_dump` (`SOURCE_RS_TEST_BSP_AT="x,y,z,радиус"`) — полный дамп
  кирпича: содержимое с расшифровкой, владелец-сущность, каждая грань с
  текстурой, габарит, попадание в коллизию.
- `probe_ramp_movement` — движение из точки: 8 направлений, рывки, залипания,
  кто мешает (кирпич + текстуры).
- `probe_slanted_surface` — лучи по наклонным кирпичам против настоящей формы.
- `probe_slope_angles` — таблица скорости по углам (приёмка A19).
- `probe_phantom_walls_scan`, `probe_collision_contents` — обход карты и состав
  коллизии.
- `real_map_*` — 28 картовых тестов, требуют `SOURCE_RS_TEST_BSP`.
- Запуск клиента: `DISPLAY=:99 SDL_VIDEODRIVER=x11 cargo run -q -p client --
  map --assets ~/gmod_server/server gm_construct ...`, для кадров нужен
  `--flythrough <dir>`.

## 6. Грабли (уже наступал)

- `Vec3` без `Index`: писать покомпонентно.
- `%[fx:mean*255]` в ImageMagick без имени канала врёт — считать
  `mean.r/g/b`.
- Тесты с картой имеют свой `VirtualFs::new()` (189 материалов) — индексы
  материалов не как в рантайме (54).
- Правки кода делать `edit`, не sed/python, кроме больших перестановок блоков —
  и после каждой проверять `cargo clippy` и тесты.
- Перед коммитом всегда: `cargo fmt --all && cargo clippy --workspace
  --all-targets -- -D warnings && cargo test --workspace` + картовые тесты.