gmod-rs/AGENTS.md

AGENTS.md — Source RS

Краткая вводная для агентов и разработчиков. Полный контекст — в docs/.

Читать первым

1. docs/PLAN.md — что строим, принципы, этапы, решения.
2. docs/ARCHITECTURE.md — структура крейтов и правила зависимостей.
3. docs/PROBLEMS.md — какие боли чиним, включая «Принцип сандбокс-масштаба».
4. docs/LUA.md, docs/NETWORK.md, docs/RECON.md — по профилю задачи.

Железные правила

1. Никаких unwrap()/panic!/expect() на данных из сети или файлов. Всё — bounded-парсеры с явными лимитами (максимумы строк, глубина рекурсии, размеры массивов).
2. catch_unwind на всех границах: вызовы Lua, FFI (Jolt/Steam), worker-потоки, обработчики задач. Клиент не должен падать ни из-за аддона, ни из-за сервера.
3. Код Source SDK 2013 / Source.NET / прочих референсов не копируем — только как спецификацию поведения (Source 1 SDK License). Реализация — своя.
4. Ассеты Garry's Mod не коммитим и не распространяем; только пути локальных установок пользователя (конфиг).
5. Изменение договорённостей/архитектуры — обновление docs/ в том же коммите.
6. Документация, коммиты и комментарии — на русском (код — английский).
7. Приоритет — оригинальным ресурсам Garry's Mod. Lua-скрипты игры (gamemodes/, lua/derma, lua/vgui, lua/weapons, lua/entities), ассеты из VPK/установки и данные карты — источник истины. Свои реализации и заглушки включаются только там, где оригинала нет (движковые вещи вроде weapon_physgun/weapon_pistol, отсутствующие VMT/VTF, сломанные данные), и обязаны уступать оригиналу: одноимённый Lua-скрипт перекрывает встроенную реализацию, поля SWEP (ViewModelFOV, смещения) — нашу таблицу подгонки.

Команды (по мере появления кода)

cargo fmt --all
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
# запуск клиента (пример; пути к ассетам настраиваются)
cargo run -p client --bin gmod-rs -- --assets ~/gmod_server/server