Building the docs¶
From the repository root:
python -m pip install -r requirements-docs.txt
python -m mkdocs serve
Open the address printed in the terminal. Before committing:
python -m mkdocs build --strict
English pages use .md; Russian siblings use .ru.md. Link to .md paths: the plugin resolves the selected language and falls back to English for missing translations. Preserve existing page paths for external links.
The workflow checks pull requests and deploys only on pushes to master. GitHub Actions needs write access, and GitHub Pages must serve the gh-pages branch. Local builds publish nothing.
Before changing public behavior, read AI documentation rules and architecture. Update both languages and the relevant realm reference with the code; preserve page URLs. See history for the baseline and release boundaries.
Local Workshop build¶
On Windows, install Python 3.12+ and put glualint in PATH. Install the build dependency once:
python.exe -m pip install -r requirements-build.txt
Run build.bat from any working directory, or double-click it. The result is
build/background-citizens/: a Workshop addon folder containing addon.json,
the license, minified lua/ and copied game resources. build/ is ignored by Git.
The build does not upload anything or change the source Lua files.
The first build downloads glua-minify
at commit 4d19b690faf5e9cd3786d60609f6a02b6f645130 into build/.tools/, verifies
its SHA-256, and runs it through Lupa's LuaJIT. Subsequent builds use the verified
cache without downloading it again. The adapter fixes parser/scope issues for
goto/labels, implicit method self, repeat-loop locals and global-name collisions.
Each Lua file becomes one physical line: comments and unnecessary whitespace
are removed, local variables/functions/parameters receive shorter names, and
multiline string values are preserved using escapes. Public methods, globals,
table keys, paths and the SERVER/CLIENT/SHARED file layout keep their names.
Comment-only files become return because GMad rejects empty files.
Repeated direct calls to selected standard math, string and table functions
are cached in file-local variables. Calls through shadowed libraries are left
alone; detected library writes/aliases or dynamic environment access disable the
affected caching. Caching assumes other addons do not replace these standard
functions after this file loads. GMod APIs and hooks remain dynamic. This is
source minification with limited lookup optimization, not a promise of higher FPS
or C++-style whole-program optimization. Debug stack traces lose source line detail.
Resources are copied from materials/ (vmt/vtf/png/jpg/jpeg), models/
(mdl/vvd/vtx/phy/ani), sound/ (wav/mp3/ogg) and resource/
(properties/ttf). Other extensions and Workshop-incompatible *.sw.vtx are
excluded. The build folder is a standalone copy; rebuild to pick up changes.
Both source and generated Lua must pass glualint dump-ast. A failed transform
or syntax check leaves the previous successful output intact. A successful rebuild
replaces only build/background-citizens/, removing stale generated files. Other
files under build/ are retained. Development tools, docs and quarantined files
are not included. To update the Workshop item (id 2341497926), run publish.bat: it builds, packs
build/background-citizens.gma with bin/gmad.exe, asks for the update description
(empty cancels) and uploads with bin/gmpublish.exe (Steam must be running).
Build regression checks:
python.exe -m unittest discover -s tools -p test_build.py -v
These checks cover transformations and output handling outside the game; test the generated addon in GMod before publishing it.