fix(website): refresh the Graphics guide and document Custom HUD controls #2013
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
3 participants
Notifications
Due date
No due date set.
Dependencies
No dependencies set
Reference
MagicBeanDev/Longshot!2013
Loading…
Reference in a new issue
No description provided.
Delete branch "Phishinabowl/Longshot:fix/graphics-guide-hud"
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?
Summary
Continues Mooki's Graphics guide refresh. This branch preserves all of Mooki's commits, including the capture helper fixes for the banner and modular Insert menu.
The Settings guide now shows a fresh Graphics capture from main
f1f2dc5b(nightly 680), with matching caption and source provenance. The website recognizes the condition shared by the nine Custom HUD sliders and Reset HUD placement. It renders the registered reset action, and the guide tests now count only generated setting disclosures and check the canonical image URLs.The visible HUD badge includes the
HOS_WIDE_UIoverride condition. The guide uses neutral wording for the Sprint note-wait behavior so the published Settings page passes the site's terminology audit. The capture helper reports unsupported older source layouts, checks logo dimensions before allocation, and cleans up the PNG, SDL and ImGui resources when capture fails.Read first:
docs/user/images/guide/source-review-fullscreen-monitor.md,website/src/repo-docs/graphics-settings.ts, andwebsite/tests/hud-visibility.test.ts.How to reproduce
On main at
f1f2dc5b, runpython -I -B scripts/check_guide_screenshots.py --review-sourcesand runnpm run buildfromwebsite/after installing the locked dependencies. The guide guard reports 37 source or fixture mismatches, and Astro stops at the missing visibility condition for Hearts and magic horizontal. With this branch, the Longshot guide check passes and the Settings page builds.Testing
Tested: Windows and Linux (WSL), using Node 24.22.2. The website build generated 20 pages, the site audit passed, and the complete Linux website suite passed 90 of 90 tests. Windows passed 89 of 90. The save ZIP fixture expects LF in Python stdout and receives CRLF on both main and this branch. The HUD regression reproduced the missing-condition error on main and passes with the fix.
The Linux SDL2 software fixture rendered Graphics at 1280×720. The guide integrity and Longshot source checks and all 14 checker regressions passed. Launcher source review was outside this capture and was reported as not checked. The Settings preview was verified in Edge at desktop and mobile widths in light and dark mode. The caption, alt text, and link to the full-size PNG were checked.
The live Graphics view was also compared on Windows using the prepared Sprint test build (game at
cd57d785, renderer with the UI changes incbfa7a18). The Graphics tab's source is unchanged between those revisions and the fixture's sourcef1f2dc5b. The maintainer checked the six tabs, first setting labels and order, Quality preset help and keyboard prompts against the guide image and confirmed they match. The guide image is still the nightly 680 game-free capture.The Linux capture smoke check on the review fixes linked the modular menu, verified that the logo drew, and rendered a PNG identical to the published guide image. The guide check passed with the verified fixture hashes. The site build, site audit, 90 Linux website tests and desktop/mobile light/dark preview passed with the revised badge.
Forgejo's guide screenshot check and website build and checks both passed on
d8d9edcd.The strict game-free runner used by
mise run testcompleted on WSL ford8d9edcdand main2b3de5b2. Both recorded 769 passed, 119 failed and 17 skipped, with the same result for every check in the two JUnit reports. Shared failures include unavailable test tools (29 checks), GCC rejecting_Static_assertin C++ fixtures, and the 600-second limit on the million-sample vector fixture. The Windows runner stopped before producing a complete report. The focused Windows guide and website checks are recorded above. Ruff on the changed Python files and workflow actionlint passed.Strict game-free checks that failed or timed out on both revisions
nx2/test_coop_spirv.pynx2/test_default_point_size.pynx2/test_depth_sample_types.pynx2/test_draw_parameters.pynx2/test_image_arrays.pynx2/test_nup_codec.pynx2/test_nup_read_name.pynx2/test_nup_stand_in.pynx2/test_nup_verify.pynx2/test_spirv_struct_identity.pynx2/test_texture_phi_dominance.pynx2/test_unsigned_image_types.pytests/test_appimage_player_build.pytests/test_bug_report_defaults.pytests/test_capture_read_once.pytests/test_capture_readback_visibility.pytests/test_check_third_party.pytests/test_crash_dialog.pytests/test_crash_record.pytests/test_crt_options.pytests/test_crt_shaders.pytests/test_damage_debug_menu.pytests/test_dav1d_av1.pytests/test_dev_ab.pytests/test_dev_packs.pytests/test_device_lost_exit.pytests/test_discover.pytests/test_display_startup_failure.pytests/test_dlss_feature_size.pytests/test_draw_binds.pytests/test_draw_stream_visibility.pytests/test_failed_compile_keeps_objects.pytests/test_flush_nothing_held.pytests/test_frame_overlap.pytests/test_fsr_image_retirement.pytests/test_fsr_uniform_ownership.pytests/test_fsr3_shaders.pytests/test_fsr3fi_hud_layer.pytests/test_fsr3fi_hudless_colour.pytests/test_fsr4_tune.pytests/test_gpu_wait_stats.pytests/test_guest_imported.pytests/test_high_fps_fixes.pytests/test_host_guest_writes.pytests/test_host_shaders.pytests/test_image_reaper_threads.pytests/test_insn_fixed_convert.pytests/test_libc_hooks.pytests/test_lift_cache.pytests/test_lift_lookups.pytests/test_linux_preflight.pytests/test_linux_pressure.pytests/test_linux_tools.pytests/test_linux_update.pytests/test_log_open_failure.pytests/test_longshot_saves.pytests/test_low_vram_texture_mips.pytests/test_make_game_cache.pytests/test_make_game_ngx.pytests/test_menu_module_slots.pytests/test_menu_modules.pytests/test_menu_sections.pytests/test_mesh_conv.pytests/test_mesh_fallback_layout.pytests/test_mesh_unreachable_outputs.pytests/test_mise_build.pytests/test_missing_nup.pytests/test_mma_software.pytests/test_mods_list.pytests/test_mods_size_table.pytests/test_native_float_atomic_add.pytests/test_native_zstd.pytests/test_ngx_sdk.pytests/test_nonuniform_image_arrays.pytests/test_obj_cache_size.pytests/test_oot_shadow_fit.pytests/test_pads_after_menu.pytests/test_pass_barrier.pytests/test_pending_guest_import.pytests/test_pipeline_play_cache.pytests/test_pipelines_outlive_cache_format.pytests/test_prepare_cache_save.pytests/test_present_queue_default.pytests/test_present_source_crop.pytests/test_profiling_mode.pytests/test_program_cache_cleanup.pytests/test_program_cache_one_variant.pytests/test_prompt_guide_lines.pytests/test_prompt_hand_guides.pytests/test_prompt_picture_tint.pytests/test_prompt_speed.pytests/test_psychov35_fsr3_fg.pytests/test_readback_timeout_source.pytests/test_recorder_own_idle.pytests/test_recorder_sync.pytests/test_reflex_swapchain_lifetime.pytests/test_renderer_new_handler.pytests/test_renhdrum.pytests/test_replay_write_order.pytests/test_sampler_admission.pytests/test_settings_table.pytests/test_slow_frames.pytests/test_song_note_cue.pytests/test_sparse_mirror.pytests/test_spirv_pack.pytests/test_split_giants.pytests/test_sprint.pytests/test_staging_burst.pytests/test_target_reuse_memory.pytests/test_texel_buffer_ownership.pytests/test_ub_update_batch.pytests/test_ui_record.pytests/test_upscaler_rows.pytests/test_vbytes.py(600 s timeout on both)tests/test_vcore_escape.pytests/test_vcore_mask0.pytests/test_vendor_translation.pytests/test_vk_occlusion_queries.pytests/test_walk.pySame Graphics view in the previous guide on main and the updated guide in this PR.
Still to test:
None for the guide and website behavior. Review and CI are tracked in the checklist.
Measurements
Verdict: the Longshot guide source check and website build now pass. There is no gameplay performance change to measure.
Setup: Windows site build with Node 24.22.2, Linux website tests in WSL, and a 1280×720 English Graphics capture with the SDL2 software fixture. Main
2b3de5b2adds a save fixture to the measured baselinef1f2dc5bwithout changing the guide, capture fixture, Graphics menu or website.2b3de5b2d8d9edcdRisks
The Graphics image could drift from the live menu as the frontend changes. The guide records the capture revision and retains the source guard. The website still rejects a hidden setting without a documented condition and rejects an unregistered Graphics action. Reverting the PR restores the previous guide and website behavior.
Review follow-up
The opening review was against
d5b9df01. The fixes are in8608978aand are included in the current head.HOS_WIDE_UI. The guide records nightly 680 as the current capture, identifies the rc.8 comparison as historical and explains how to verify the Git revision and source hashes.Checklist
Ready for review
main; the title is a Conventional Commit. Verified a conflict-free merge against85a59e6f. Main's intervening camera, renderer and synchronization fixes do not touch the PR's files.mise run testpasses (any failure that also fails onmainis named). This is satisfied under the baseline-failure exception: the strict run exited 1 on both revisions, and all 119 matching failures or timeouts are named above.main, or Measurements says why there is nothing to measure.third_party/untouched; nothing GPL-incompatible.When it applies
mainand passes here.tests/that reads changed source is updated, not weakened.mainand here, for a change that shows on screen. Both guide images are linked in Testing. The live comparison passed by hand.Assisted-by:/Co-Authored-By:trailers.Ready to merge
Possibly related, for context:
Recommendation: Request changes. The reported checks show the Settings page builds and the guide source check passes. The capture helper breaks the documented workflow for comparing older revisions, and the new logo loader needs a dimension check before allocating pixels.
Players get a newer Graphics illustration and can look up all nine Custom HUD sliders and Reset HUD placement on the Settings page. The fixture now builds the same menu modules as Longshot, which improves fidelity and adds maintenance work whenever those modules gain renderer dependencies.
@fixwill do (9)scripts/screenshots/capture_menu.py:46: The helper unconditionally compiles menu_model.cpp and its C++ fixture assumes the modular row table. (more on the line)scripts/screenshots/menu.cpp:152: The decoded PNG dimensions go straight into ImTextureData::Create, which multiplies width, height and four bytes per pixel as signed ints. (more on the line)scripts/screenshots/capture_menu.py:72: The reported checker regressions verify recorded files and hashes. They would still pass if the module inputs were omitted from the compile or the fixture lost its logo hook. Add a game-free smoke check for the Linux capture helper that links and renders the Graphics view in a temporary directory, honors the selected compiler, and fails if either fixture fix is undone.scripts/screenshots/menu.cpp:149: A missing or corrupt logo now throws after SDL, the surface, the renderer and ImGui have initialized. (more on the line)website/src/repo-docs/graphics-settings.ts:25: The visible badge omits the HOS_WIDE_UI condition. (more on the line)docs/user/images/guide/README.md:13: The provenance section identifies rc.8 at2f1c0c9cas the current Graphics capture. (more on the line)docs/user/images/guide/manifest.json:957: The README says reviewed_source.revision is the SHA-256 of the sorted file/hash pairs, but this entry stores the Git commit. (more on the line)docs/user/graphics-and-controls.md:268: The Sprint wording also changes, but the summary gives no reason for it. (more on the line)For the author (1) (a run, a measurement or a decision)
docs/user/images/guide/source-review-fullscreen-monitor.md:246: The current record compares the new PNG with the proposed rc.8 fixture image. (more on the line)Checks: Still running:
PR description / Description follows the template (pull_request_target),CI / Conventional Commit title (pull_request),CI / Workflow lint (actionlint) (pull_request),CI / Website build and checks (pull_request).More: does it help, other systems, switches, what was read
Does it help: Yes. The PR reports 37 guide source or fixture mismatches on
f1f2dc5band a passing local source check ond5b9df01. Astro goes from stopping at the first HUD slider to building 20 pages, with 90 of 90 Linux website tests and 89 of 90 on Windows. The Windows failure is reported on both revisions. The live menu comparison remains open.Other systems: The shared Graphics PNG changes in the repository guide and on the website. The optional Linux fixture also serves Audio, Controls and the focused Fullscreen view, and the current-head report describes a Graphics capture. The launcher images and their records are unchanged, and Launcher source review was skipped. Steam Deck, GPU vendors, drivers, saves, audio, input and game builds use unchanged runtime code.
Switches: No switch or option changes. The guide documents the existing HOS_WIDE_UI override. An unset or empty value leaves control with the HUD layout row, which defaults to Screen’s edges.
Reviewed:
d5b9df0195againstf1f2dc5bd2: Read AGENTS.md, CONTRIBUTING.md, the Forgejo template, the developer standards, the range log and all 11 file diffs. Read the changed Python, C++ and TypeScript files and tests in full and traced their menu, ImGui, website and screenshot-checker dependencies. Read the guide README and capture review, inspected the changed guide passages and PNG, and skimmed manifest fingerprints and recorded runs. The adjacent Tooling checkout and docs/review-checklist.md were absent.; nothing run (a code review).Checked and fine:
Testing: Read-only review. The diff whitespace check passed. Website, browser and fixture results are author-reported. The full repository suite, the current-head default Audio and Controls captures, the live Graphics comparison and the listed CI checks have no completed result in the supplied record.
Overlaps and merge order: The description identifies #1501 as the predecessor whose commits are included here. This branch carries that work, so there is no prerequisite merge order with #1501.
Automated code review by BeanBot (gpt-6.2-sol), on the pull request's opening. Nothing was run; a maintainer decides.
@ -266,3 +266,3 @@without the roll. Hold <kbd>Shift</kbd> while you move, or on a controller hold the left stick pressed in; let go andhe moves as before. He runs past people, signs and pots without talking, reading or picking up; tap A to roll oract as usual. While the ocarina waits for a note, Sprint does nothing. Turning the row on moves <kbd>Shift</kbd> from Bact as usual. Sprint is disabled while the instrument is waiting for a note. Turning the row on moves <kbd>Shift</kbd> from BL9 (minor): The Sprint wording also changes, but the summary gives no reason for it. The website audit rejects the old instrument name in the published page, so identify this edit as part of restoring publication.
@ -11,3 +11,3 @@source hashes. All six launcher images are UI-only captures built from Launcher nightly-52-b1d9f7a9 source`b1d9f7a9b19fa99b91ec3e8cd24455d4703d6d25`; they replace the earlier official-AppImage and rc.3 fixture captures.The Graphics image is recaptured from fullscreen monitor PR #1277, `54d25c79ead4d07e22cdcf5f07e481e19f90f78c`, on main `e335bd5c`.The Graphics image is recaptured from main `2f1c0c9c19ce922a9d86dc95c3f56653340d70c3` (v3.0.0-rc.8), after the NFC tab (#280) joined the menu's tab strip and #1629 moved its banner; its earlier capture, from fullscreen monitor PR #1277 (`54d25c79`), remains in repository history.L6: The provenance section identifies rc.8 at
2f1c0c9cas the current Graphics capture. The committed PNG, caption and manifest identify nightly 680 atf1f2dc5b. Namef1f2dc5bhere and identify the rc.8 sections in the linked review as historical comparisons.@ -897,3 +955,3 @@"reviewed_source": {"repository": "https://git.magicbean.dev/MagicBeanDev/Longshot","revision": "sha256:4179c3f3d6f121635148401ca32b40133749c113f3ceb4032215aae45e54316b","revision": "f1f2dc5bd2821cef061798ba40a043d281ac1707",L7 (minor): The README says reviewed_source.revision is the SHA-256 of the sorted file/hash pairs, but this entry stores the Git commit. A maintainer following that verification instruction cannot reproduce the recorded value. Record the source-map digest here or document that this review uses the exact main commit and explain how to verify it.
@ -116,0 +243,4 @@The game-free fixture rendered the first Graphics view at 1280×720 from main `f1f2dc5b` (nightly 680). Compared with the previous proposed rc.8 image, 61,552 of 921,600 pixels differ. The visible setting labels, values, Quality preset help and keyboard commands still match. The banner version, scrollbar and layout pixels changed, so the guide uses the new capture and its matching caption.The manifest records the compiler-discovered source files and fixture hashes for this capture. This review uses the SDL2 software renderer and bundled fonts. The in-game Graphics comparison remains pending.L10 (minor): The current record compares the new PNG with the proposed rc.8 fixture image. The pending live comparison still needs to confirm the visible rows, selected help and keyboard and tab prompts at the corresponding menu scale, and record any differences due to hardware or the synthetic defaults.
@ -45,2 +44,3 @@'-I' + str(source), '-I' + str(source / 'gpu/vk'), '-I' + str(source / 'host/posix'), '-I' + str(source / 'gpu/vk/compat'),'-I' + str(source / 'third_party/imgui'), '-I' + str(args.vulkan_headers.resolve()),str(Path(__file__).with_name('menu.cpp')), str(source / 'gpu/vk/vk_menu_i18n.cpp')]str(Path(__file__).with_name('menu.cpp')), str(source / 'gpu/vk/vk_menu_i18n.cpp'), str(source / 'gpu/vk/menu_model.cpp')]L1: The helper unconditionally compiles menu_model.cpp and its C++ fixture assumes the modular row table. Pointing the documented --source option at v3.0.0-rc.8 fails because that checkout has no menu_model.cpp. Preserve the cross-revision workflow with a compatible fixture for each layout, or reject pre-module sources up front and document which pinned helper to use for each side.
@ -119,0 +146,4 @@{ // The banner's logo: the repository's own picture, decoded to straight RGBA bytes, as the renderer's header holds it.png_image logo{};logo.version = PNG_IMAGE_VERSION;if (!png_image_begin_read_from_file(&logo, argv[2])) throw std::runtime_error(logo.message);L4 (minor): A missing or corrupt logo now throws after SDL, the surface, the renderer and ImGui have initialized. The catch exits without running their shutdown, and failures after texture registration also bypass the logo cleanup. Give those resources scoped ownership so each successful init is unwound and the logo is unregistered before destroying the ImGui context.
@ -119,0 +149,4 @@if (!png_image_begin_read_from_file(&logo, argv[2])) throw std::runtime_error(logo.message);logo.format = PNG_FORMAT_RGBA;auto* texture = IM_NEW(ImTextureData)();texture->Create(ImTextureFormat_RGBA32, int(logo.width), int(logo.height));L2: The decoded PNG dimensions go straight into ImTextureData::Create, which multiplies width, height and four bytes per pixel as signed ints. A 32,768 by 32,768 replacement logo overflows that calculation before libpng decodes the pixels. Check both dimensions and the RGBA byte count before narrowing or allocating, and reject an oversized logo with a clear error.
@ -22,6 +22,7 @@ export const BADGES = [{ test: /\bshown with NVIDIA DLSS\b/i, label: 'With NVIDIA DLSS', shown: true },{ test: /\bshown while Frame generation is on\b/i, label: 'While Frame generation is on', shown: true },{ test: /\bshown with a CRT filter on\b/i, label: 'With a CRT filter on', shown: true },{ test: /\bshown with HUD layout set to Custom and no `HOS_WIDE_UI` override\b/i, label: 'With HUD layout set to Custom', shown: true },L5 (minor): The visible badge omits the HOS_WIDE_UI condition. A player whose saved HUD layout is Custom and whose longshot_env.txt still sets HOS_WIDE_UI=0 sees a badge implying Reset HUD placement is available, while the only caveat is inside its collapsed disclosure. Put both conditions in the visible badge and assert the rendered text.
WIP: fix(website): refresh the Graphics guide and document Custom HUD controlsto fix(website): refresh the Graphics guide and document Custom HUD controls