docs(website): add illustrated launcher guide under Get started #709
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!709
Loading…
Reference in a new issue
No description provided.
Delete branch "bibiburl/Longshot:docs/launcher-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: low · Tested on: Linux, Chromium 153, website and game-free checks · Needs: review of this rebased head; inherited test/source-review failures resolved before deployment
Why
Players need an illustrated guide to choosing a player, finding their save and using the launcher, accessible from Getting started. Add a Launcher section that explains the player picker, the three home screens, updates, saves, privacy controls and the Steam Deck flow.
See LongshotLauncher issue #68. Its screenshots are HTML mockups, not a released launcher. The guide uses direct player instructions and explanatory picture captions, with one short opening preview notice and links to the current installation and save guides. Approved by Jordan at
cb983fce; rebased without changing its own documentation diff onto839a8cc4for current validation; this PR is not a deployment request.What changed
Added Get started → Launcher at
/launcher/, plus a Launcher card at the end of Install. The guide has a three-step navigation strip, an explanation of Kid / Normal / Advanced homes, and eight inline pictures beside the controls they explain. Each picture has descriptive alt text, a caption explaining the controls and a full-size link.docs/launcher.md: canonical source, including direct instructions for player selection, manual versus automatic updates, shared builds versus separate saves, privacy controls and useful help links.docs/getting-started.md,website/src/content-pages.ts,website/astro.config.ts: entry point, source registration and sidebar placement.website/src/styles/content.css: responsive flow cards, a grouped home-screen comparison and captioned figures, using existing theme tokens.docs/images/launcher-preview/: eight unchanged issue #68 mockups (player picker, three homes, saves, storage, telemetry and splash), with original attachment URLs, dimensions and SHA-256 hashes. The existing asset integration serves them locally; generated copies are ignored by Git.website/README.md: maintenance guidance and the requirement to verify a named launcher version before presenting this as a released-feature walkthrough.No new JavaScript, dependencies or game-derived assets. Mockups load lazily with reserved dimensions and retain their source attribution/provenance; they are separate from the released-UI screenshot manifest. Existing UI screenshots retain their version captions and provenance. This branch starts from current main independently of the earlier website PRs.
Screenshots
Rebased guide @
661277a4, local built site. These are design mockups of the upcoming launcher; the opening preview notice remains. All eight lazy-loaded images were decoded before capture.Measurements
Verdict: the requested website changes pass their focused regressions, built-page checks and integration checks. Inherited failures are identified under Testing; this is not a gameplay measurement.
Hardware: Linux x86_64, Node/npm with the repository’s pinned dependencies, Chromium 153 for browser checks
Scene: local built website at desktop 1440 px and mobile 390 px
Method: functional checks against untouched main @
839a8cc4and this PR @661277a4; no performance comparison.How to reproduce: from
website/withnpm run build,npm run check,node --test tests/*.test.ts; from the repository root withpython -I -B tests/run_all.py.839a8cc4661277a4Flags and settings
None. No game, launcher or deployment setting changes.
Testing
Tested: current-head full website suite, static build/generated-page check, complete game-free suite, image integrity and
git diff --check. Browser checks at 1440/390 px in light/dark show no horizontal overflow. All eight original mockups decode successfully at 960 px wide; fresh full-page screenshots are above. The rebased PR preserves the original documentation/assets diff. Earlier keyboard/search and axe results were recorded atcb983fce; they were not rerun as new accessibility audits here.The same existing
graphics-settings.test.tsfailure, HDR Native condition accepts current prose but remains required (Missing expected exception), reproduces on untouched main @839a8cc4. The generated-page/source/link checks pass;npm run checkstill exits nonzero on that test. The earlier public-copy publication violations no longer reproduce on this baseline.The complete game-free suite has the same 17 failing files and 74 skips as untouched main:
tests/test_appimage_player_build.py,tests/test_bake_portability.py,tests/test_crash_dialog.py,tests/test_crt_options.py,tests/test_env_on.py,tests/test_forge_pr.py,tests/test_lift_cleanup_error.py,tests/test_linux_preflight.py,tests/test_linux_update.py,tests/test_make_game_cache.py,tests/test_missing_nup.py,tests/test_mods_size_table.py,tests/test_options_budget_once.py,tests/test_pipeline_tour.py,tests/test_readback_late.py,tests/test_vk_occlusion_queries.py,tests/test_vk_pgo.py. Skips are missing local tools/headers or platform-specific checks, not passes.The guide-source CI failure also reproduces on untouched main: 15 recorded Graphics-menu inputs have drifted since the
e9bed614image review. Existing image integrity, screenshot-checker regressions and capture-isolation regressions pass.docs/images/guide/source-review-microphone-device-limit.mdalready records that the old Graphics illustration describes superseded VRAM-budget help. This update does not certify it as current, reset its fingerprints or build a game/menu capture. A source-and-image refresh remains separate work; the external Launcher source check is not performed here.Combined integration: #611 + #638 + #709 merge cleanly on main @
839a8cc4, build 19 pages, pass generated-page checks and run 139 website tests successfully with the same one inherited HDR assertion. Browser interaction confirms mouse/keyboard tab changes update#release-rcand#release-stable. #768’s alternative hero is not included in this combination; earlier screenshots of that four-PR combination remain historical evidence only.Not tested: real Actions token execution, deployment/runner queues, notification delivery, Cloudflare production, game or Launcher runtime, Firefox/Safari, Windows/Steam Deck. No game was built or launched.
Must be tested:
Forgejo Actions and Cloudflare production, by hand after approved rollout: a maintainer checks production downloads and release refreshes, including one controlled refresh failure/recovery, expecting correct channel downloads and one Actions-owned incident that closes on success. Resolve the inherited website-test and Graphics-image/source-review failures before deployment. This update does not deploy the website.
Windows/Linux/Steam Deck, by hand before removing the preview notice in a future change: a maintainer checks the guide against a named launcher release, expecting controls and instructions to agree. Retain the notice until then; a runtime check is not required to merge this preview guide.
Risks
What could break: readers could mistake a proposal for a shipped feature. The opening preview notice identifies the upcoming launcher and its design mockups, and the Install entry also notes its preview status. Practical guidance about saves, shared-build updates and PC-wide privacy controls remains explicit. Local picture files, their source manifest and the guide must stay in sync and be checked against the eventual launcher release; captions explain the controls shown.
Turning it off: revert this documentation change.
Compatibility: nothing changes for saves, options, caches, renderer ABI, launcher behavior or builder tools. Existing guide links and source ownership are preserved.
Issues
See MagicBeanDev/LongshotLauncher#68
Related implementation: MagicBeanDev/LongshotLauncher#55 and MagicBeanDev/LongshotLauncher#59. This documentation does not close the redesign issue or claim those features have shipped.
Checklist
Everyone
type(scope): description) of the status line's type.main(e090cc48, fetched again before committing).python -I -B tests/run_all.pypasses (any failure that also fails onmainis named above).third_party/untouched (a new folder with aPROVENANCE.mdinstead).When it applies
Assisted-by:/Co-Authored-By:trailers.First website preview for this draft. These are screenshots of the documentation page, not a running redesigned launcher. The guide links to the design mockups in Launcher issue #68.
After: this PR @

e230d576, Launcher overview, 1440 × 1000, light.Full-page desktop light and dark (1440 px), and mobile light (390 px), at the same PR commit:



Install page, same 1440 px viewport and light theme. The existing launcher screenshots remain version-captioned examples.


Before: main @
e090cc48.After: this PR @
e230d576, with the Launcher sidebar item and section.Added the first-attempt screenshots to the main description: desktop overview, full-page light/dark and mobile guide, plus the Install before/after comparison. Validation results and existing baseline failures are recorded there. Keeping this PR WIP as requested; the guide explicitly labels Launcher #68 as a proposed redesign.
Updated the guide itself with eight inline design mockups from Launcher issue #68. Each has descriptive alt text, a design-preview caption and a full-size link; all images are served locally and preserved unchanged with source URLs and SHA-256 provenance.
After: this PR @
40e5af86. These screenshots show the illustrated website guide, not a released launcher.Validation repeated: build passes; all eight images load from local assets and match their original hashes; no horizontal overflow at 1440/768/390/320 in either theme; four axe audits report zero violations. Keyboard full-size image navigation works. Existing baseline failures remain unchanged. Keeping this PR WIP.
Updated the main post for
40e5af86: the guide now contains eight captioned mockups with local full-size links, and the main-post screenshots show the illustrated version. Recorded repeated validation and retained the WIP status.Updated the guide with direct player instructions and captions that explain each screen. One opening preview notice identifies the upcoming launcher; save, update and privacy guidance remains explicit. The development-status section is now useful help links.
Current screenshots at
cb983fce(the launcher pictures are design mockups). These replace the earlier guide screenshots in the main post.Full-page exports and updated Install entry
Website build passes. Layout and accessibility checks pass; existing website and game-free test failures are unchanged from the base. This remains WIP.
WIP: docs(website): add launcher UI preview under Get startedto WIP: docs(website): add illustrated launcher guide under Get startedReviewed at
cb983fce: good to go in from my side. It merges cleanly with main and with #768, it's self-contained, and the opening notice says the pictures are mockups of the upcoming launcher. I'll approve once it's out of WIP.Review drafted with Claude Code and checked by Jordan.
Preparing this for final review following Jordan’s feedback. Normalised the description checker’s Measurements and Must be tested sections; the guide, screenshots and recorded validation are unchanged at
cb983fce. This does not request deployment.WIP: docs(website): add illustrated launcher guide under Get startedto docs(website): add illustrated launcher guide under Get startedReviewed at
cb983fceand still the same head: approved. Drafted with Claude Code and checked by Jordan.cb983fce43661277a4a2New commits pushed, approval review dismissed automatically according to repository settings
Rebased the approved guide onto main @
839a8cc4; new head661277a4preserves the PR’s documentation/assets diff. Refreshed the main post with full-page light/dark screenshots at 1440 and 390 px. All eight original mockups decode correctly; no horizontal overflow.Build and generated-page checks pass (18 pages). Website tests: 82 pass, the same one HDR-condition assertion as main. Game-free: 535 pass, 17 fail, 74 skip, with identical failing files to main. The guide-source CI failure is inherited Graphics screenshot drift (15 inputs), not changed Launcher mockups; the source/image review notes and limits are explicit in the main post. No capture fingerprints were reset, no game was built/launched, and no website deployment occurred.
Re-approving after the rebase onto main @
839a8cc4(my approval ofcb983fcewas dismissed by the force-push).git range-diffshows all three commits' patches unchanged (=), and the PR's whole diff matches cb983fce's except the index lines of the three website files main changed underneath. It still merges cleanly with #768. The red Guide screenshots check is main's:check_guide_screenshots.py --review-sourcesgives the same 16 settings-graphics.png review issues on main @839a8cc4and on this head.Drafted with Claude Code at Jordan's request.
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.