[Chichimokers]

Docs: AoE2:DE Automatch2 implementation findings

This PR adds practical notes from implementing and testing a minimal AoE2:DE 1v1 Automatch2 flow against a local RLink-compatible server. It complements the existing endpoint reference with observed client behaviour, protocol gotchas, and a clarification for the advertisement field layout.

What is added

• src/rlink/game/automatch2/notes.md (new) - end-to-end flow, polling response semantics, Automatch2GameMessage shape, advertisement/automatch identification, minimal 1v1 policy, and ideas for future work.
• src/SUMMARY.md - registers the new notes page in the sidebar. The polling, stoppolling and updateStatus pages under automatch2 were already listed; this PR only adds the "Implementation notes" entry.
• src/rlink/game/advertisement/getadvertisements.md - adds an observed field-layout note. The existing sample uses the 24-field layout; in our tests the current PC client rejected that layout with response was not formatted correctly. A 27-field layout was accepted. The note documents both and lists the accepted field order.

Key findings documented

• The host receives the matched polling response before the advertisement exists, then creates it via /advertisement/update (AoE2:DE does not use /advertisement/host for this flow).
• Polling response field 1 is elapsed wait seconds; field 4 is the host profile ID.
• Relay IPs must be resolved per request from the local address the client used to reach the server. Synthetic /10.0.11.x addresses can make the client attempt DNS resolution and fail.
• Automatch2GameMessage is a JSON object with named fields; matchMembers is an array of objects, not positional arrays.
• matchtype=19 and/or a positive automatchPoll_id identify automatch; matchtype=1 + maxplayers=4 + empty map is an ordinary party/session.
• Automatch joins bypass the random advertisement password; teams come from the polling response.
• The 27-field advertisement layout is required by the tested client; a wrong layout breaks ordinary custom games too, not just automatch.

Context / testing

Tested with two AoE2:DE clients in the Ranked/Scored Multiplayer 1v1 Automatch flow against a local server, with battle-server-manager running. The reference implementation is a simple first pass (earliest-host pairing, canonical 1v1 queue 6, Arabia, 2 players, team size 1). It intentionally leaves room for MMR, more maps/queues, host migration, NAT/relay fallback, and better retry/cancellation behaviour.

Reference implementation/PR: Chichimokers/ageLANServer#1

Validation

• mdbook build passes (mdBook 0.5.2, the version pinned in .github/workflows/mdbook.yml), including the SUMMARY and link preprocessors.
• dprint check passes with the plugin versions and settings from .dprint.json (the lint.yml gate).

These are empirical notes, not a claim that every client version behaves identically. Feedback and corrections are welcome.

[simonsan]

Thanks a lot! 🚀 <3