WIP: docs(website): add an experimental multiplayer guide #962
No reviewers
Labels
No labels
area/accessibility
area/audio
area/input
area/install
area/menu
area/renderer
area/saves
area/tooling
area/upscaling
beanstalk: approved
beanstalk: failed
beanstalk: needs approval
beanstalk: running
beanstalk: tested
ci: approved
good first issue
gpu/amd
gpu/igpu
gpu/intel
gpu/nvidia
help wanted
kind
bug
kind
chore
kind
docs
kind
feature
kind
performance
kind
question
needs measurements
platform/linux
platform/macos
platform/steam-deck
platform/windows
preview
priority
critical
priority
high
priority
low
regression
risk
high
risk
low
risk
medium
status
blocked
status
confirmed
status
duplicate
status
invalid
status
needs-info
status
wontfix
ci: approved
No milestone
No project
No assignees
2 participants
Notifications
Due date
No due date set.
Dependencies
No dependencies set
Reference
MagicBeanDev/Longshot!962
Loading…
Reference in a new issue
No description provided.
Delete branch "bibiburl/Longshot:docs/multiplayer-guide"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Type: docs · Risk: medium · Tested on: Linux, Chromium (website only) · Needs: #68 merged, final build/UI and publication checks
Why
Players currently have to piece together the co-op discussion, technical reference and tester guide to start a session. They need a clear route through temporary saves, room setup and consent before trying the experimental features. See #463, #355 and #68.
Keep this PR WIP until #68 is merged and the publication checks below are complete. Merging this PR publishes the Multiplayer section and header link automatically through
website.yml; there is no separate deployment approval afterwards. The header link is retained for that publication point. Multiplayer is experimental, off by default and targeting 3.1.0 through #68; a target is not a release promise.Mooki reviewed every page and confirmed the consent, save-safety and networking distinctions. The requested settings-file and link corrections are applied in
c525656d. This was a comment review, not an approval.What changed
Added a Multiplayer section to the main navigation and documentation sidebar, with five player-facing guides:
Temporary-copy acceptance is see and talk only: it does not authorize progress sharing, pools, transfers or Go to friend. Normal-save sharing can persist changes; a backup is not temporary-session isolation. These distinctions stay explicit throughout the guide.
The canonical pages live in
docs/multiplayer/, registered throughwebsite/src/content-pages.ts. The unpublisheddocs/multiplayer/README.mdrecords pinned sources and the remaining content checks. Website workflow path filters include this directory so later documentation-only changes build the site. Settings-file guidance links the README’s Where the files go, covering OS and launcher differences; player-facing playtest/build/reporting links point to #68. The backup and relay references are pinned to the reviewed commit until #68 is merged. Relay setup requires a matching checkout containing multiplayer support, without assuming every release has it.Sources: plan #463, behaviour, networking, technical reference at 25746346, historical playtest #355, base #68, and the draft tester guide, revision 03ca1a12.
Menu positions, exact build-mismatch messages, invite codes, UPnP, shared time, shared enemies and an official relay are not documented as settled features. In-game pictures will follow once the layout is stable and the agreed build can be captioned accurately. The screenshots below show the website itself.
Measurements
Nothing to measure in the game: documentation, website navigation and guide styling only. No gameplay or networking performance claim.
Flags and settings
None. Existing playtest settings are explained; this PR changes no game default or runtime switch.
Testing
Tested:
23144a3ahas an identical tracked source tree to the testedc525656d(git diff c525656d HEADis empty). The checks and guide screenshots below are from that identical source tree.npm run build: passed atc525656d; the previously tested baseline ismain @ a8a30c22, with 23 pages versus 18.npm run check: run onc525656d; the site audit passes; website tests are 101 passed / 1 failed on both revisions. The existing failure isgraphics-settings.test.ts: “HDR Native condition accepts current prose but remains required”.python -I -B tests/run_all.py: rerun onc525656d, 551 passed / 18 failed / 76 skipped, matching the previously tested baselinea8a30c22; identical failing test files, no branch-only failures (listed below).--review-sourcesreports the same 19 existing Graphics source-review mismatches on both revisions; Launcher source review was not performed. Review hashes were not reset.git diff --check: passes. No additional test run was needed for the exact restoration of the tested source tree.Existing game-free failures on both main and this PR
tests/test_appimage_player_build.pytests/test_bake_portability.pytests/test_crash_dialog.pytests/test_crt_options.pytests/test_env_on.pytests/test_lift_cleanup_error.pytests/test_linux_preflight.pytests/test_linux_update.pytests/test_make_game_cache.pytests/test_missing_nup.pytests/test_mods_size_table.pytests/test_options_budget_once.pytests/test_pipeline_tour.pytests/test_readback_late.pytests/test_run_all_changed.pytests/test_vk_occlusion_queries.pytests/test_vk_pgo.pytests/test_walk_key.pyNot tested: no game was built or launched, and no multiplayer, save recovery, relay or direct connection was exercised in this task. Behaviour is documented from the linked sources. No live deployment or hosted PR preview has been requested.
Must be tested:
By hand, documentation owner before ready/merge: confirm #68 is merged, rebase onto the current main and check its actual playtest/release availability, expecting every public build link and availability statement to match what players can obtain. Then verify and switch the two pinned technical references to main’s
docs/coop.md. A merge into main alone does not prove a Release or Nightly is available.By hand, co-op author on the agreed Linux/Windows candidate builds: walk through copy → room → acceptance → return, checking the action labels, normal-save/copy distinction, Friend information and host setup against these pages. Expect the documented restrictions and recovery behaviour; correct the prose before marking this PR ready.
By hand, documentation owner before publication: confirm the available playtest/release entry point, then add version-captioned UI pictures with secrets hidden when the layout settles, expecting the linked build and its controls to match the guide. Keep future features and an official relay unpromised until confirmed.
Risks
What could break: experimental behaviour and menu wording can outpace the guide; incorrect save instructions would matter to players. The draft is explicitly marked experimental, starts with temporary copies, and records its source revisions for review. The extra navigation entry also needs to remain usable at narrow widths.
Turning it off: revert this documentation commit.
Compatibility: no changes to saves, options, caches, renderer ABI, game builds or launcher behaviour.
Issues
See #463 — plan and availability.
See #355 — playtest and behaviour evidence.
See #68 — multiplayer integration target; this documentation PR does not implement or close it.
Screenshots
Local builds: Before: main @
a8a30c22; After: this PR @c525656dfor the overview and connection-guide captures. Current head23144a3arestores that identical source tree. Desktop viewport 1440 × 1000; phone viewport 390 × 844. Full-page captures show the current wording. The unchanged navigation comparisons and mobile-menu capture retain their originald23583a7captions.Phone: light, dark and the new navigation section
Navigation comparison on Install: same viewport and page, both themes
The local Astro preview does not serve the download Worker endpoint, so both Install captures show the existing version-metadata fallback. This PR does not change that feature.
Connections & help: hosting and reporting
Checklist
Everyone
type(scope): description) of the status line's type.main: the tested base remainsa8a30c22; refresh after #68 merges, before marking ready.python -I -B tests/run_all.pypasses (any failure that also fails onmainis named).third_party/untouched (a new folder with aPROVENANCE.mdinstead).When it applies
Assisted-by:/Co-Authored-By:trailers.Added the built-site screenshots to the main description: full-page Multiplayer overview in light and dark, 390 px phone views, and matching before/after navigation captures. The final draft is
d23583a7on maina8a30c22. Builds and link checks pass; existing website and game-free failures are named with matching baseline results. Keeping this PR WIP as requested, pending co-op content confirmation.Thanks, this is a really good first pass. I checked every page against the co-op technical reference on the current co-op line and against main. Almost all of it is right, including the parts that are easy to blur: see-and-talk on a copy versus progress on a normal save, a backup not being isolation, direct connections still needing a relay, and acceptance repeating when rules change.
To fix
longshot_options.iniis (connections.md, "Host from your game"). "In the game folder" is only right on Linux and for a game started by itself. On Windows, when the launcher starts the game, the file is in%APPDATA%\Longshot(a portable launcher's inLongshotLauncher-data\user), since #729. Rather than naming a folder, I'd link the README's "Where the files go": https://git.magicbean.dev/MagicBeanDev/Longshot/src/branch/main/README.md#where-the-files-go. The draft tester guide had the same mistake; I'm fixing it there too.docs/coop.mdon the branchcoop-playtest-r9, which stops moving when 355 closes. Pin them to a commit, as your README already does, until 68 is merged, then use main'sdocs/coop.md.Before this leaves WIP
website.ymldeploys on every push to main, so merging puts a Multiplayer section and a header link live while co-op is in no release or Nightly yet. I'd merge after 68 is on main, or keep the sidebar section and leave the header link out until then.Checked and correct, so you don't have to re-check them: Friend information starts at 0 and 3 shows both ages; Friend labels is the player's own Off, Names, Names and arrows; the copy's button is Accept to see and talk; Temporary save works outside a room only;
coop-backupsits besidesaveand nothing from the room is applied until it is made; Go to friend is normal saves only; the kit flow, including that accepting again is not a refill; what the relay can and cannot see; direct connections off by default, the address warning and the relay fallback; and the two cross-links (../updates-and-saves.md,../reporting-and-contributing.md) resolve on main.CI: the red "Guide screenshots" check fails the same way on main (the 19 Graphics mismatches you named), and "not mergeable" is only the
WIP:title; a trial merge into current maina8a30c22is clean.Coming up that you already mark as not settled: the Direct connections row moves under an Advanced heading, refusals get a next step, the build-mismatch message, invite codes and UPnP. Co-op tab pictures at Small, Medium and Large from a demo room are being made now; I'll send them when the layout settles.
Addressed the review in
c525656d: settings-file guidance now links the canonical platform/launcher locations; all player-facing playtest, build and results links point to #68; backup and relay references are commit-pinned. Relay instructions now require a matching checkout containing multiplayer support. The description and maintenance ledger explicitly keep this WIP until #68 merges, with final availability checks and a warning that merging publishes the website. Refreshed overview and connection-guide screenshots are in the main post. Build and link audit pass; website tests remain 101/1 and game-free checks 551/18/76, matching the documented baseline failures.Added Nightly feedback guidance under Connections & help in
5c19b93c. It asks for both players’ exact build versions, what worked, regressions and connection/save setup, and links to individual bug reports or the multiplayer PR for session summaries. It explicitly asks players to confirm that their agreed Nightly contains multiplayer. The current full-page connection-guide screenshots are in the main description. Build and all 1,387 local links/assets pass; website tests retain the single documented baseline HDR-condition failure. Still WIP until #68 merges and publication checks are complete.Removed the Nightly feedback addition in
23144a3aas requested. The PR now contains only the multiplayer guide and the corrections from mooki’s review. Restored the matching connection-guide screenshots and removed the feedback section from the main description. The tracked source tree is identical to the previously testedc525656d. Keeping this PR WIP.View command line instructions
Manual merge helper
Use this merge commit message when completing the merge manually.
Checkout
From your project repository, check out a new branch and test the changes.