Development history¶
Dated entries, newest last. Numbers where there are numbers.
2026-09-25: research, plan, scaffold (M0)¶
- Read the knowledge base (the SS14 knowledge base, 7 files) and the source of the launcher (
437fe66), engine (61bbd3f, sparse) and content (49b0dca, sparse). Facts that matter are indocs/development/launcher-reference.md(13 sections); the design indocs/development/plan.md. - Key findings: the launcher takes a
ss14://URI on its command line and forwards it to a running instance over a named pipe; the Windows bootstrap exe drops arguments, so the tool must callbin_x64\SS14.Launcher.exewithDOTNET_ROOTset; the game client stays open on "The server is full!" with a 30 s Retry timer and never retries by itself; its stdout is written tologs\client.stdout.log, which is the signal for success or failure; a launcher overlay left in an error state silently drops later connect commands. - Environment: cloud container blocks
hub.spacestation14.com(proxy 403) but reaches GitHub. uv upgraded 0.8.17 → 0.12.19 via pip to get Python 3.14.7 (the old uv only knew 3.14.0rc2). - Scaffold:
pyproject.toml(uv, ruff, pytest),src/ss14_autojoin/server.py(address parsing with the launcher's four test vectors, status parsing, free-slot logic, status fetch),cli.pywithstatusandwatch(poll and print), tests, CI workflow,CLAUDE.md.
2026-09-25 (later): first real logs from Windows¶
- The maintainer supplied
client.stdout.logfor a successful join to Lizard and for a "server is full" attempt (docs/development/fixtures/, redacted). The success log confirms the line wording from the engine source, including the quoted endpoints and the harmlessDisconnected, reason: "Connection attempt failed"of the losing IPv6/IPv4 candidate. - The failure log ends before any
net:line. Cause found inConnector.PipeOutput: the launcher writes the piped stdout into aFileStreamwith a 4 KiB buffer and never flushes, so a quiet failed client leaves its failure lines in memory. Consequence for the design: failure is detected by the absence of the success marker within a timeout, then the client is closed and the log read post-mortem (flush on exit unverified; new verification item 3). - Checked and ruled out:
SS14_LOG_CLIENT(unused by the engine),log.*cvars (server only), client--loglevel/--cvarflags (only the launcher builds the client command line). Root level is already Debug.
2026-09-25 (later still): the denial, seen¶
- The maintainer repeated the full-server attempt and copied the log after pressing Exit
(
docs/development/fixtures/client.stdout.full-after-exit.log). The buffer is flushed on client exit. The denial arrives during the handshake:Status changed to Disconnected, reason: "{\"reason\":\"Connect denied: The server is full!\",\"redial\":false,\"delay\":30}", thenRunlevel changed to: Initializeand an[ERRO] net: Exception during handshakeline with the same JSON. The parser in M2 has real text for both outcomes.
2026-09-26: the launcher log¶
- the reference launcher log (
docs/development/fixtures/launcher.log) shows a Steam launcher, 0.40.1.0, at<Steam library>\steamapps\common\Space Station 14 Playtest, same layout as the standalone zip, client gets--cvar branding.steam=true. Target server confirmed as Lizard, addressss14s://lizard.spacestation14.io/server(status URLhttps://lizard.spacestation14.io/server/status). - The launcher log has timestamps, the client PID (
Setting up manual-pipe logging for new client with PID) and the client's exit (EOF, ending pipe logging), so it is the clock for the attempt timeout. Update with a cached version takes 1.6 s, with a content download 8.2 s (39 blobs). - Decision: proceed with the Steam build; verification item 2 (command-line connect) is now the gating test.
- Added the Lizard address to the
server.pytest vectors.
2026-09-26 (later): the Steam launcher takes commands; discovery module¶
- The maintainer ran
bin_x64\SS14.Launcher.exe ss14s://lizard.spacestation14.io/serveragainst the running Steam launcher: the client started and attempted the join (denied, server full). The gating test passed; the join milestone is unblocked. He reports adotnet_x86folder in the install. - The maintainer asked for (1) a matrix of common install locations checked before asking, (2) a configuration window. Both recorded in the plan; the GUI moved into M3 as required.
- Built
launcher.py: install description (LauncherInstall), runtime folder detection, Steam library discovery throughlibraryfolders.vdf, root from the launcher log'sLaunch command, root from a running launcher process (psutil), common standalone folders, andfind_launcherin priority order.doctorCLI command prints the result. 54 tests pass.psutiladded as the first runtime dependency.
2026-09-26 (evening): cold start works; install layout confirmed¶
dirof the install:bin(2025 leftover),bin_x64,dotnet_x64,console.bat, the bootstrap exe. The earlierdotnet_x86was a misreading.- The command-line connect works with the launcher closed too: it starts, queues
randc<uri>, logs in, connects; client PID 5.7 s after start. Warm:Connect commandtoLaunch command3.2 s. The launcher log hasLauncher command: ...lines for pipe/command-line connects. Fixturelauncher.logextended. - Consequence: no "launcher must be running" precondition; restarting a stuck launcher with the URI is a clean recovery.
2026-09-26 (night): M2 code complete, untested on Windows¶
client.py: client log parsing (ClientLogState,DenyReasonwith escaped-JSON decoding), launcher log events with timestamps,LogTail(growth, recreation, partial lines) andLauncherLogTail(daily roll). Verified against all four fixtures: joined, truncated-while-open, full-after-exit, launcher log.joiner.py: the state machine with injected ports; 9 scripted scenarios (slot opens, full then join, timeout with post-mortem ban stops, unknown failures cap, no client appears, dropped command with and without restart, offline back-off and max attempts, panic bunker filter and stop, rejoin after kick).runtime.py: real ports (subprocess for the launcher command withDOTNET_ROOT, psutil for the client process, the two log tails).joinCLI command wired. 76 tests pass. Verification record item 7 is the first real run.
2026-09-26 (day 2): first real run, one wrong kill, the socket witness¶
- First
joinrun on Windows: discovery, slot detection (three attempts, each on a79/80poll), the connect command, PID pick-up and termination all worked. But the client log never flushed after a successful join either (lobby with the rules popup is quiet), the tool saw no success marker in 45 s, and killed a live session. The maintainer also read the behaviour as brute force; it was slot-driven, the server hovered at the cap. - Fix: (1) unknown outcome now keeps the client and stops the tool (
--on-unknown retryrestores the old behaviour); (2) new witness: the client's open UDP socket count via psutil (0 after a rejection since Lidgren peers are shut down, 1 while connected). Joined after 15 s of an open socket, failed after 12 s with none.probecommand to check the signal on Windows. 79 tests.
2026-09-26 (day 2, later): the socket witness is real¶
probeon Windows: connected clientudp_sockets=1every second, rejected clientudp_sockets=0, no elevation needed. The join/fail decision no longer depends on the client log flushing. Also fixed a patch that had not applied (theprobesubcommand and--on-unknownwere missing from the parser) and added a test tying the parser's subcommands to the dispatch table.
2026-09-26 10:35: first end-to-end join¶
join ss14s://lizard.spacestation14.io/server --verbose --max-attempts 3: poll78/80 slot free→ connect command → client PID 32008 after 2 s →joined (client kept a UDP socket open for 15 s)→ stop, game left running. 17 s from slot to confirmed join. M2 verified on Windows.
2026-09-26 (day 2, afternoon): M3 code¶
config.py(TOML settings, validation,joiner_config()),app.py(Tkinter window: settings panel with Browse/Detect, Start/Stop, Save, scrolling log; joiner in a thread, queue to the main loop),guicommand andss14-autojoin-guiscript,build.py(PyInstaller one-file:SS14AutoJoinwindow build andss14-autojoinconsole build), CIwindows-appjob uploading both exes on push. Linux console build verified: 17 MB,--versionandstatusrun. 86 tests. Verification record items 9 and 10 for the Windows check.
2026-09-26 10:42: window and exe verified¶
- The maintainer ran the window: detection pre-filled the Steam folder, Save wrote the config, Start joined Lizard
(77/80 → PID after 2 s → joined at 15 s) with the log in the window. The PyInstaller window build runs.
M3 verified. Added
notify.py: three alert sounds on a join (--quietin the console), a bell and window raise when the loop stops.
2026-09-26: join sound option and fanfare¶
- The maintainer asked for a GUI switch for the join sound and a free trumpet success sound. Added
soundto the settings and window,--quietstays for the console.tools/make_fanfare.pysynthesizesdata/fanfare.wav(1.47 s, 127 KB, public domain);notify.play_successplays it (winsound on Windows, afplay/paplay/aplay elsewhere, bell fallback); PyInstaller bundles the data folder. 88 tests.
2026-09-26: fanfare verified from the exe; window bell removed¶
- The maintainer: the fanfare plays from the built window and the setting is respected. The
donehandler still rang the Tk bell; removed, the window is only raised.
2026-09-26: app icon¶
tools/make_icon.pydraws a ring space station (1024 px supersampled, box-filtered to 256/128/64/48/32/16) and writesdata/icon.pnganddata/icon.icowith a pure-Python PNG and ICO writer. The window sets it throughiconphoto(andiconbitmapon Windows);build.pypasses it as the exe icon. 89 tests.
2026-09-26: icon not shown in the window; ICO format¶
- The maintainer: the exe's Properties dialog shows the icon, but Explorer's list, the window title bar and the taskbar do not. Explorer is the icon cache (same path as the icon-less build). The window was our bug: Tk's Windows icon reader only understands classic bitmap ICO entries, and the ICO had PNG-compressed ones; the exception was swallowed. Now 256 px stays PNG, the rest are 32-bit bitmaps with an AND mask; the window sets the ICO before the PNG and logs icon failures. Headless Tk (Xvfb) loads the PNG at 256 px.
2026-09-26: icon, round three¶
- The maintainer copied the exe to a new folder: Explorer shows the icon (cache confirmed) and the taskbar shows it
(from the exe resource). The title bar still did not, in a build predating the diagnostic line. Python
3.14's bundled Tk is 9.0.4, so Tk's own icon path is suspect. Added a Windows API fallback: after the window
is mapped,
WM_SETICONbig and small on the frame window via ctypes, logged in the window.
2026-09-26 11:28: icon everywhere¶
- With the WM_SETICON fallback the title bar shows the icon too. Root cause on record: Tk 9.0.4 on Windows
accepts
wm iconbitmapwithout applying it to the title bar. Verification record item 12 closed; nothing is open.
2026-09-26: 1.0.0 release preparation¶
- Personal names, account ids and machine-specific paths removed from the repository (fixtures use
C:\Users\player,D:\Games\SteamLibrary; documents use<user>,<Steam library>, "the maintainer"). - Documentation split:
docs/is the MkDocs Material user site (getting started, how it works, settings, command line, troubleshooting, FAQ) published to GitHub Pages bydocs.yml; the development record moved todocs/development/(plan, launcher reference, decisions, verification record, history, fixtures). - Release automation:
release.ymlpublishesv<version>with Windows and Linux binaries, checksums and notes generated from merged pull requests (.github/release.ymlcategories) whenever a new version lands onmaster. CI also builds the docs strictly. Issue templates (join problem, launcher not found, other platform, feature request), a pull request template andCONTRIBUTING.mdadded. README rewritten with the Windows-only notice, the documentation link and an AI disclosure. Version 1.0.0.
2026-09-26: after 1.0.0¶
v1.0.0published by the release workflow with Windows and Linux binaries and checksums; documentation site live.SECURITY.md, Dependabot, and least-privilegepermissionsin the workflows (CodeQL alerts) followed in small pull requests.- Towards fewer SmartScreen prompts: Windows builds now carry a VERSIONINFO resource (product, version,
company, description; generated by
build.py), and a winget packageDevigami.SS14AutoJoin(portable) is prepared underpackaging/winget/with a generator and an automatic submission job for later versions. Code signing through SignPath Foundation is being applied for by the maintainer.
2026-11-01: winget manifest schema bump¶
- The 1.0.0 submission to
microsoft/winget-pkgs(PR 441430) waited five weeks for a moderator and was then bounced by the repository's automation: manifest schema 1.10.0 had been deprecated meanwhile, 1.28.0 asked for. The 1.28.0 schemas (frommicrosoft/winget-cli,schemas/JSON/manifests/v1.28.0/) add no required field and keep every field the package uses, so the fix is the declared version only. Generator, committed manifests and tests moved to 1.28.0 (validated against the downloaded schemas); the packaging README records how to update an open pull request in place rather than opening a new one.