gmod-rs/docs/RECON.md

Разведка (снято 2026-10-11)

1. Окружение разработки

• OS: Linux x86_64 · CPU: 16 ядер · RAM: 31 ГБ (доступно ~17) · Swap: 8 ГБ
• GPU: NVIDIA RTX 3060 (GA106) → Vulkan через wgpu
• Rust: 1.97.1 (cargo 1.97.1)
• Домашний каталог: /home/niko

2. Каталоги

• ~/garrysmod-rs — корень проекта (на момент разведки пустой; сессия переведена сюда)
• ~/source-rs — пустой, не используется (оставлен как есть)

3. Целевой сервер: ClassicBox

• Адрес: 194.147.90.27:24215
• A2S-инфо (2026-10-11): имя ClassicBox, карта gm_mobenix_v3_final, игра garrysmod, тип Sandbox, 36/46 игроков, Linux DS, VAC=1 (\x01), теги: gm:sandbox gmc:other loc:ru ver:260917
• Вывод для плана: цель по нагрузке — 46–64 живых игрока и типичный сандбокс-набор (пропы, констрейны, PAC3/Starfall у игроков), открытая карта.

4. Локальные ассеты и полигон

• GMod Dedicated Server: ~/gmod_server/server
  • garrysmod/garrysmod_{000,001,002}.vpk (~772 МБ) + fallbacks_*.vpk (~104 МБ)
  • sourceengine/* (hl2_* vpk), platform/*
  • garrysmod/mount.cfg, gameinfo.txt — порядок монтирования и mounts
  • srcds_linux — локальный сервер для автотестов (sv_lan)
  • garrysmod.ver: 260508 prerelease
• Steam-клиент GMod: ~/.local/share/Steam/steamapps/common/GarrysMod — заглушка ~32 КБ (полного клиентского контента нет). Для рендера используем DS-ассеты.
• Workshop: ~/.local/share/Steam/steamapps/workshop/content/4000 — пусто.

5. Инструменты пользователя

• ~/glua-steal (исходники, C++) и ~/gluasteal (рабочий каталог с config.toml) — дампер клиентского/шаренного Lua с серверов, исполнитель Lua, блокировщик файлов. Полезен как:
  • источник тест-корпуса Lua (дампить ClassicBox);
  • источник требований к защите путей при загрузке файлов с сервера. Лицензию glua-steal отдельно проверить перед заимствованием идей (код не копируем).

6. Референс-проекты

Проект	Что даёт	Ограничения
SourceDotNET/Source.NET	Структура Stage-слоёв Source; рабочий сетевой стек и подключение к реальным GMod-серверам; зачатки Lua	C#, GL46, только UnlitGeneric, физика Jitter-враппер, нет анимаций, Source 1 SDK License
Leystryku/leysourceengineclient	Базовый сетевой протокол для внешних клиентов	—
ValveSoftware/source-sdk-2013	Спецификация: net_chan, dt_*, studio, шейдеры, VGUI, предсказание	Лицензия SDK (только для модов Source) — берём как спеку
nillerusr/source-engine	Кроссплатформенный порт: Linux-специфика, шейдерные переводы	SDK-лицензия
wiki.facepunch.com/gmod	Lua API и поведение движка	—
gluasteal	Требования к безопасности загрузки файлов	проверить лицензию

7. Ключевые факты о GMod, влияющие на план

• Клиент исторически 32-битный (есть 64-битная бета) → у нас сразу x86_64.
• Lua: LuaJIT (семантика 5.1).
• PAC3/Starfall — аддоны внутри GMod Lua (Starfall несёт свой интерпретатор) → наша задача = движковый API + sandbox; их логику не переписываем.
• Скачиваемые с сервера файлы: Lua + контент; LZMA-сжатие (уточнить capture'ами в M2).
• Сервер может требовать Steam-тикет (ClassicBox VAC=1) → steamworks-rs с M2, fallback noSteam конваром.
• В DS-установке есть базовые lua-файлы игры — референс порядка bootstrap Lua-рантайма.

8. Лицензии и правовая позиция

• Цель проекта — личный клиент для игры на серверах; ассеты берутся из локальных установок пользователя и не распространяются.
• Source SDK 2013 и Source.NET — Source 1 SDK License: код не копируем, используем как спецификацию форматов и поведения.
• Наш код — собственный (clean-room по форматам/поведению).

9. Тестовый контур

Контур	Использование
Локальный srcds_linux (~/gmod_server/server)	Контролируемые сценарии, синтетика (2000 пропов, 500 констрейнов)
Packet dump/replay	Воспроизведение прод-нагрузки без сервера
ClassicBox (live)	Финальные проверки (36–46 игроков), аккуратно и по делу
Fuzz-стенды	vpk/bsp/mdl/vtf/pcf/сеть — cargo-fuzz

10. Заметки спринта 0 (обновляется по ходу)

• VPK в установке: 9 *_dir.vpk (77 933 записи, 41 архив) — garrysmod (v2, 15 324 записи), fallbacks, hl2_{textures,misc,sound_misc,sound_vo_english}, content_hl2, content_cstrike, platform_misc. CS:S-контент присутствует (важно для gm_mobenix).
• Формат VPK сверен с ValvePak (VRF): терминаторы, preload, встроенные данные, внешние архивы <stem>_NNN.vpk; парсер bounded и fuzz-устойчив.
• fs doctor: 0 ошибок CRC на выборке; fs cat читает MDL (IDST) и текстовые файлы из VPK.
• Клиент: SDL3 (собран из исходников, feature build-from-source) + wgpu 30. Запуск проверен: NVIDIA RTX 3060, Vulkan, ~58–63 FPS (vsync), чистое завершение по --frames.
• wgpu 30: API проверено по примеру sdl3-rs (raw-window-handle-with-wgpu); заголовок окна обновляется через sdl3::sys (метод крейта требует &mut Window).
• BSP v20: структуры dnode_t/dleaf_t на диске выровнены до 32 байт (хвостовой паддинг) — иначе поля читаются как мусор; dnode_t.children — int[2], не short.
• gm_construct: геометрия валидна (14 079 вершин, 9 460 граней, 4 988 узлов), pakfile — ZIP 3.8 МБ, 599 записей (CRC проверен на выборке).
• VTF brickfloor001a.vtf: 7.1, DXT1 512×512, 10 мипов, миниатюра 16×16; раскладка данных совпадает с размером файла до байта; декод мипа 0 и миниатюры — ок.
• По 200 случайных VTF и VMT из VPK разбираются без единой ошибки.
• Полезные открытые референсы форматов (используем как спецификации, не код): vformats (KV/VMT/VTF/PHY/GMA/SND), source-vtf (VTF 7.x), ValvePak (VPK), glua-steal.
• MDL: базовый studiohdr_t = 408 байт (все версии); у v48+ за заголовком лежит studiohdr2_t (256 байт, studiohdr2index=408), данные костей начинаются после него. Смещения полей совпадают у v44–v48 (проверено на 53 моделях: v44 — 47, v45 — 1, v48 — 5, length == размер файла у всех).
• VVD: заголовок 64 байта (IDSV v4), вершина mstudiovertex_t = 48 байт.
• VTX: структуры packed (#pragma pack(1)); смещения вложенных структур отсчитываются от своей структуры, а не от начала файла (только bodyPartOffset — от файла). Проверено: oildrum001 — 270 вершин / 756 индексов / 1 стрип; 51 пара VVD/VTX — checksum совпадает.
• fs inspect для модели показывает кости/аттачменты/текстуры/keyvalues и меш-статистику.
• M3 v0 (рендер мира): gm_construct собирается за ~0.5 с — 6838 браш-граней + 110 displacement, 46 646 вершин, 41 324 треугольника, 47 материалов, 65 МиБ текстур.
• Запечённые VRAD-материалы карты лежат в pakfile BSP как VMT-патчи (maps/<map>/..., include → базовый материал, replace $envmap → кубмапа); pak монтируется как источник файлов VFS. VTFs в pak — кубмапы (.hdr.vtf).
• Материалы без $basetexture (шейдер lightmappedreflective — стекло/вода) в v0 пропускаются как прозрачные, а не красятся заглушкой.
• Скриншоты: на NVIDIA/Vulkan формат поверхности — BGRA; readback обязан менять местами R/B (иначе цвета инвертируются, что однажды уже сбило диагностику).
• Спавн gm_construct — внутри «color room» (большой белой комнаты): для эффектных скриншотов камеру надо выносить наружу (--pos/--angles).
• Скайбокс: небо «painted» — это реально почти равномерная светлая текстура (256×256 DXT5); проверять отрисовку скайбокса надо через смену clear color.
• Скайбокс рисуется на дальней плоскости: clip.z = clip.w * 0.99995 — ровно z=w отбрасывается клиппингом (симптом: скайбокс «не рисуется», видно цвет очистки).
• M2 v0: нумерация net/SVC-сообщений в GMod сдвинута относительно Source 2013 (NET_Tick=3, NET_SignonState=6, SVC_Print=7, SVC_ServerInfo=8); сверено с Source.NET.
• GMod требует в connectionless connect поле ChecksumXOR (зависит от первого байта и длины буфера) — без него сервер молчит.
• ClassicBox (VAC=1) требует Steam-тикет (auth_protocol=3): steamworks-rs Client::init_app(4000) + authentication_session_ticket_with_steam_id; в connect пишется u16(размер+8), u64 steamid, тикет.
• Сервер сравнивает версию клиента: при старой версии — #GameUI_ServerRejectNewVersion; наша версия берётся из A2S-ответа сервера.
• Локальный GMod DS (srcds_linux) в этом окружении виснет после «VAC secure mode disabled» (Steam-инициализация), поэтому живой полигон — ClassicBox. Запуск с -insecure открывает UDP-порт, но сервер не отвечает на A2S (зависает).

11. Netchan GMod (снято 2026-10-12, сверка с трафиком ClassicBox)

• Флаг Challenge = 0x20 (не 0x10, как в Source): при нём после reliable_state идёт u32 challenge; сервер шлёт challenge в каждом пакете.
• Флаг Reliable = 0x01: при нём читается надёжная часть. Проверено: пакет с флагом 0x01, но без надёжной части → сервер отвечает «Buffer overflow in net message».
• Надёжная часть: subchannel u4 (в GMod 16 подканалов, не 8!) → для каждого из 2 потоков (Normal, File) 1 бит «есть данные» → для потока: single block бит (0 = один блок) → compressed бит → varint32(bytes) → данные. Затем ненадёжные сообщения.
• challenge одноразовый: повторный connect со старым challenge → #GameUI_ServerRejectBadChallenge.
• Сервер отвечает 'B' только на повторный connect (второй цикл getchallenge → 'A' → connect); первый connect как будто «регистрирует» клиента (асинхронная проверка Steam).
• Пустой Steam-тикет → #GameUI_ServerRejectSteam (синхронная проверка формата).
• Steam-клиент обязан жить всю сессию (иначе тикет инвалидируется); тикет готов только после события AuthSessionTicketResponse; локальный begin_authentication_session на своём тикете = Ok.
• Нерешённое: после 'B' сервер шлёт challenge-пакеты раз в секунду и через ~1.5 с отключает: NET_Disconnect «Client dropped by server». Кик не зависит от наших пакетов после 'B' (проверено полным бездействием, ack'ами, keepalive 20 Гц, hello с SignOnState/ClientInfo в надёжном и ненадёжном потоках, разными флагами). В engine_srv.so рядом: «Invalid STEAM UserID Ticket» и «After this many seconds without a message from a client, the client is dropped (while connecting)» — похоже на серверную проверку аутентификации или нет-сообщений; формат нашего надёжного потока проверен побайтово против NetChannel_engine.cs и совпадает.

12. Форматы BSP GMod: уточнения (2026-10-12, сверка с gm_construct)

• dleaf_t в GMod = 32 байта (без CompressedLightCube): contents i32, cluster i16, area:9|flags:7 u16, mins i16[3], maxs i16[3], firstleafface u16, numleaffaces u16, firstleafbrush u16, numleafbrushes u16, leafWaterDataID i16, padding. Area маскируется & 0x1FF.
• dface_t = 56 байт: planenum u16, side u8, onNode u8, firstedge i32, numedges i16, texinfo i16, dispinfo i16, surfaceFogVolumeID i16, styles u8[4], lightofs i32, area f32, LightmapTextureMinsInLuxels i32[2], LightmapTextureSizeInLuxels i32[2], origFace i32, numPrims u16, firstPrimID u16, smoothingGroups u32. Отдельных mins/maxs нет.
• Лайтмапа грани: блок (size[0]+1) × (size[1]+1) люкселей, индекс v*width + u. lightofs указывает на блок после styles*4 байт усреднённого цвета (PrecompLightmapOffsets в vrad). Люксель: ColorRGBExp32 → (c/255) * 2^exponent.
• Лайтмапа displacement'а: не проекция мира! Плотная сетка по UV поверхности (CCoreDispInfo::CalcDispSurfCoords(bLightMap=true)): углы блока — (0.5,0.5) … (flU+0.5, flV+0.5), где flU = size[0], flV = size[1]; для вершины сетки (a,b) (индекс a*side+b, a вдоль p0→p1, b вдоль p0→p3): luxel_u = 0.5 + (b/n)*flU, luxel_v = 0.5 + (a/n)*flV. Проекция мира даёт «шахматку» теней на рельефе.
• 3D-скайбокс: движок рендерит по area bits листа sky_camera (CSkyboxView::DrawInternal) + vis от камеры скайбокса. Area листа скайбокса — отдельная (в gm_construct area=1, z≈10 000…15 200; в gm_flatgrass area=2, скайбокс под картой, z≈-15 000). Displacement-грани не попадают в leaf_faces (detail-геометрия) — выбирать грани надо по листу центра грани (+normal*2 и -normal*2), иначе теряется основная плоскость скайбокса. Защита: если «область» накрыла >30 % граней карты — скайбокс не выделяем.
• Порядок отрисовки скайбокса: 2D-скайбокс фоном (depth Always, без записи), затем 3D-меш (depth Always, без записи), затем мир (LessEqual, пишет depth) — стены карты всегда перекрывают скайбокс; иначе дальние стены (depth > 0.9999) оказываются позади сжатой глубины скайбокса.
• Вода: SURF_WARP (0x8) + VMT шейдера Water ($abovewater 1 — поверхность, 0 — изнанка; $fogcolor "{24 64 72}"). Две грани на один браш воды (поверхность/изнанка) — рисуем полупрозрачно с френелем и отбрасываем изнанку по нормали.
• SURF_NOLIGHT-грани (вода, COLOR_ROOM и пр., lightofs = -1): движок рисует их с белой лайтмапой (полная яркость); ambient-куб листа в GMod (LEAF_AMBIENT_INDEX/LIGHTING, запись 28 байт) почти чёрный — использовать его нельзя.

13. Хендшейк Steam-подключения (2026-10-12, эксперименты с живыми серверами)

Ключевая находка: тикет Steam нужно запрашивать с идентичностью игрового сервера. Современный Steamworks (GetAuthSessionTicket с SteamNetworkingIdentity) требует SteamID сервера; «generic»-тикет (пустая идентичность, как в старом движке SteamUser()->GetAuthSessionTicket без identity) сервер отклоняет синхронно: #GameUI_ServerRejectSteam. Работает: NetworkingIdentity::new_steam_id(game_server_steam_id).

• Ответ challenge ('A', auth_protocol=3) содержит: magic u32, challenge u32, my_challenge u32, auth_protocol u32, keysize u16 (=0), game_server_steam_id u64, secure u8, затем строку версии. Пример с ClassicBox: magic=0x5A4F4933, GSID=0x0130000000B33AE4 (универсум 1, тип 3 = GameServer), secure=1.
• connect (C2S): 0xffffffff, 'k', protocol u32 (24), auth_protocol u32 (3), challenge u32, retry_challenge u32, ChecksumXOR u32 (по записанным байтам), name\0, password\0, patch_version\0 (у GMod — версия сервера, напр. 2026.04.29), затем size u16 (= ticket_len+8), steam_id u64, тикет.
• Отказ: 0xffffffff, '9', my_challenge u32, строка причины (#GameUI_ServerRejectSteam — отказ BeginAuthSession).
• Сервер создаёт netchan-сессию сразу на первый connect (если тикет принят) и отвечает 'B'; повторные connect с тем же SteamID → BeginAuthSession возвращает k_EBeginAuthSessionResultDuplicateRequest → снова отказ. Значит ретраи надо делать с большим интервалом (в движке — тикет кэшируется на сервер: CSteam3Client::GetAuthSessionTicket хранит m_hAuthTicket до смены сервера/IP/secure).
• Частые запросы тикетов подряд (десятки за минуты) приводят к тому, что Steam начинает выдавать тикеты, которые сервер отвергает — нужно ограничить частоту и переиспользовать тикет.
• После 'B' сервер ждёт от клиента (состояние Connected): Net.SetConVar (userinfo) + Net.SignonState(CONNECTED=2), затем шлёт сигнон-блок (Net.Tick, SVC_CreateStringTable×N, SVC_GMod_ServerToClient, SetConVar, SignonState(NEW=3)). Порядок состояний: CONNECTED(2) → NEW(3) → PRESPAWN(4) → SPAWN(5) → FULL(6); на NEW клиент шлёт CLC_ClientInfo + CLC_GMod_ClientToServer + SignonState(NEW). Наши пакеты сервер подтверждает (ack растёт), но сигнон-блок пока не приходит — разбираемся (подозрение: разбор/порядок сообщений или ожидание доп. сообщений).
• Проверено на двух живых серверах: ClassicBox 194.147.90.27:24215 и 37.230.228.47:27021 (ДаркРП).
• Замечание по окружению: на машине сломан системный резолвер (/etc/nsswitch.conf → resolve, но systemd-resolved не запущен) — из-за этого не резолвятся имена (srcds не стартует, master-сервер не опросить). Прямые запросы к 1.1.1.1 работают.