Documentation status: maintained reference. MODUS is
0.9.5-betaand NOT READY for production use. This guide gets the current checkout running; it is not a release promise.
Languages: English · Português (Brasil) Updated: September 29, 2026 · Toolchain: Godot 4.7.2 / GUT 9.7.1
- Godot 4.7 in the 4.7 line expected by
project.godot; CI uses 4.7.2. - Bash for repository verification scripts.
- A writable
/tmpfor the isolated headless runner environment. - A graphical session for editor, visual, input, and manual gameplay evidence.
- Python 3.10+ for release helpers;
zstdfor.tar.zstpackage operations. - No GodotSteam extension is bundled. Steam-specific behavior requires separate installation, app configuration, and proof.
From the repository root:
godot --editor --path .The configured main scene is shared/ui_core/screens/main_menu_screen.tscn. For a bounded startup check:
tools/run_main_player_path_smoke.sh --strictThat smoke proves menu/startup only. It does not prove movement, combat, saves, multiplayer, or editor interaction.
This is a local artifact path, not a published release. Install the Godot 4.7 Linux export template, then run:
mkdir -p standalone/client
godot --headless --path . --export-release "Linux Desktop" standalone/client/modus.x86_64
tools/run_export_smoke.sh --platform linux --executable standalone/client/modus.x86_64The smoke covers bounded Linux launch only. It does not prove installer quality, signing, Steam/GodotSteam behavior, target-Windows runtime, manual gameplay, or long-session stability.
From the repository root, after building standalone/client/modus.x86_64 and its adjacent .pck:
tools/package_linux_portable.sh package \
--artifact-dir standalone/client \
--output logs/modus-linux-0.9.5-beta.tar.zst
tools/package_linux_portable.sh install \
--archive logs/modus-linux-0.9.5-beta.tar.zst \
--prefix "$HOME/.local/opt/modus"
tools/package_linux_portable.sh verify --prefix "$HOME/.local/opt/modus"
tools/package_linux_portable.sh uninstall --prefix "$HOME/.local/opt/modus".tar.zst is preferred for transfer and requires the zstd executable; .tar.gz remains supported. The installer owns only $prefix/modus and its manifest. It preserves user save/config data in the XDG data and config directories. This is a local unsigned portable package, not installer, signing, target-Windows, Steam, manual-gameplay, or release-version proof.
bash tools/check_documentation_truth.sh
bash tools/check_project_truth.sh
bash tools/check_headless_runner_manifest.shRun automated tests when you need runtime contract evidence:
./tests/runners/run_all_tests_headless.sh
./tests/runners/run_tests_by_category.sh --report docs/AUTOMATED_TEST_LANES_REPORT.mdGenerated reports and raw logs/ are ignored local outputs, absent from a fresh clone. See regeneration commands and prerequisites. The published status summary records dated evidence, not a fresh result; a clean source/docs check is not a green game test suite.
game/scripts/core/— GameManager and foundational runtime code.game/scripts/features/— feature/service modules.game/entities/— player, enemies, components, effects, and projectiles.game/world/— maps and world actors.game/editor/andshared/editor_core/— editor surfaces.game/data/— content data.game/config/— runtime configuration and profiles.mods/— sample repository mods.tests/— automated/manual evidence surfaces.docs/— current truth, generated reports, maintained guides, and labeled historical snapshots.
The current global entry point is GameManager:
var logger: Node = GameManager.get_core_system("logger")
var config: Node = GameManager.get_core_system("config")
if logger:
logger.info("Example initialized", "Example")
GameManager.subscribe("example_event", _on_example_event)
GameManager.emit_event("example_event", {"source": "getting_started"})Optional services can be absent under a feature profile, so null-check lookups. Do not add a new autoload just to obtain an existing service.
Use the ownership map in docs/technical/JSON_SCHEMAS.md:
- authored registries such as weapons, enemies, and loot live under
game/data/; - runtime settings live under
game/config/; - feature profiles begin at
game/config/features.json5; - user mod overrides belong under
user://mods/.
Do not restore retired configuration directories or duplicate root-level gameplay configuration files.
- Identify the source file and its focused test.
- Change the smallest coherent surface.
- Run GDScript formatting/lint for touched scripts when available.
- Run the focused test, then the relevant wider lane.
- Update
BACKLOG.md,CHANGELOG.md, and current docs with the exact proof boundary. - Leave manual, hardware, Steam, and connected-peer claims open unless they were actually observed.
- Current state:
docs/CURRENT_STATUS.md - Architecture:
docs/architecture.md - Testing:
tests/README.md - Modding:
docs/guides/MODDING.md - Troubleshooting:
docs/troubleshooting.md - Evidence collection:
tests/docs/MANUAL_PLAYER_EXPERIENCE_TESTS.md