111 lines
5.3 KiB
Markdown
111 lines
5.3 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
python3 "Toby Doom Launcher.py"
|
|
```
|
|
|
|
Install Python dependencies in a virtual environment when needed:
|
|
|
|
```bash
|
|
python3 -m pip install -r Requirements.txt
|
|
```
|
|
|
|
Build with PyInstaller when it is installed:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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.
|