Automation Scripts & Tooling
Relevant source files
The following files were used as context for generating this wiki page:
Automation scripts and tooling in BandaStation manage codebase integrity, simplify map development, and automate documentation. These tools reduce manual labor during large-scale refactors and ensure that contributions adhere to project standards through Continuous Integration (CI) checks and specialized utility scripts.
Map and Path Management
BandaStation utilizes specialized tools to handle map file formats and path refactoring, ensuring compatibility with Git and the BYOND DreamMaker environment.
Map Merger 2
The Map Merger keeps maps in a format that tracks easily in Git and minimizes merge conflicts. It converts maps between DMM and TGM formats, with TGM being the preferred format for repository storage.
convert.py: Converts maps to and from the TGM format.mapmerge.py: Runs the merge operation on map backups.precommit.py: A Git hook that automatically merges the index version of a map with the Git version during a commit.
Sources: tools/mapmerge2/README.md:1-40
UpdatePaths
UpdatePaths automates the renaming of object paths within map files. This is essential when a developer refactors code and moves or renames classes. The tool ensures that map files do not lose data or unknown paths when opened in the map editor.
The diagram shows the data flow of the UpdatePaths tool as it processes scripts to mutate map files.
Key features include:
- Subtype Handling: Using the
@SUBTYPEStag to update an entire tree of objects. - Variable Retention: The
{@OLD}tag ensures existing variable edits on a map are preserved. - Variable Filtering: Tags like
@SKIPor@ANYallow precise targeting of specific variable values.
Sources: tools/UpdatePaths/readme.md:1-120
Continuous Integration and Code Sanity
The project employs several scripts to enforce coding standards and detect errors before code is merged.
Check Grep Linter
The check_grep.sh script performs extensive pattern matching to find common mistakes in code and map files.
| Check Category | Description |
|---|---|
| Map Issues | Detects non-TGM formats, unexpected comments, and invalid procs in maps. |
| Whitespace | Enforces tab indentation and LF line endings. |
| Common Mistakes | Finds unmanaged global variables, manual verb definitions, and spelling errors. |
| 515/516 Syntax | Identifies outdated BYOND syntax for hrefs and proc references. |
Sources: tools/ci/check_grep.sh:1-250
Define Sanity
The check.py script in the define_sanity directory ensures that local #define statements are properly cleaned up. It scans .dm files for definitions and flags any that do not have a corresponding #undef in the same file.
The flowchart illustrates the logic used to enforce local definition scope.
Sources: tools/define_sanity/check.py:1-90
Wiki Automation
The autowiki.js script automates the publishing of generated documentation to the project's MediaWiki instance. It uses the mwbot library to interact with the API.
- Authentication: Uses
USERNAMEandPASSWORDfrom environment variables. - Rate Limiting: Implements an exponential backoff strategy with
MAX_RATE_LIMIT_RETRIES(5) andRATE_LIMIT_RETRY_DELAY(5000ms). - Automation Note: Automatically prepends a
<noinclude>warning to pages indicating they are automated and should not be edited manually.
Sources: tools/autowiki/autowiki.js:1-100, tools/autowiki/package.json:1-10
Development and Build Tooling
TGUI Tooling
The TGUI framework provides a suite of scripts for building and debugging the React-based user interface.
bin/tgui-build: Builds TGUI for production and runs CI checks.bin/tgui-dev: Launches a development server with support for hot reloading and layout debugging.bun tgui:lint: Automatically fixes code style problems.
Sources: tgui/README.md:40-100
Flaky Test Management
The rerunFlakyTests.js script identifies integration tests that fail due to non-deterministic issues. If a test fails and subsequently passes on a retry, the script extracts failure details from the logs and either creates a new GitHub issue or comments on an existing one labeled "🤖 Flaky Test Report".
Sources: tools/pull_request_hooks/rerunFlakyTests.js:1-150
Summary
The automation ecosystem in BandaStation spans from low-level map file manipulation (UpdatePaths, Map Merger) to high-level CI maintenance (Check Grep, Define Sanity) and automated documentation (Autowiki). These tools maintain a consistent environment for developers and ensure that the codebase remains stable across BYOND version updates and large-scale architectural changes.