toby-doom-launcher/AGENTS.md

Repository guidance

Project and layout

Toby Doom Launcher is an accessible PySide6 application for configuring and launching Doom games with GZDoom and the Toby Doom Accessibility Mod.

• Toby Doom Launcher.py: application, dialogs, game configuration, launch commands, and speech handling. Quote this filename in shell commands.
• Requirements.txt: Python runtime dependencies. VLC, GZDoom, and usable speech providers also need to be available on the target system.
• Toby Doom Launcher.spec: PyInstaller configuration; output goes to dist/.
• TobyCustom/*.json: custom game definitions, dependencies, optional content, launch flags, and map selection behavior.
• DoomTTS.ps1: Windows speech helper.

Read README.md and any contributing guide before changes. Confirm the intended repository and maintained branch, and check whether the issue exists in current code. Preserve unrelated modified and untracked files. Keep patches scoped and follow the surrounding code's conventions; avoid incidental refactoring or version changes. TOBY_VERSION_NUMBER near the top of the main file identifies the Toby mod version.

Fix verified issues discovered during the work when the correction is small and safe; do not leave them pending just because they predate the current task. Keep each fix focused, verify its behavior and likely regressions, and mention it in the report. Ask before larger changes, ambiguous behavior changes, or destructive actions. This permission does not authorize unrelated refactoring, commits, pushes, or submission.

Useful commands

Run from a suitable game installation:

python3 "Toby Doom Launcher.py"

Install Python dependencies in a virtual environment when needed:

python3 -m pip install -r Requirements.txt

Build with PyInstaller when it is installed:

pyinstaller "Toby Doom Launcher.spec"

Do not launch the application solely for a syntax check: initialization can modify the user's game configuration. A syntax check that does not import the application or create bytecode is:

python3 -c 'import ast; from pathlib import Path; ast.parse(Path("Toby Doom Launcher.py").read_text(encoding="utf-8")); print("Python syntax OK")'

Behavior to preserve

• DoomLauncher owns the main UI and launch process. IWADSelector discovers IWADs; CustomGameDialog selects JSON configurations. AudioPlayer and AudioManualDialog provide the VLC audio manual.
• Windows resolves game files from the working directory and uses TobyConfig.ini. Linux uses ~/.local/games/doom and ~/.local/share/doom, with GZDoom settings under $XDG_CONFIG_HOME/gzdoom/gzdoom.ini (default ~/.config). Preserve these platform distinctions. macOS remains untested according to the README.
• Custom game definitions are searched in the launcher directory, game directory, and Linux share directory; Windows uses the working directory. Preserve dependency checks and the order of files and flags passed to GZDoom.
• use_map_menu enables map selection. map_after_files defaults to false: selected maps load after TobyAccMod and before game files. When true, maps load after game files, and selected music follows the map. This order affects which content overrides other content.
• SpeechHandler handles game output using the selected speech provider. ScreenReaderRemoteController, OrcaRemoteController, and CthulhuRemoteController implement D-Bus integration through dasbus. Inspect their current service configurations and methods before changing them; old Orca endpoint examples are not an API specification.
• Preserve subprocess argument boundaries, background speech processing, process monitoring, and cleanup when the game or launcher exits.
• The main file contains repeated class and method definitions. Check which definition actually runs before editing; later definitions override earlier ones. Do not remove duplicates as unrelated cleanup.

Accessibility and verification

Use native Qt controls, complete accessible names, and label buddies where appropriate. Preserve Tab and Shift+Tab navigation, dialog focus, Escape behavior, and AccessibleComboBox keyboard handling. Let screen readers announce the UI through Qt accessibility; keep game-output speech separate from UI feedback. Never communicate state only through color or sound.

There is no checked-in automated test suite. Run focused syntax or JSON checks for changed files, and report exactly what they establish. For behavior changes, also exercise the affected workflow with a real game installation and screen reader, preserving the user's configuration before testing. Do not claim live speech or keyboard accessibility from syntax checks or mocks.

Give the contributor concrete manual checks for the changed behavior and likely regressions: control labels and keyboard navigation for UI changes; file order, IWAD selection, and optional content for custom games; narration styles and provider selection for speech; game exit and launcher close for process changes; track selection, playback, and stop for audio manual changes. Distinguish tested platforms from unverified ones.

Follow the AI-assisted contribution policy in README.md. Human review and testing are required before submission; do not commit, push, or submit changes unless explicitly requested.