Перейти к содержанию

Сборка документации

Из корня репозитория выполните:

python -m pip install -r requirements-docs.txt
python -m mkdocs serve

Откройте адрес из терминала. Для проверки перед коммитом:

python -m mkdocs build --strict

Английские страницы имеют суффикс .md, русские — .ru.md рядом с оригиналом. Относительные ссылки пишите на .md: плагин сам выбирает язык. Для отсутствующего перевода используется английский текст. Сохраняйте старые пути страниц, чтобы не ломать внешние ссылки.

Workflow проверяет pull request и публикует сайт только при push в master. Нужны права GitHub Actions на запись и GitHub Pages с веткой gh-pages. Локальная сборка ничего не публикует.

Перед изменением публичного поведения прочитайте правила документации для ИИ и архитектуру. Обновляйте EN/RU и соответствующий справочник области вместе с кодом; сохраняйте URL страниц. Текущая база и границы релиза — в истории.

Локальная сборка для Workshop

В Windows установите Python 3.12+ и добавьте glualint в PATH. Один раз установите зависимость сборщика:

python.exe -m pip install -r requirements-build.txt

Запустите build.bat из любой рабочей папки или двойным щелчком. Результат — build/background-citizens/: папка аддона для Workshop с addon.json, лицензией, минифицированной lua/ и копиями игровых ресурсов. build/ игнорируется Git. Сборка ничего не публикует и не изменяет исходные Lua-файлы.

При первом запуске сборщик скачивает glua-minify из коммита 4d19b690faf5e9cd3786d60609f6a02b6f645130 в build/.tools/, проверяет SHA-256 и запускает через LuaJIT из Lupa. Следующие сборки используют проверенный кеш без повторного скачивания. Адаптер исправляет проблемы парсера и областей видимости: goto/метки, неявный self методов, локальные переменные repeat-циклов и совпадения имён с глобальными переменными.

Каждый Lua-файл становится одной физической строкой: комментарии и лишние пробелы удаляются, локальные переменные, функции и параметры получают короткие имена, значения многострочных строк сохраняются через escape-последовательности. Имена публичных методов, глобальных переменных, ключей таблиц, пути и структура файлов SERVER/CLIENT/SHARED сохраняются. Файлы только с комментариями превращаются в return, поскольку GMad не принимает пустые файлы.

Повторные прямые вызовы выбранных стандартных функций math, string и table кешируются в локальных переменных файла. Вызовы через затенённые библиотеки не меняются; обнаруженные записи в библиотеку, её алиасы или доступ к динамическому окружению отключают соответствующее кеширование. Кеширование предполагает, что другие аддоны не подменяют эти стандартные функции после загрузки файла. GMod API и хуки остаются динамическими. Это минификация исходников с ограниченной оптимизацией обращений, без обещания прироста FPS или оптимизации всей программы как в C++. Стеки ошибок теряют подробные номера строк исходников.

Ресурсы копируются из materials/ (vmt/vtf/png/jpg/jpeg), models/ (mdl/vvd/vtx/phy/ani), sound/ (wav/mp3/ogg) и resource/ (properties/ttf). Другие расширения и несовместимые с Workshop *.sw.vtx исключаются. Папка сборки — автономная копия; для обновления пересоберите аддон.

Исходный и сгенерированный Lua должны пройти glualint dump-ast. Ошибка преобразования или проверки синтаксиса сохраняет предыдущую успешную сборку. Успешная пересборка заменяет только build/background-citizens/, удаляя устаревшие сгенерированные файлы. Остальные файлы внутри build/ сохраняются. Инструменты разработки, документация и карантинные файлы не включаются. Чтобы обновить предмет Workshop (id 2341497926), запустите publish.bat: он собирает аддон, упаковывает build/background-citizens.gma через bin/gmad.exe, запрашивает описание обновления (пустое отменяет) и загружает через bin/gmpublish.exe (Steam должен быть запущен).

Регрессионные проверки сборщика:

python.exe -m unittest discover -s tools -p test_build.py -v

Эти проверки выполняются вне игры и проверяют преобразования и работу с результатом; перед публикацией проверьте собранный аддон в GMod.