WIP: feat(vk): choose the colour of Link's tunic in the Insert menu #1616
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
1 participant
Notifications
Due date
No due date set.
Dependencies
No dependencies set
Reference
MagicBeanDev/Longshot!1616
Loading…
Reference in a new issue
No description provided.
Delete branch "mooki/Longshot:feat/link-colours"
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: feat · Risk: medium · Tested on: Linux, RTX 4090 (NVIDIA driver, windowless) · Needs: Windows, AMD
TL;DR
You can now pick the colour of Link's tunic and cap, child and adult, in the Insert menu (Gameplay, Link's colours): 24 named swatches, a picker or a hex code, applied while you pick, saved in your options file, and usable with a controller alone. Mido and the ocarina holder, who share Link's tunic texture in the game's files, keep their own green. Nothing from the game is added to the repository: the renderer finds Link's textures through a table the builder makes from your own game files. I checked it in the game on the build of this head, in five runs and a page run, and with new tests.
Breakdown
link_tunicand the variableHOS_LINK_TUNIC.Why
Link's tunic is always the same green. Players have asked to colour it, and a co-op project already does (https://github.com/daurosk/oot-remake-multiplayer), with ten fixed colours and a worker that polls the game's textures. This adds the first slice for Longshot: alone, any colour, with a page that works with a controller. No issue on the tracker asks for it (the tracker was searched: no cosmetics, palette, tunic or texture-override thread, open or closed).
What changed
The renderer recolours Link's tunic textures when it uploads them, from a table the builder makes from your own game files, so nothing from the game is in the source and the game's memory is never written. Mido and the ocarina holder get a texture of their own, made at build time, and stay green.
gpu/vk/coop_look_paint.{h,cpp}andtests/test_link_look_paint.cpp: daurosk's block recolour and test, GPL-3.0-or-later with his SPDX line, taken as they are from https://github.com/daurosk/oot-remake-multiplayer (commit39b98de2); a test pins their hashes.gpu/vk/link_look_recipes.h,link_look.{h,cpp},link_look_upload.h, the seam ingpu/vk/vk_texture.cpp(look_begin(),guest_bytes(),upload_inner(),texture_touch(): about 40 lines) andvk_main.cpp: the recipe table, the choice, the recoloured copy laid over the guest's bytes for one upload on the CPU route, the live change (a texture made under an older choice is uploaded again at its next use), the copy kept per colour.nx2/link_look_assets.py,nx2/make_game.py,nx2/prompt_assets.py: the builder writeslook/recipes.txtand a mod foldermods/00-longshot-link-look(private copies of the two models and the one tile); the size-table row the new texture needs travels inprompts/rsizetable.zs, whichhost/prompts.calready merges into a mod's table.gpu/vk/look_picker.h,vk_menu.{h,cpp},menu_i18n.h,switches.def: the optionlink_tunic, the page (draw_look,look_open,look_close), the picker, 46 texts in the 13 menu languages (written by the assistant: a native speaker's look is welcome).docs/link-colours.md,docs/link-colours-page.md,docs/development.md, the README's option table.Not in this PR: gear colours, co-op (others seeing your colours), saved palettes and share codes, per-save colours, a rotating preview of Link.
Measurements
Verdict: works in the game on this PC; the cost is a one-time CPU recolour of about 85 ms for the child's five textures at load (93 ms for the adult's three, once per colour change) plus about 0.02 ms to look at each texture of a recipe's shape and size; no frame time is claimed (shared card).
Hardware: Linux (Arch, kernel 7.2.15), GeForce RTX 4090 with NVIDIA 615.78.08, Intel Core i9-13900K (32 threads), 93 GB; windowless, 1280x720 pictures.
Scene: Kokiri Forest, child, beside Mido; Kakariko, adult.
Method: the game's own
longshot_log.txtlines "Link's colours" (a count and the milliseconds of each recolour and the running totals of hashing and recolouring) from the five games of the proof hold,analysis.txtmade by a script from those logs.How to reproduce: build a game folder, set
HOS_LINK_TUNIC=1FA67Aor open the page, look at Link.876dc360924ae0373a(from the child's first run, c1; the full lines are in the evidence folder of the run)
Flags and settings
An option, an environment name and a switch-table row; no renderer switch.
link_tunic(menu row Link's colours, ini key)RRGGBBoroffoff(the game's own)HOS_LINK_TUNIC=<RRGGBB>offor empty: the game's own); row ingpu/vk/switches.defTesting
Tested: on the PR head
24ae0373arebased onmain876dc3609; the game runs below were made on a fullnx2/make_game.pybuild ofd21e02e95, the head's parent (the head adds one commit that changes onlytests/test_upscaler_round_trip.py, which no game run reads). Linux, RTX 4090, windowless, 18 November 2026.tests/test_link_look_paint.py(daurosk's recolour and his test, files pinned by hash),test_link_look_recipes.py(the table: good lines, comments, an unknown part, malformed and too long lines, the size window, a near miss),test_link_look_seam.py(the overlay is used only while an upload runs, guest memory is never written, an overlaid texture skips the GPU unswizzle, a new choice makes the textures again),test_link_look_assets.py(38 tests of the builder on a synthetic RomFS),test_link_look_picker.py(708 checks; the test breaks its subject 13 ways and each break fails one),test_link_look_menu.py(13 tests: the row, the page, the ini, the variable, the bridge, the translations), and the existing menu tests updated for the new row. All pass.python -I -B tests/run_all.py: this head: 729 passed, 40 failed, 17 skipped;main876dc3609: 722 passed, 41 failed, 17 skipped. All 40 failures of this head also fail onmain(named in step 2);test_mods_size_tablefails onmainand passes here (its link stub now matches). One failure of my own was found this way (test_upscaler_round_trip, fixture out of date) and fixed in the head's last commit.main(test_astc_reuse,test_audio_output_menu,test_mods_size_table,test_stick_dead_zone: sources ofmainthat Windows-Werrorrejects). Windows execution was not run.link_tunicover the control bridge); adult in Kakariko, the game's own, then teal, red, the game's own; no colour chosen (the feature on); ASTC as RGBA8 (RX_VK_ASTC_RGBA8=1); ASTC on the CPU (RX_VK_ASTC_CPU=1). All five exit 0, kernel driver lines 0, no crash or device-lost line. The child's tunic and cap are recoloured (5 textures), the adult's tunic and cap (3); the pause menu's Equipment page shows Link in the colour; Mido's vest and cap stay green next to a teal Link; the three decode routes give the same colour.longshot_options.iniheldlink_tunic=C8321Eafterwards, and the next start of the game came up with Link in red from the first frame, with no menu open.How it was tested, step by step
python3 -I -B tests/test_link_look_<name>.py, the compile with-Wall -Wextra -Werror.main.python -I -B tests/run_all.py --jobs 6 --strictonce onmain876dc3609and once on this head, under the whole-suite lock and the idle gate (a private wrapper that waits until the machine is quiet), compared by failing test name: 729 passed, 40 failed, 17 skipped on this head (277 s); 722 passed, 41 failed, 17 skipped onmain(257 s). The failing names of this head, all also failing onmain:test_bug_report_defaults,test_capture_readback_visibility,test_cpu_report,test_crt_options,test_damage_debug_menu,test_dev_packs,test_display_startup_failure,test_dlss_feature_size,test_draw_stream_visibility,test_failed_compile_keeps_objects,test_fsr_image_retirement,test_fsr_uniform_ownership,test_guest_imported,test_hud_layout_row,test_invalidate_quick,test_invalidate_vcore,test_libc_hooks,test_linux_preflight,test_linux_pressure,test_linux_update,test_log_open_failure,test_mirror_budget,test_missing_nup,test_nonuniform_image_arrays,test_parallel_init_order,test_pending_guest_import,test_pipeline_play_cache,test_present_source_crop,test_present_thread,test_profiling_mode,test_psychov35_fsr3_fg,test_readback_timeout_source,test_replay_write_order,test_run_all_changed,test_slow_frames,test_staging_burst,test_switch_table,test_upscaler_rows,test_vk_occlusion_queries,test_walk_key. Onmainonly,test_mods_size_tablealso fails (it passes here: the test's link stub was brought up to date). The first branch run of the pair showedtest_upscaler_round_tripfailing only on the branch; that was mine (the fixture cutsave()andmenu_init()out ofvk_menu.cppwithout the new picker), fixed by the head's last commit, and this run is after it.d21e02e95withnx2/make_game.py(https://git.magicbean.dev/MagicBeanDev/Longshot/src/branch/main/nx2/make_game.py), through the full-build lock and the build gate: 611 s, exit 0, log linelongshot v3.0.0-rc.7-88-gd21e02e95 (source 272919f8). The game folder haslook/recipes.txt(7 lines, the builder's) and the mod foldermods/00-longshot-link-look(two model copies and one texture). Earlier heads were tried on a standalonenx2/build.pybuild (no lift) while this was written; none of that is evidence for this head and none is used here. Shader and pipeline caches were made once with the game's--prepare-shaders(295 s) before the games.HOS_HEADLESS=1, https://git.magicbean.dev/MagicBeanDev/Longshot/src/branch/main/docs/development.md), through the GPU gate that lets games take turns, 1280x720 pictures. The machine was busy with other work (load average 12 to 54 during the runs), so no speed number is claimed.HOS_OPTIONS_FILE) withlink_tunic=off, because the control bridge'soption setsaves to the file it was started with.scripts/longshot_ctl.py, https://git.magicbean.dev/MagicBeanDev/Longshot/src/branch/main/docs/control.md) over a private socket per run:statusuntil Link is controllable (stateplay, map and position),shotfor a picture (the bridge's pictures leave the menu out and show Link as the game draws him),stick Rto turn the camera,press PLUSandpress Lfor the pause menu,option set link_tunic <value>for a live change,quit. The workbench's run wrapper starts the game, keeps the log, frame statistics and the kernel's driver lines, and says when the run ends. The public workbench has the same bridge calls as session tools: https://github.com/mooki000/ls-workbench.HOS_LINK_TUNIC=1FA67A, four views, the pause menu's three pages, then red, blue, the game's own and teal set live, then a walk to Mido and a talk; a1 adult in Kakariko, the game's own, then teal, red and the game's own live; c0 child with no colour chosen (the feature on, the control picture); r2 child, teal,RX_VK_ASTC_RGBA8=1; r3 child, teal,RX_VK_ASTC_CPU=1. Pictures were taken at the same spot for each colour.RX_VK_MENU_SCRIPTpresses Insert, the Gameplay tab, 14 times Down to Link's colours, Enter to open the page, Right and the pad's A (PADE, confirm) for Red, the pad's left button (PADW, Y: reset to the game's own, see step 10), two more Rights and A for Gold, the pad's B (PADS, back), Enter to open the page again, Right and A for Red, Esc (keep and close the page), Esc (close the menu);RX_VK_SHOT_MENU=1andRX_VK_SHOT_EVERY=30make the menu's own pictures every 30 presents (these show the page), and the bridge takes a picture of Link every 1.2 s and reads the option. p2 starts the game again on the options file p1 left, and sets the colour back to the game's own at its end.PADS,PADE,PADW,PADN) inject only the menu's own confirm and back presses, so X, Y, the triggers, the sticks and L3 are not driven by any run here; the page's use of them is covered by the picker's state-machine test (708 checks) and by the page's own hint line, which the pictures show.PADWpress in this hold's timetable does nothing: the pictures show Red staying Red until the next A. I left it in the timetable and say so instead of counting a reset as tested.panels.shof the evidence skill), and the log lines were counted by a script (analyze1.py): per run, the textures recoloured and by which colour, the milliseconds, the mods loaded (Mido's and the ocarina holder's copies), and the fatal, crash and device-lost counts (all 0).Pictures
Not testable by hand: a real controller's X (compare), Y (reset), triggers (turn the hue) and L3 (the D-pad in the square): the host gives the menu only a digital mask of the pad's buttons, the control bridge's
pressgoes to the game and not to the menu, and the menu script's pad tokens inject only the menu's confirm and back. Those paths are covered by the picker's state-machine test (708 checks, 13 deliberate breaks) and, in the game, only A and B were driven. A person with a controller can try the rest.Not tested: Windows and AMD; the ocarina holder's copy (not in view in any picture, only its loading is in the log); a character mod that replaces Link's textures or models; frame times (shared card, no timing claim is made); the black first picture on the CPU ASTC diagnostic route was not run down (step 12 below).
Must be tested:
@Beanstalk windows, Link's colours page)@Beanstalk radv)docs/link-colours-page.mdsays (Test Farm: any player with a controller)Risks
What could break: the upload path of every texture gets one lookup (
link_look::wanted, a table of seven entries): a texture of a recipe's shape and size is hashed once (PENDING:cost-hash-short). A mod that replaces Link's textures makes the table match nothing and the page says "not found in this game". The private copies need the game to take a texture under a new name from the mod folder with a size-table row: it did in the proof (the log shows both files loaded, no hang), but a user mod whose own size table cannot be merged byhost/prompts.closes our row (Mido and the holder would then follow Link's colour or fail to load; not seen). On the CPU ASTC diagnostic route a texture can be black at the moment of a picture; it happened without the feature too (see the step list).Turning it off: the game's own colour is the default and the lookup does nothing without
look/recipes.txt; reverting the commits removes everything.Compatibility:
longshot_options.inigets one new key; the builder writeslook/and a mod folder in the game folder (a build from before this has neither and nothing changes);prompts/rsizetable.zsis written even when the font needs no raise; the shader translator and the pipeline caches are not touched; noMKWVK_API_VERSIONchange.Checklist
Everyone
type(scope): description) of the status line's type.can't be run by hand is in Testing's Not testable by hand, with why.
in Risks.
main.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.mainand passing here.tests/that reads changed source updated in this PR, not weakened.New on this forge; not opened on GitHub.
gpu/vk/coop_look_paint.{h,cpp} recolour the end colours of BC1, BC3 and ASTC blocks of one tone to another colour without decoding the texture, keeping the shading. They are taken as they are from https://github.com/daurosk/oot-remake-multiplayer (hookshot/src, commit 39b98de2), GPL-3.0-or-later with his SPDX line, and tests/test_link_look_paint.cpp carries his look_paint_test.cpp (the checks and the synthetic golden blocks are his; his doctest macros are replaced by a small shim). tests/test_link_look_paint.py pins the two files by hash so an edit of them is a decision. Assisted-by: Claude Sonnet 5.5 Co-Authored-By: Claude Sonnet 5.5 <[email protected]> Co-authored-by: daurosk <[email protected]>View command line instructions
Checkout
From your project repository, check out a new branch and test the changes.