a2qlinux 0.2.0__tar.gz

a2qlinux-0.2.0/.gitignore

@@ -0,0 +1,32 @@
+# Built by bridge/build.sh (Windows parts, test programs, tools)
+*.exe
+*.dll
+
+# Python
+__pycache__/
+*.pyc
+
+# IDE
+.idea/
+.vscode/
+
+# Claude Code local config (skills, local settings) — kept per-machine, not committed
+.claude/
+
+# Private notes (Polish): other meters, game rules, network diagnostics of this
+# machine. Kept locally, never committed.
+notes/
+
+# Editor / OS
+*.bak
+*.orig
+.DS_Store
+
+# Runtime
+*.log
+
+# Packaging
+a2qlinux/_version.py
+dist/
+build/
+*.egg-info/

a2qlinux-0.2.0/CHANGELOG.md

@@ -0,0 +1,72 @@
+# Changelog
+
+What changed for players, release by release. Technical details are in
+`docs/ARCHITECTURE.md`.
+
+## [0.2.0] — 2026-11-05
+
+### Changed
+- A2Qlinux is now installed and updated from PyPI: `pipx install a2qlinux`,
+  then `pipx upgrade a2qlinux` for new versions. After updating from 0.1.0,
+  which was installed from a downloaded file, switch over once: quit
+  Questlog, then run `pipx uninstall a2qlinux && pipx install a2qlinux`. The
+  menu entry, the Steam launch option and the settings stay as they are.
+- Play in Steam (with the launch option) starts Questlog first and the game
+  a few seconds later, once Questlog runs, instead of the other way round.
+  That is what lets the game end without disturbing Questlog.
+- Quit Questlog ends it at once when no game data is waiting to be saved
+  (without the game, or a while after closing it); while playing, it still
+  waits until the last data is saved, at most about 10 seconds.
+- The status window opens in the terminal the desktop has (GNOME Terminal,
+  Ptyxis, the Xfce or MATE terminal, Debian's default terminal or xterm),
+  not only in Konsole. Without any, a notification says which to install.
+
+### Added
+- `a2qlinux-setup` installs Questlog when it is not there yet: it downloads
+  the newest version from Questlog's authors, checks it and puts it in
+  place. Installing Questlog by hand is no longer needed.
+- `a2qlinux-setup` checks everything A2Qlinux needs, including that
+  capturing the game's traffic is allowed and that the tray icon can run on
+  the desktop, and for anything missing prints the exact command for the
+  distribution in use.
+- A settings file, `~/.config/a2qlinux/config.toml`, created by
+  `a2qlinux-setup`: Questlog's folder, what happens after the game (Questlog
+  stays or closes, and after how long it closes), and automatic updates.
+  Mistakes in it are reported with their line, and the default is used
+  meanwhile.
+- The install guide covers Debian, Ubuntu, Fedora and openSUSE besides
+  Arch, in numbered steps with one package command per distribution, and
+  says what A2Qlinux needs from the desktop and from Steam.
+
+### Fixed
+- Steam no longer shows AION 2 as running after the game is closed while
+  Questlog stays open: a moment after the game ends, Steam shows Play again,
+  and Questlog keeps running untouched. Only when the game was started
+  before Questlog does Questlog restart, about 10 seconds after the game, as
+  it was (window open or only in the tray).
+- AION 2's Proton environment is found wherever Steam is installed, not
+  only in its default folder. A Steam from Flatpak, which A2Qlinux cannot
+  work with, is named as the reason.
+
+## [0.1.0] — 2026-10-18
+
+First release.
+
+### Added
+- Questlog Desktop runs next to AION 2 on Linux, inside the game's Proton
+  environment, with live game traffic: the damage meter, boss HP and alerts
+  work as on Windows.
+- Questlog can be started before, after or together with the game; with the
+  Steam launch option it starts with the game, and pressing Play while
+  Questlog is open lets the game join it.
+- Clicks in the game stay in the game while Questlog's window is open behind
+  it.
+- A tray icon with Open and Quit that works every time, in place of
+  Questlog's own, whose menu opens only once under Proton.
+- Quitting Questlog waits until it has saved its data, without touching the
+  game; opening it again within those seconds keeps it running.
+- Questlog is kept up to date: new versions are downloaded in the background
+  (never while the game runs), checked, installed at the next start, and
+  rolled back if they do not start.
+- Installation with pipx; `a2qlinux-setup` creates the "Questlog (AION 2)"
+  menu entry, which keeps itself pointing at the installed program.

a2qlinux-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 raman78
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

a2qlinux-0.2.0/PKG-INFO

@@ -0,0 +1,142 @@
+Metadata-Version: 2.5
+Name: a2qlinux
+Version: 0.2.0
+Summary: Questlog Desktop (AION 2 damage meter) on Linux under Proton, with live game traffic.
+Project-URL: homepage, https://github.com/raman78/A2Qlinux
+Project-URL: repository, https://github.com/raman78/A2Qlinux
+Project-URL: issues, https://github.com/raman78/A2Qlinux/issues
+Author: raman78
+License: MIT License
+        
+        Copyright (c) 2026 raman78
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: aion2,dps-meter,linux,proton,questlog,wine
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: X11 Applications :: Qt
+Classifier: Natural Language :: English
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Games/Entertainment
+Requires-Python: >=3.11
+Requires-Dist: pyqt6>=6.5
+Requires-Dist: python-xlib>=0.33
+Description-Content-Type: text/markdown
+
+# A2Qlinux
+
+Run [Questlog Desktop](https://questlog.gg/aion-2/en/app), the Windows-only
+damage meter and overlay app for AION 2, on Linux next to the game under
+Steam's Proton, with live game traffic.
+
+Questlog reads the game's traffic through Npcap, a Windows driver that cannot
+work under Wine/Proton. A2Qlinux captures the traffic on the Linux side with
+`dumpcap` and hands it to Questlog through its own stand-in for Npcap's
+`wpcap.dll`. Questlog runs inside the game's Proton prefix, in its normal
+live-capture mode, with its overlays over the game. Its program files stay
+as shipped; the only change A2Qlinux makes to Questlog's folder is removing
+the configuration of Questlog's own updater, which cannot install under
+Proton (A2Qlinux updates it instead).
+
+It also handles what comes with sharing a Wine session with a fullscreen
+game:
+
+- starting Questlog before, after or together with the game (Steam launch
+  option), without blocking the game's launch;
+- keeping clicks in the game while Questlog's window is open behind it;
+- its own tray icon (Open / Quit) in place of Questlog's, whose menu opens
+  only once under Proton;
+- quitting Questlog without losing its last data and without touching the
+  game or other programs in the prefix;
+- updating Questlog: its own updater cannot install under Proton, so A2Qlinux
+  downloads new versions in the background (not while the game runs), checks
+  them against what it relies on, installs them at the next start and rolls
+  back if they do not start.
+
+Status: in daily use on CachyOS, KDE Plasma 6 (Wayland), Proton 11
+(`proton-cachyos-slr`), Questlog 0.1.37. Other distributions and desktops
+are untested; what they need (Steam from the distribution or Valve, not
+Flatpak; a system tray; Python 3.11 or newer; the packages per distribution)
+is in [docs/INSTALL.md](https://github.com/raman78/A2Qlinux/blob/main/docs/INSTALL.md#what-you-need-before-you-start).
+
+## Quick start
+
+The [installation guide](https://github.com/raman78/A2Qlinux/blob/main/docs/INSTALL.md) walks through each step, with the commands
+for Arch, Debian, Ubuntu, Fedora and openSUSE. In short:
+
+1. Install the packages A2Qlinux uses — see
+   [Installing the packages](https://github.com/raman78/A2Qlinux/blob/main/docs/INSTALL.md#installing-the-packages).
+2. Join the `wireshark` group and log in again — see
+   [Allowing capture](https://github.com/raman78/A2Qlinux/blob/main/docs/INSTALL.md#allowing-capture).
+3. `pipx install a2qlinux`, `pipx ensurepath`, open a new terminal, then
+   `a2qlinux-setup --desktop-shortcut`. It installs Questlog, checks
+   everything else and prints the command for anything still missing — see
+   [Installing A2Qlinux and Questlog](https://github.com/raman78/A2Qlinux/blob/main/docs/INSTALL.md#installing-a2qlinux-and-questlog).
+4. Start **Questlog (AION 2)** from the menu, or set the Steam launch option
+   that `a2qlinux-setup` prints.
+
+## Documentation
+
+- [docs/INSTALL.md](https://github.com/raman78/A2Qlinux/blob/main/docs/INSTALL.md) — requirements, installing, removal.
+- [docs/USING.md](https://github.com/raman78/A2Qlinux/blob/main/docs/USING.md) — starting, tray icon, playing.
+- [docs/UPDATING.md](https://github.com/raman78/A2Qlinux/blob/main/docs/UPDATING.md) — Questlog updates, installing Questlog
+  by hand, and updating A2Qlinux itself (`pipx upgrade a2qlinux`).
+- [docs/TROUBLESHOOTING.md](https://github.com/raman78/A2Qlinux/blob/main/docs/TROUBLESHOOTING.md) — problems, FAQ.
+- [docs/ARCHITECTURE.md](https://github.com/raman78/A2Qlinux/blob/main/docs/ARCHITECTURE.md) — how it works and why, failure
+  modes, tests, what a Questlog update can break.
+
+## Repository layout
+
+| Path | What |
+|---|---|
+| `a2qlinux/launcher.py` | launcher (`a2qlinux-run`): capture, bridge, starting/quitting Questlog, tray |
+| `a2qlinux/pcap_bridge.py` | TCP server that feeds captured packets to the DLL |
+| `a2qlinux/desktop.py` | `a2qlinux`: menu-entry entry point; one launcher at a time |
+| `a2qlinux/tray.py` | tray icon (PyQt6) |
+| `a2qlinux/config.py` | settings from `~/.config/a2qlinux/config.toml` |
+| `a2qlinux/update.py` | installing Questlog, and background Questlog updates: download, verify, check, install, roll back |
+| `a2qlinux/steam.py` | `a2qlinux-steam`: Steam launch-option wrapper |
+| `a2qlinux/setup_desktop.py` | `a2qlinux-setup`: dependency and capture checks with install commands, Questlog installation, menu entry, icon |
+| `a2qlinux/bin/` | the built Windows parts (shipped in the package, not in git) |
+| `bridge/` | Windows parts in C: `wpcap.dll` stand-in, `questlog_ctl.exe`, their tests; `build.sh` |
+| `tests/` | Python tests: `python3 -m unittest` |
+| `tools/` | diagnostics: replay-file tools, TCP-owner probe |
+
+The Windows parts are built with `clang` against the installed Wine's headers
+(`bridge/build.sh`) — by the release workflow for the packages, by hand in a
+source checkout; built files are not kept in the repository. Releasing:
+[docs/RELEASE.md](https://github.com/raman78/A2Qlinux/blob/main/docs/RELEASE.md).
+
+## Not affiliated
+
+A2Qlinux is an independent project, not made or endorsed by Questlog's
+authors or by AION 2's publisher. It contains no Questlog code or assets:
+Questlog is downloaded from its authors, and its icon is taken from your own
+installation. Questlog and its name belong to its authors (questlog.gg).
+
+Whether third-party meters are allowed is for the game's publisher, NCSOFT,
+to decide. It has not said so either way, and its rules forbid
+"unauthorized programs" in general terms. Using any third-party meter,
+under Windows or through A2Qlinux, is at your own risk; check the
+publisher's current rules.
+
+## License
+
+MIT — see [LICENSE](https://github.com/raman78/A2Qlinux/blob/main/LICENSE).

a2qlinux-0.2.0/README.md

@@ -0,0 +1,100 @@
+# A2Qlinux
+
+Run [Questlog Desktop](https://questlog.gg/aion-2/en/app), the Windows-only
+damage meter and overlay app for AION 2, on Linux next to the game under
+Steam's Proton, with live game traffic.
+
+Questlog reads the game's traffic through Npcap, a Windows driver that cannot
+work under Wine/Proton. A2Qlinux captures the traffic on the Linux side with
+`dumpcap` and hands it to Questlog through its own stand-in for Npcap's
+`wpcap.dll`. Questlog runs inside the game's Proton prefix, in its normal
+live-capture mode, with its overlays over the game. Its program files stay
+as shipped; the only change A2Qlinux makes to Questlog's folder is removing
+the configuration of Questlog's own updater, which cannot install under
+Proton (A2Qlinux updates it instead).
+
+It also handles what comes with sharing a Wine session with a fullscreen
+game:
+
+- starting Questlog before, after or together with the game (Steam launch
+  option), without blocking the game's launch;
+- keeping clicks in the game while Questlog's window is open behind it;
+- its own tray icon (Open / Quit) in place of Questlog's, whose menu opens
+  only once under Proton;
+- quitting Questlog without losing its last data and without touching the
+  game or other programs in the prefix;
+- updating Questlog: its own updater cannot install under Proton, so A2Qlinux
+  downloads new versions in the background (not while the game runs), checks
+  them against what it relies on, installs them at the next start and rolls
+  back if they do not start.
+
+Status: in daily use on CachyOS, KDE Plasma 6 (Wayland), Proton 11
+(`proton-cachyos-slr`), Questlog 0.1.37. Other distributions and desktops
+are untested; what they need (Steam from the distribution or Valve, not
+Flatpak; a system tray; Python 3.11 or newer; the packages per distribution)
+is in [docs/INSTALL.md](https://github.com/raman78/A2Qlinux/blob/main/docs/INSTALL.md#what-you-need-before-you-start).
+
+## Quick start
+
+The [installation guide](https://github.com/raman78/A2Qlinux/blob/main/docs/INSTALL.md) walks through each step, with the commands
+for Arch, Debian, Ubuntu, Fedora and openSUSE. In short:
+
+1. Install the packages A2Qlinux uses — see
+   [Installing the packages](https://github.com/raman78/A2Qlinux/blob/main/docs/INSTALL.md#installing-the-packages).
+2. Join the `wireshark` group and log in again — see
+   [Allowing capture](https://github.com/raman78/A2Qlinux/blob/main/docs/INSTALL.md#allowing-capture).
+3. `pipx install a2qlinux`, `pipx ensurepath`, open a new terminal, then
+   `a2qlinux-setup --desktop-shortcut`. It installs Questlog, checks
+   everything else and prints the command for anything still missing — see
+   [Installing A2Qlinux and Questlog](https://github.com/raman78/A2Qlinux/blob/main/docs/INSTALL.md#installing-a2qlinux-and-questlog).
+4. Start **Questlog (AION 2)** from the menu, or set the Steam launch option
+   that `a2qlinux-setup` prints.
+
+## Documentation
+
+- [docs/INSTALL.md](https://github.com/raman78/A2Qlinux/blob/main/docs/INSTALL.md) — requirements, installing, removal.
+- [docs/USING.md](https://github.com/raman78/A2Qlinux/blob/main/docs/USING.md) — starting, tray icon, playing.
+- [docs/UPDATING.md](https://github.com/raman78/A2Qlinux/blob/main/docs/UPDATING.md) — Questlog updates, installing Questlog
+  by hand, and updating A2Qlinux itself (`pipx upgrade a2qlinux`).
+- [docs/TROUBLESHOOTING.md](https://github.com/raman78/A2Qlinux/blob/main/docs/TROUBLESHOOTING.md) — problems, FAQ.
+- [docs/ARCHITECTURE.md](https://github.com/raman78/A2Qlinux/blob/main/docs/ARCHITECTURE.md) — how it works and why, failure
+  modes, tests, what a Questlog update can break.
+
+## Repository layout
+
+| Path | What |
+|---|---|
+| `a2qlinux/launcher.py` | launcher (`a2qlinux-run`): capture, bridge, starting/quitting Questlog, tray |
+| `a2qlinux/pcap_bridge.py` | TCP server that feeds captured packets to the DLL |
+| `a2qlinux/desktop.py` | `a2qlinux`: menu-entry entry point; one launcher at a time |
+| `a2qlinux/tray.py` | tray icon (PyQt6) |
+| `a2qlinux/config.py` | settings from `~/.config/a2qlinux/config.toml` |
+| `a2qlinux/update.py` | installing Questlog, and background Questlog updates: download, verify, check, install, roll back |
+| `a2qlinux/steam.py` | `a2qlinux-steam`: Steam launch-option wrapper |
+| `a2qlinux/setup_desktop.py` | `a2qlinux-setup`: dependency and capture checks with install commands, Questlog installation, menu entry, icon |
+| `a2qlinux/bin/` | the built Windows parts (shipped in the package, not in git) |
+| `bridge/` | Windows parts in C: `wpcap.dll` stand-in, `questlog_ctl.exe`, their tests; `build.sh` |
+| `tests/` | Python tests: `python3 -m unittest` |
+| `tools/` | diagnostics: replay-file tools, TCP-owner probe |
+
+The Windows parts are built with `clang` against the installed Wine's headers
+(`bridge/build.sh`) — by the release workflow for the packages, by hand in a
+source checkout; built files are not kept in the repository. Releasing:
+[docs/RELEASE.md](https://github.com/raman78/A2Qlinux/blob/main/docs/RELEASE.md).
+
+## Not affiliated
+
+A2Qlinux is an independent project, not made or endorsed by Questlog's
+authors or by AION 2's publisher. It contains no Questlog code or assets:
+Questlog is downloaded from its authors, and its icon is taken from your own
+installation. Questlog and its name belong to its authors (questlog.gg).
+
+Whether third-party meters are allowed is for the game's publisher, NCSOFT,
+to decide. It has not said so either way, and its rules forbid
+"unauthorized programs" in general terms. Using any third-party meter,
+under Windows or through A2Qlinux, is at your own risk; check the
+publisher's current rules.
+
+## License
+
+MIT — see [LICENSE](https://github.com/raman78/A2Qlinux/blob/main/LICENSE).

a2qlinux-0.2.0/a2qlinux/__init__.py

@@ -0,0 +1,6 @@
+"""A2Qlinux: Questlog Desktop for AION 2 on Linux under Proton, with live game traffic."""
+
+try:
+    from ._version import __version__
+except ImportError:           # a source checkout that was never built or installed
+    __version__ = "0+unknown"

a2qlinux-0.2.0/a2qlinux/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.2.0'
+__version_tuple__ = version_tuple = (0, 2, 0)
+
+__commit_id__ = commit_id = None

a2qlinux-0.2.0/a2qlinux/config.py

@@ -0,0 +1,148 @@
+"""User settings: ~/.config/a2qlinux/config.toml.
+
+Which value wins, highest first:
+    1. a command-line option        (--interface, --close-with-game, --no-auto-update, --exe)
+    2. an environment variable      (QUESTLOG_DIR)
+    3. this file
+    4. the default in SETTINGS
+
+Only behaviour a user may want to change is here. Values that follow from
+how Questlog or Wine work (how long Questlog needs to save, wait limits) are
+named constants in the code, documented in docs/ARCHITECTURE.md.
+
+Nothing wrong in the file is ignored silently: load() returns each problem
+(file, line, what is wrong) next to the settings, using the default for that
+setting; the launcher shows them in its window and as a notification.
+"""
+
+from dataclasses import dataclass
+import os
+from pathlib import Path
+import re
+import tomllib
+
+CONFIG_PATH = Path(os.environ.get("XDG_CONFIG_HOME") or Path.home() / ".config") / "a2qlinux" / "config.toml"
+# Closing Questlog after the game does not wait for it to save, so the delay
+# must cover the time Questlog takes to save game data (see launcher.SAVE_WAIT).
+MIN_AFTER_GAME_DELAY = 10.5
+
+
+@dataclass(frozen=True)
+class Setting:
+    default: object
+    kind: type
+    help: str
+    choices: tuple = ()
+    minimum: float = None
+
+
+SETTINGS = {
+    "questlog_dir": Setting("~/Games/Questlog", str,
+                            "Folder with Questlog.exe (the QUESTLOG_DIR environment variable overrides it)."),
+    "interface": Setting("", str,
+                         "Network interface carrying the game's traffic; empty: the only one besides lo."),
+    "after_game": Setting("keep", str,
+                          '"keep": Questlog stays open after the game, and Steam sees the game as closed; '
+                          '"close": Questlog closes with the game.',
+                          choices=("keep", "close")),
+    "after_game_delay": Setting(15, (int, float),
+                                'With after_game = "close": seconds after the game exits before Questlog closes '
+                                f"(a game restarted sooner keeps it open). At least {MIN_AFTER_GAME_DELAY:g}.",
+                                minimum=MIN_AFTER_GAME_DELAY),
+    "auto_update": Setting(True, bool, "Download new Questlog versions in the background and install them "
+                                       "at the next start."),
+    "update_check_hours": Setting(6, (int, float), "Hours between checks for a new Questlog.", minimum=0.25),
+}
+
+
+@dataclass(frozen=True)
+class Settings:
+    questlog_dir: Path
+    interface: str
+    after_game: str
+    after_game_delay: float
+    auto_update: bool
+    update_check_hours: float
+
+
+def _line_of(text, key):
+    for number, line in enumerate(text.splitlines(), 1):
+        if re.match(rf"\s*{re.escape(key)}\s*=", line):
+            return number
+    return None
+
+
+def load(path=CONFIG_PATH):
+    """(Settings, problems). A missing file is no problem: all defaults."""
+    values = {name: spec.default for name, spec in SETTINGS.items()}
+    problems = []
+    path = Path(path)
+    try:
+        text = path.read_text()
+        data = tomllib.loads(text)
+    except FileNotFoundError:
+        text, data = "", {}
+    except (OSError, UnicodeDecodeError) as error:
+        text, data = "", {}
+        problems.append(f"{path}: cannot be read ({error}); using the defaults.")
+    except tomllib.TOMLDecodeError as error:
+        text, data = "", {}
+        problems.append(f"{path}: not valid TOML ({error}); using the defaults.")
+    for name, value in data.items():
+        where = f"{path}, line {_line_of(text, name) or '?'}"
+        spec = SETTINGS.get(name)
+        if spec is None:
+            problems.append(f"{where}: unknown setting '{name}' (known: {', '.join(SETTINGS)}); ignored.")
+            continue
+        wrong_type = not isinstance(value, spec.kind) or (spec.kind is not bool and isinstance(value, bool))
+        if wrong_type:
+            problems.append(f"{where}: '{name}' must be {_kind_name(spec.kind)}, not {value!r}; "
+                            f"using {spec.default!r}.")
+            continue
+        if spec.choices and value not in spec.choices:
+            problems.append(f"{where}: '{name}' must be one of {', '.join(map(repr, spec.choices))}, "
+                            f"not {value!r}; using {spec.default!r}.")
+            continue
+        if spec.minimum is not None and value < spec.minimum:
+            problems.append(f"{where}: '{name}' must be at least {spec.minimum:g}, not {value!r}; "
+                            f"using {spec.default!r}.")
+            continue
+        values[name] = value
+    env_dir = os.environ.get("QUESTLOG_DIR")
+    values["questlog_dir"] = Path(env_dir or values["questlog_dir"]).expanduser()
+    values["after_game_delay"] = float(values["after_game_delay"])
+    values["update_check_hours"] = float(values["update_check_hours"])
+    return Settings(**values), problems
+
+
+def _kind_name(kind):
+    if kind is bool:
+        return "true or false"
+    if kind is str:
+        return "a quoted text"
+    return "a number"
+
+
+def questlog_dir():
+    """Where Questlog is, for the parts that need only that (the menu entry, the Steam wrapper)."""
+    return load()[0].questlog_dir
+
+
+def template(questlog_dir=None):
+    """The file a2qlinux-setup writes when there is none: every setting, at its default, explained."""
+    lines = ["# A2Qlinux settings. Delete a line to get its default back.",
+             "# A command-line option or the QUESTLOG_DIR variable overrides the value here.", ""]
+    for name, spec in SETTINGS.items():
+        value = str(questlog_dir) if name == "questlog_dir" and questlog_dir else spec.default
+        lines.append(f"# {spec.help}")
+        lines.append(f"{name} = {_toml(value)}")
+        lines.append("")
+    return "\n".join(lines)
+
+
+def _toml(value):
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, str):
+        return '"' + value.replace("\\", "\\\\").replace('"', '\\"') + '"'
+    return repr(value)