Сборка документации¶
Из корня репозитория выполните:
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.