docs: add windows native test runbook #1

jann · 2026-04-14T13:40:16+02:00

jann commented

2026-04-14 13:40:16 +02:00

Who this is for

Jakub or kolega 4 — anyone on the team with a Windows 10/11 box and a willingness to install Visual Studio Build Tools 2022 for an hour. It is the missing mirror of the existing m2dev-client/docs/linux-wine.md: we already know the client reaches character selection under Wine on Fedora 41, but nobody has validated it on actual Windows.

Why we need it now

Metin2Launcher.exe (from jann/metin-launcher) has only been exercised in the Linux+Wine path. Velopack, single-file bundling and the Avalonia GUI all have Windows-specific failure modes (SmartScreen, DPI scaling, Defender quarantine, UAC write-through) that Wine simply does not exercise.
The C++ client is Windows-first per this repos AGENTS.md. A reproducible "does it build and run on plain Windows" procedure is a prerequisite before we start shipping updates via the launcher.
When the launcher or client breaks on a testers machine we want a single document that tells them exactly what to capture. Today that is tribal knowledge.

What the runbook covers

Prereqs with exact installer URLs (VS Build Tools 2022, Git for Windows, .NET 8 SDK, PowerShell 7).
Cloning m2dev-client-src, jann/metin-launcher, and the runtime m2dev-client into a safe path (C:\dev\metin, not OneDrive/Documents/Program Files).
Step-by-step MSVC build of Metin2.exe in RelWithDebInfo with Tee-Object for the build logs.
dotnet publish of the launcher with PublishSingleFile + IncludeNativeLibrariesForSelfExtract.
First run: expected launcher GUI, the "Server unreachable — using local client" fallback (DNS for updates.jakubkadlec.dev is still broken on purpose), Play button, server picker, register + character create + enter map.
What logs to capture (launcher.log, syserr.txt, packetdump.txt, CMake build logs, dxdiag) plus a Compress-Archive one-liner that zips them for filing.
A "Windows-specific gotchas" section distilled from linux-wine.md and general legacy 32-bit-client experience: SmartScreen, UAC + Program Files, OneDrive, DirectX End-User Runtimes, DPI scaling, firewall prompt, 32/64-bit mixups, non-ASCII usernames.
Rollback / reset procedure that does not nuke the 4 GB of assets.
Where to report findings: new issue in metin-server/m2dev-client-src, label windows-test.
An "absolute-minimum fast path" appendix for when you just want to run the prebuilt launcher over the existing client folder.

Notes

Aligned with AGENTS.md in this repo (Windows-first, no protocol or source changes).
Pure documentation — no code, no CI touch, no build verification performed from this branch.
Complements m2dev-client/docs/linux-wine.md and m2dev-client/docs/update-manager.md rather than duplicating them.

## Who this is for Jakub or kolega 4 — anyone on the team with a Windows 10/11 box and a willingness to install Visual Studio Build Tools 2022 for an hour. It is the missing mirror of the existing `m2dev-client/docs/linux-wine.md`: we already know the client reaches character selection under Wine on Fedora 41, but nobody has validated it on actual Windows. ## Why we need it now - `Metin2Launcher.exe` (from `jann/metin-launcher`) has only been exercised in the Linux+Wine path. Velopack, single-file bundling and the Avalonia GUI all have Windows-specific failure modes (SmartScreen, DPI scaling, Defender quarantine, UAC write-through) that Wine simply does not exercise. - The C++ client is Windows-first per this repos `AGENTS.md`. A reproducible "does it build and run on plain Windows" procedure is a prerequisite before we start shipping updates via the launcher. - When the launcher or client breaks on a testers machine we want a single document that tells them exactly what to capture. Today that is tribal knowledge. ## What the runbook covers - Prereqs with exact installer URLs (VS Build Tools 2022, Git for Windows, .NET 8 SDK, PowerShell 7). - Cloning `m2dev-client-src`, `jann/metin-launcher`, and the runtime `m2dev-client` into a safe path (`C:\dev\metin`, not OneDrive/Documents/Program Files). - Step-by-step MSVC build of `Metin2.exe` in `RelWithDebInfo` with `Tee-Object` for the build logs. - `dotnet publish` of the launcher with `PublishSingleFile` + `IncludeNativeLibrariesForSelfExtract`. - First run: expected launcher GUI, the "Server unreachable — using local client" fallback (DNS for `updates.jakubkadlec.dev` is still broken on purpose), Play button, server picker, register + character create + enter map. - What logs to capture (`launcher.log`, `syserr.txt`, `packetdump.txt`, CMake build logs, `dxdiag`) plus a `Compress-Archive` one-liner that zips them for filing. - A "Windows-specific gotchas" section distilled from `linux-wine.md` and general legacy 32-bit-client experience: SmartScreen, UAC + Program Files, OneDrive, DirectX End-User Runtimes, DPI scaling, firewall prompt, 32/64-bit mixups, non-ASCII usernames. - Rollback / reset procedure that does not nuke the 4 GB of assets. - Where to report findings: new issue in `metin-server/m2dev-client-src`, label `windows-test`. - An "absolute-minimum fast path" appendix for when you just want to run the prebuilt launcher over the existing client folder. ## Notes - Aligned with `AGENTS.md` in this repo (Windows-first, no protocol or source changes). - Pure documentation — no code, no CI touch, no build verification performed from this branch. - Complements `m2dev-client/docs/linux-wine.md` and `m2dev-client/docs/update-manager.md` rather than duplicating them.

jann added 1 commit 2026-04-14 13:40:17 +02:00

docs: add windows native launch test runbook a974836db1

jann referenced this pull request from metin-server/m2dev-server

2026-04-14 15:04:31 +02:00

handoff: server down + DNS blocker + 3 PRs k merge + write access request #2

jann referenced this pull request

2026-04-15 13:00:18 +02:00

client: hardcoded pack/property.pck path bypasses m2p loader #2

This pull request can be merged automatically.

This branch is out-of-date with the base branch

You are not authorized to merge this pull request.

View command line instructions