Status | Install and play | Controls | In-game menu | Mods | Build from source | Credits | License
BlueShell is a static recompilation built on Hookshot's engine. The game's code is translated to C and compiled into a Windows program, the console's system software is reimplemented, and the Switch 2 graphics are rebuilt on Vulkan. All of this happens on your PC, from your own copy of the game.
Important
This repository does not contain the game, keys or an executable, and it does not explain how to get them. You
need your own copy. Everything the build creates (blueshell.exe, the generated code, the shader caches and your
saves) comes from your game and stays on your PC. Never share those files.
Experimental.
| What | Status |
|---|---|
| Menus, Grand Prix, Knockout Tour and free roam | ✅ Works |
| Sound, controller, keyboard and saves | ✅ Works |
| Hookshot's renderer, stutter, memory and flash fixes | ✅ In |
| One-frame flashes in some scenes (a desert stretch, a town by the water) | |
| Frame generation | ❌ Off for now: it flashed the title screen |
| Stutter the first time a scene is seen | |
| Linux | ❌ Not yet |
- Download BlueShellBuilder.exe from the latest release and run it. It installs the BlueShell Builder (it downloads its own parts and the compiler; no Visual Studio needed).
- Point the Builder at your own dump of Mario Kart World: a
.nup, or itsromfsandexefsfolders. - Choose a game folder. Optional: a Save folder, Unlock everything (every driver, outfit, kart and sticker, the Special Cup and Mirror, added to your own save) and the 100% save.
- Build, then press Play. The first build takes a while; later updates rebuild only what changed.
The Insert key opens the in-game menu.
Keyboard racing layout (change it in the Insert menu's Controls tab):
| Action | Keys |
|---|---|
| Accelerate / brake | W or Enter / S or Backspace |
| Steer | A / D, or the arrow keys |
| Drift / hop | Space |
| Item | Shift or E |
| Stick up / down (menus, aim) | Arrow keys or I / K |
| Pause | Tab or P |
Controllers work as they do in Hookshot.
By default, press Insert, F1 or Esc in game. On a controller, press Home or Select and
Start together; on a DualShock 4 or DualSense, clicking the touchpad does the same as F1, unless a row of
Controls takes the touchpad as its input.
The same keys close it; with every Menu shortcut, Esc goes back a page or closes the open menu.
F1 always works. Controls → Menu shortcut can leave Insert free for another overlay (F1 only).
With Insert or F1, or with F1 only, Esc does not open the menu: it only lets the mouse go. Options saved by
an older version on Insert or F1, the default then, move to Insert, F1 or Esc; F1 only stays.
The menu has five tabs, Graphics, Audio, Gameplay, Controls and Debug:
Q and E (or Tab and Shift+Tab) switch between them, LB and RB on
a controller (or the triggers). Up and Down choose a row, Left and Right
change it (Enter changes it too); beside the rows, the help says what the row is and, on a line of its own,
what the value chosen does. On a controller the D-pad chooses and changes, A changes too and opens a page (Motion,
Controls, the Teleport list, the inventory), and B goes back or closes the menu: A and B are the buttons your layout puts the Switch's A and B
on (with the Nintendo layout, A is the right face button). The mouse is free while the menu is open: click a tab, click a row's name to choose it (its
value stays), click the left or right half of a value to lower or raise it, drag a slider, turn the wheel to scroll the rows (it never changes a value), and right-click to go back. The
button prompts at the bottom show the keys or the controller's buttons, whichever you used last. Your choices are saved
in hookshot_options.ini in the game folder.
The menu, the FPS counter and the start-up screen are drawn in the style of the game's own menus. They use the game's own menu font, read into memory from your game files (the romfs folder the game runs from) the first time one of them is drawn. It is never copied anywhere, and Hookshot does not include it. Without it, or if it has no Latin letters, they use Libertinus, which Hookshot includes.
The rows marked "after a restart" below are read when the game starts. While one is changed, it is tagged "After restart" and the help on the Graphics tab lists it; closing the menu then asks whether to restart now. Later keeps the change for the next start (and is not asked again until you change one of those rows); Restart now saves your choices and starts the game again, so progress since your last save is lost.
A row for something this PC cannot use is not shown: NVIDIA Reflex and AMD Anti-Lag 2 without a GPU and driver that have them, the DLSS model where DLSS does not run. HDR paper white and HDR peak brightness show only while HDR is on, the HDR tone mapper only with HDR set to Native.
The Graphics tab groups its rows under section titles: Resolution and upscaling, Frame generation and latency, Screen, HDR, Detail, and GPU and memory (last: the rows to change when something is wrong). The table lists them in that order.
| Tab | Option | Choices | Default |
|---|---|---|---|
| Graphics | Quality preset | Custom, Minimum (4GB), Low (6GB), Balanced (8GB), High (12GB), Ultra (16GB+), Auto (this PC) | Auto (this PC) on a first start; Custom in an options file from before it |
| Aspect ratio | The shapes your screen's resolutions have, narrowest first (5:4, 4:3, 16:10, 16:9, 21:9, 32:9, ...), your monitor's own marked "(monitor's)" (after a restart) | Your monitor's | |
| Stretch to window | Off, On (the picture over the whole window, for an ultrawide mod: with the Aspect ratio at 16:9) | Off | |
| Output resolution | The Aspect ratio's sizes: your screen's resolutions and the common ones (1440p, 4K, 5K at 16:9; 1920x1200, 2560x1600 at 16:10; 3440x1440 at 21:9; ...), and 2048x1152 (the game's own) at 16:9 (after a restart) | 2048x1152 | |
| Profile | Docked, Handheld (after a restart) | Docked | |
| Upscaler | Game's own, NVIDIA DLSS, NVIDIA DLAA (only in builds with NVIDIA's DLSS SDK, below; DLSS and DLAA on RTX GPUs), AMD FSR 3.1 (every build, on GPUs it runs on, below), AMD FSR 4, AMD FSR 4 Native AA (only in builds with FSR 4, below), Off (no upscaling) | Game's own | |
| DLSS model | Transformer (K), Transformer 2 (M), Transformer 2 (L), NVIDIA default (shown where DLSS runs; used by DLSS and DLAA) | Transformer (K) | |
| Render resolution | Auto (the game's own dynamic resolution), 100%, 75%, 67%, 50% (each with its size). With DLSS, FSR 3.1 or FSR 4: Auto, Quality (67%), Balanced (58%), Performance (50%), Ultra Performance (33%). With DLAA or FSR 4 Native AA: Native. With Off: Auto, 100%, 75%, 67%, 50%, 33% | Auto | |
| Sharpness | 0 to 100%, in steps of 10 | 0% | |
| Frame generation | Off, Auto, 2x to 8x | Off | |
| Frame generation by | Auto (NVIDIA DLSS Frame Generation where it runs: RTX 40 and newer, with a temporal Upscaler; else the built-in one; with frame generation on, the row shows who makes the frames, as Auto: DLSS FG, and why not DLSS FG when another does), Built-in FG (changes at once) | Auto | |
| Frame pacing | Off, On | Off | |
| Game frame rate cap | 60, 90, 120, 144, 165, 240 FPS, Uncapped, 30 FPS (after a restart) | 60 FPS | |
| NVIDIA Reflex | Off, On, On + Boost (shown only on NVIDIA GPUs with VK_NV_low_latency2) |
Off | |
| AMD Anti-Lag 2 | Off, On (shown only on AMD GPUs with VK_AMD_anti_lag) |
Off | |
| Fullscreen | Off, On (the same as F11) | Off | |
| V-Sync | Auto, On, Off | Auto | |
| Window scaling filter | Off, Catmull-Rom, Lanczos | Off | |
| Ultrawide menus | Full width; Centred, blurred sides; Centred, black bars (with the Aspect ratio at the monitor's shape) | Centred, blurred sides | |
| HDR | Off, Expanded, Native (the game's) | Off | |
| HDR paper white | 80 to 400 nits (while HDR is on) | 200 nits | |
| HDR peak brightness | 400 to 4000 nits (while HDR is on) | 1000 nits | |
| HDR contrast | 50% to 200% around mid grey (while HDR is on) | 100% | |
| HDR tone mapper | Vanilla (the game's curve), PsychoV35 (RenoDX's; with HDR set to Native. DLSS, FSR and TAAU do not take its scene yet: the game's own upscale runs) | Vanilla | |
| Texture detail | Auto, Full, Medium, Low | Auto | |
| Anisotropic filtering | Game's, 2x, 4x, 8x, 16x | 16x | |
| GPU device | Auto, or each graphics card by name (after a restart) | Auto | |
| VRAM budget | Auto, 3.6, 4.8, 6, 7.5, 9, 11 GB (2.2 GB only from the Minimum (4GB) preset); a quality preset sets it | Auto | |
| Refresh memory | A button (Enter or A): lets go of the textures not drawn for a while and asks Windows to keep the game's memory in RAM | ||
| Audio | Volume | 0 to 100%, in steps of 5 | 100% |
| Mute in background | Off, On | Off | |
| Audio output | Auto, Stereo, 5.1 (after a restart) | Auto | |
| Gameplay | FPS counter | Off, FPS, Frame time, Graph, Breakdown | Off |
| FPS counter position | Top right, Top left, Bottom right, Bottom left | Top right | |
| Menu size | Small, Medium, Large | Medium | |
| Game speed | Per frame, Real time | Real time | |
| Field of view | 50% to 150%, in steps of 5; applies immediately during gameplay | 100% (original) | |
| Text speed | Normal, 2x, 4x, Instant | Normal | |
| Text size | Original, 110%, 125%, 150%, 175% (dialogue, Navi and signs) | Original | |
| Microphone | Off, Default, or each microphone by name | Default | |
| Game language | The game's 16 languages, each by its own name (after a restart) | The one built with | |
| Menu language | Auto (the game's language), or English, Português (Brasil), Español (Latinoamérica), Español (España), Français, Deutsch, Italiano, Nederlands, Polski, Русский, 日本語, 한국어, 简体中文, 繁體中文 | Auto | |
| Discord status | Off, On ("Playing BlueShell" and the time played in your Discord status, while Discord runs on this PC) | On | |
| Unlock everything | Off, On (every driver and outfit, kart and sticker, the Special Cup and Mirror added to your save when the game loads it; your progress stays, the save before goes to save-backup-unlock; after a restart) |
Off | |
| Skip opening | Off, On (skips the new-game opening: the story movie and Navi waking Link; later cutscenes and the title screen stay) | Off | |
| Bug report | Saves a report into a new folder in bug-reports (below) |
||
| Controls | Controller in background | Off, On | Off |
| Mouse camera | As the stick, Native | As the stick | |
| Disable camera centering | Off, On | Off | |
| Mouse sensitivity | 0.10 to 5.00 | 1.00 | |
| Invert mouse vertical | Off, On | Off | |
| Invert camera X | Off, On | Off | |
| Invert camera Y | Off, On | Off | |
| Camera speed | 50% to 400%, in steps of 25 | 100% | |
| Stick dead zone | Default (24%), 5%, 10%, 15%, 20%, 30% | Default (24%) | |
| Auto run | Off, On | Off | |
| Rumble strength | Off, 25% to 150%, in steps of 25 | 100% | |
| Layout preset | Nintendo (Def), Xbox / PC, Swap Face, Custom (on the Controls page) | Nintendo (Def) | |
| Button prompts | Auto, Switch, Xbox, PlayStation 4, PlayStation 5, Steam Deck (on the Controls page) | Auto | |
| Motion | Opens the Motion page: Motion controls (Off, On; On), Motion sensitivity X (10% to 600%) and Y (10% to 300%; 100%), Invert motion X and Y (Off, On; Off), Motion deadzone (Low, Standard, High; Standard) | ||
| Controls | Opens the Controls page | ||
| Menu shortcut | Insert or F1; F1 only; Insert, F1 or Esc | Insert, F1 or Esc | |
| Compact menu key | Right Shift, Right Ctrl | Right Shift | |
| Debug | Debug tools | Off, On (the tools below it while on) | Off |
| Developer: Descriptor reuse | Off, On (after a restart) | On | |
| Developer: Sampler cache | Off, On (after a restart) | Off | |
| Developer: Robust buffers | Auto, Off, On (after a restart) | Auto | |
| Developer: ASTC as RGBA8 | Off, On (after a restart) | Off |
- Quality preset sets Render resolution, Window scaling filter, Sharpness, Frame pacing, Game speed, Profile and the video memory limits for a card with that much memory. It leaves the Upscaler and Frame generation as you chose them: with DLSS, FSR 3.1 or FSR 4, the preset's resolution becomes their nearest mode. Changing most other rows yourself sets it back to Custom.
- Auto (this PC), which a first start begins on, chooses for the PC it runs on: the memory tier from the card's
video memory (an integrated GPU, a Steam Deck or a card without mesh shaders at Minimum), DLSS on an NVIDIA RTX card
or FSR 4 on an AMD RX 9000 where the build has them (else the game's own upscaler), and the screen's size as the
Output resolution where the tier has the memory for it. In the first minute of play it then measures the GPU: while
frames are missed with the GPU over 90% busy it lowers the Render resolution a step, and while the frame rate cap holds
with the GPU under half busy it raises it a step, up to the best mode that still upscales (DLSS or FSR Quality, or 100%
with the game's own; never DLAA or native AA). At most two steps; a PC that holds its cap keeps its picture. It chooses again when the card or the screen changes.
hookshot_log.txt'sAuto (this PC)lines say what it chose and why. - Menu size is how large the menu, the FPS counter and the start-up screen are drawn: Medium unless you choose Small (a desk) or Large (a TV across the room). It stays the same whether you use a controller or the keyboard and mouse.
- Field of view changes the gameplay camera's vertical angle: 100% keeps the game's view, higher shows more of the
world and lower brings it closer. The game's zoom changes remain relative to your choice.
Aiming has been tested in the 50% to 150% range, including with ultrawide enabled.
Cutscenes, the HUD and movies keep their own view. The setting is saved as
field_of_viewinhookshot_options.ini. - GPU device matters on a PC with more than one graphics card (a laptop's integrated and dedicated GPUs, or a
second card for Lossless Scaling). Auto prefers a dedicated one, and only cards with Vulkan 1.3 are listed.
hookshot_log.txtlists every card asvk: device <n>;RX_VK_DEVICE=<n>chooses one for a single run and wins over the menu. - Frame generation makes extra frames between the game's own. It adds a little input delay, and fast motion can
show artifacts. The renderer's own interpolation makes the frames; at 2x, AMD FSR 3.1's frame interpolation can make
it instead with
RX_VK_FSR_FG=1(below: it moves the HUD with the scene, so it is not the default). Frame pacing shows frames at an even interval: less stutter, up to one frame of delay. It paces the frames that frame generation shows, so it has no effect while Frame generation is Off. - Game frame rate cap limits the frames the game renders. With a cap of 60 and Frame generation at 2x, the output
can reach 120 FPS. Choose Auto in Frame generation to target the display's refresh rate instead of a fixed multiplier.
30 FPS reduces rendering work for handhelds and slower PCs while keeping real-time game speed. It is the last option
in the row so existing saved caps keep their meaning. At 30, Game speed follows real time even if Per frame is selected.
A cap past 60 is experimental: the game keeps real time, but some cutscenes and bosses still count frames and can
misbehave (Gohma running into the wall, the intro's narration running ahead: #1742). 60 is the safe choice.
Uncapped renders as fast as the PC can (the game still keeps real time). A display that waits for its refresh still
holds the frames to its refresh rate: V-Sync on, or the driver's FIFO mode.
HOS_FPS_MAX=30or<61-1000>sets a cap for one run. - Bug report writes a folder
bug-reports/<date>_<time>in the game folder with what an issue needs:report.txt, which answers the game problem form's questions under its own headings (the version, the map you are in, your graphics card and driver, CPU, RAM and system, the menu options and theRX_/HOS_switches you changed) and ends with a link that opens the form with them filled in (the switches by name only);hookshot_log.txt(this run's log so far) andhookshot_log.1.txt(the run before's, which has the crash if the game crashed last time); andpicture.png, the game's picture without the menu. Your home folder is written~(%USERPROFILE%on Windows) and your user name<user>in the logs' paths. A switch's value is written only when it is a number, a size or on/off, and never for a name withTOKEN,KEY,ROOM,SECRET,PASS,SERVERorUSERin it; other values read(value left out). Nothing else goes in (no saves, no game files, nothookshot_options.iniorhookshot_env.txtthemselves), and nothing is sent: open the form, write what happened, and drag the folder's files into it (from File Explorer on Windows, a file manager on Linux; on a Steam Deck, in Desktop Mode). The row then shows the folder's name. A game that stops before its menu can be used leaves its log ashookshot_log.1.txt: start it again, or attach that file yourself. - The scaling rows, in the picture's order: Output resolution is the size of the game's whole frame, HUD included. The Upscaler fills it from the 3D: the game's own network, NVIDIA DLSS or DLAA (the 3D at full size, edges smoothed), AMD FSR 3.1, or AMD FSR 4 or its Native AA (below). DLSS and DLAA look softer than the game's own: set Sharpness to around 80% with them. Off is no upscaler at all: the game's own network is left out too, and the 3D is stretched to the output with a plain linear filter (the fastest choice, below). DLSS model chooses their network (below). Render resolution is the 3D's share of the output. The Window scaling filter then scales the frame to your window, and Sharpness sharpens it, by the picture's pixels: when the window is much larger than the picture (the Handheld Profile's 1536x864 on a 4K screen), a Sharpness kept from an older version is stronger than it was, so a lower one may suit.
- Aspect ratio and Output resolution: the menu lists the resolutions your screen offers (its display modes, as
Windows lists them, DSR's included), with the common sizes of each of those shapes your screen does not list (1440p, 4K
and 5K at 16:9, 1920x1200 and 2560x1600 at 16:10, 3440x1440 at 21:9, ...), grouped by shape. Aspect ratio lists
the shapes, your monitor's own marked "(monitor's)" (the default: 21:9 on an ultrawide, 16:10 on a 16:10 screen);
Output resolution then lists that shape's sizes, your screen's own marked "(native)". A size larger than your
screen is drawn at that size and scaled down to the window. The marks are for the monitor the game's window is on, and
follow it: moved to another monitor, or the desktop's resolution changed while playing, the menu adds that screen's
sizes. On Linux the screen's size comes from SDL (the primary display). A portrait screen has no shape the game can
draw, so the row shows Monitor's shape as a value of its own there. Docked only. A shape other than 16:9 widens the cameras (21:9, 32:9) or narrows the
picture (16:10, 4:3, 5:4) and keeps the HUD and movies in the middle 16:9. At 16:9 on a 5120x1440 (32:9) monitor, the
game's 16:9 picture is stretched across the 32:9 output, sharp but wide. Options saved by an older version at 16:9,
the default then, move to Monitor's shape on a screen narrower than 16:9 (16:10 such as the Steam Deck's, or 4:3),
where 16:9 only adds bars above and below; an ultrawide keeps its 16:9. The output's rows below show the sizes for the
output you chose. At your screen's own size the HUD and text map pixel for pixel. Above 2560x1440 the game's render
targets get a bigger GPU pool, so a full-size 3D fits. Where the screen's modes are not known (Linux), the menu offers
1920x1080, 2560x1440, 3840x2160, 5120x1440 and 5120x2880. For a size the menu does not offer, set
output_res=<width>x<height>inhookshot_options.ini: each side a multiple of 8, at least 640x360, at most 5120x2880's pixels, and between 5:4 and 48:9 in shape; anything else uses the game's 2048x1152. The menu then offers it as its own choice. A picture wider or narrower than 16:9 is kept to 5120x2160's pixels, so above that a size of another shape is not a native frame. A size's own shape sets the camera's, even when the OS reports a single 16:9 primary monitor. For three 16:9 monitors, use5760x1080or7680x1440and a window or logical display that spans all three. Both render at full size: 7680x1440 has 5120x2160's pixels, the most a wide picture takes. For one run, setHOS_OUTPUT_RESto a size, such asHOS_OUTPUT_RES=3840x2160. - Window scaling filter matters only when your window's size differs from the Output resolution: for the sharpest picture, set the Output resolution to your screen's, and the row shows "Not needed (window = output)". It and Sharpness also work when Frame generation is Off.
- Anisotropic filtering keeps textures sharp on surfaces seen at a slant: the paths and floors ahead of Link. The game
asks for 1x or 2x, which at a PC's resolutions smears the ground a few metres off; 16x costs little on most cards, and
Game's is the console's own.
RX_VK_ANISO=<n>sets it for one run (0: the game's). - Upscaler Off (
dlss=6inhookshot_options.ini) is for slow GPUs and for measuring: no DLSS, no FSR, and not the game's own network either, which otherwise runs on every frame (at the game's usual 3/4 share it scales the 3D up and smooths its edges; at 100% a pass of the same kind still smooths them). In its place the 3D is stretched to the output with a linear filter, and the HUD is drawn over it at the output's size as always. Nothing is kept from frame to frame, so there is no ghosting, but no anti-aliasing either: edges are jagged, and below 100% the picture is soft. The Render resolution then sets the 3D's size alone (Auto, 100%, 75%, 67%, 50%, 33%): lower is faster. RX_VK_DLSS, RX_VK_FSR4 and RX_VK_FSR set for a run go over it, as over the row's other choices. - Texture detail with DLSS, FSR 3.1 or FSR 4: DLSS and DLAA sample the world's textures as NVIDIA's DLSS guide asks:
at the output's size and one mip step finer (the game's own bias + log2(3D / output) - 1), which DLSS resolves over its
frames, so they keep the detail of the full-size picture instead of the 3D's smaller size. FSR 3.1 and FSR 4 sample them
one finer mip step for each halving of the 3D below 75% (the game already does so for its own 75%).
RX_VK_UPSCALE_LOD_BIAS=0turns it off;RX_VK_DLSS_LOD_OFFSET=<steps>sets DLSS's extra step for a run (-1 by default, 0 for none, down to -3). - NVIDIA Reflex Off is the game as without it.
RX_VK_REFLEX_LOG=1logs the driver's latency timings every 300 frames while it is on. - AMD Anti-Lag 2 Off is the game as without it. It works with Frame generation too: each game frame's present stage is given when that frame itself is shown, not at the made frames before it.
- Profile runs the game as the console docked (at the Output resolution) or Handheld (1536x864): lighter on the GPU.
- Mesh shaders (how the game's mesh programs, much of the scenery, run) is no longer a menu row: changing it made
the next start translate every shader again. The game uses the GPU's own mesh shaders where it has them, and the
compute path where it has not and on Linux AMD cards (issue 2245). For troubleshooting,
RX_VK_MESH_SHADERS=computeinhookshot_env.txtuses the compute path on every GPU (try it if your card crashes or leaves objects out; usually a little slower), andRX_VK_MESH_SHADERS=nativethe GPU's own for every draw. Amesh_shaders=line left inhookshot_options.iniis no longer read. - Ultrawide menus: with the Aspect ratio at the monitor's shape, the pause, item and map menus stay in the middle 16:9, with what the game draws beside them out of focus, or black; Full width stretches them over the whole screen, as before. Loading screens and pre-rendered movies get the same sides. It changes at once.
- V-Sync: Auto is mailbox where the driver has it (no tearing, no wait for the display); otherwise On, or on Windows
Off. On waits for each refresh (FIFO): no tearing, at most the display's rate. Off shows each frame at once and can
tear (where the driver cannot, it is Auto). It changes at once.
RX_VK_FIFO=1(On) orRX_VK_IMMEDIATE=1(Off) chooses for one run. - Robust buffers (Debug tab, Developer): a read past a buffer's end is dropped instead of stopping the GPU. Auto is on, on every card; Off can be faster on some NVIDIA cards.
- ASTC as RGBA8 (Debug tab, Developer): the AMD texture workaround below.
- Game speed: with Per frame, the game runs slower whenever it is below 60 fps. Real time keeps it at normal speed down to 15 fps.
- FPS counter shows in a corner (FPS counter position; at the top right while the menu is open), at one of
four levels. FPS is the number alone (an options file's old On); with frame generation on, it also shows the
game's own rate and who makes the frames:
Base 60, DLSS FG(NVIDIA DLSS Frame Generation),FSR 3.1 FGorBuilt-in FG. Frame time adds the game's frame time and its 1% low (the rate of the slowest 1% of frames over the last 10 seconds). From this level on, the number and the frame time are green at the Game frame rate cap's rate, amber under it and red under two thirds of it. (The cap's rate is the display's refresh instead with V-Sync On when that is slower; with Uncapped and V-Sync not On there is no line, and the colours are against 60.) Graph adds the frame times of the last 4 seconds (each point the slowest frame of its span, so no stutter is missed), with a dashed line at the Game frame rate cap's frame time and a red mark over frames that took more than twice it; its scale follows the usual frame, so a spike is drawn at the top rather than flattening the rest. Breakdown adds where the frame's time went on the game's presenting thread, as a bar and in numbers: the game's own code (Game), recording and submitting the GPU's work (Renderer), waiting for the GPU (GPU wait), and waiting for the frame's turn (Pacing: the frame rate cap, vsync, Reflex); then the GPU's own time per frame, and the shaders built and draws left out in the last 4 seconds (red marks on the graph where they happened, the usual cause of a stutter). - Volume scales the game's whole sound, on top of the game's own sound settings and Windows' volume. Its steps follow a curve so they sound about even: 50% is a quarter of the level (-12 dB). Mute in background silences the game while another window has the focus; an overlay such as Steam's or Discord's does not count as another window while the game was in front.
- Audio output is the speakers the game mixes its sound for. Auto is 5.1 when your default output device has 5.1
or more speakers, else stereo; Stereo or 5.1 chooses one whatever the device has (5.1 on stereo speakers is mixed
down). Auto counts the speakers Windows names, not the channels: an audio interface whose outputs are not set up as
surround speakers (a Focusrite Scarlett's 8 outputs, for one) is stereo, so voices and the ocarina do not go to an
output with nothing connected. For one run,
HOS_AUDIO_CHANNELS=2or6chooses stereo or 5.1 and wins over the menu. - Microphone is what the ocarina hears when the game's own microphone option is on (an instrument, or humming).
Default follows Windows' default recording device; the list shows each microphone by name, and a change applies at
once. A chosen microphone that is unplugged stays chosen (shown as not connected): Default stands in until it is
back. On Linux (SDL2) two microphones with the same name cannot be told apart: the first is used. Windows must allow desktop apps to use the microphone
(Settings, Privacy & security, Microphone).
HOS_MIC_LOG=1logs what the game reads, a line a second. - Game language is the game's own text,
language.txtin the game folder: the row writes it once you leave the row, and the game reads it at its next start (HOS_LANGUAGE, when set, wins over the file, as for the game). Where the folder cannot be written the row goes back to the file's language. Menu language is this menu's: Auto follows the language the game runs in until the restart (English (UK) and French (Canada) take English and French). The translations are machine-made and want checking by speakers of each language: each is one line ingpu/vk/menu_i18n.h. Place and item names stay English for now. Japanese, Chinese and Korean letters come from the game's own fonts for them, with Windows' (Yu Gothic, Microsoft YaHei, Microsoft JhengHei, Malgun Gothic) or Linux's Noto CJK where a game font lacks one. - Discord status shows "Playing Hookshot" and the time played in your Discord status. It is on by default and does nothing unless a Discord client is running on this PC; with the row Off nothing is sent to it.
- Controller in background: On keeps the controller working while another window has the focus. The keyboard and mouse still need the game's window.
- Mouse camera: Native turns the camera with the mouse one to one, as in a PC game. As the stick uses the mouse in place of the right stick. The - and = keys change the sensitivity in game too. When another camera takes over, Native leaves it alone; on returning, mouse look starts from the game's current pitch and yaw rather than restoring the old view.
- Disable camera centering: On stops the game gradually turning the camera toward your movement, so it does not fight native mouse look. Off keeps the game's standard behavior. Changes apply immediately with either Mouse camera mode. Manual controls, explicit recentering and scripted camera headings still work; automatic pitch adjustment is unchanged.
- Camera speed is how fast the right stick turns the camera, in percent of the game's own speed. The camera keys follow it, and so does the mouse with Mouse camera on As the stick; Native mouse look has its own sensitivity. The game's own camera speed option still picks the speed this multiplies.
- Stick dead zone: how far a stick moves from center in any direction before it counts. Default is about 24%. Use a lower value for a precise stick or a higher one for a stick that drifts. The game also applies its own dead zone.
- Auto run: the sprint goes on after the run button (A) is let go. Hold A for 0.4 s while moving (the roll, then the sprint, as usual), let go, and A stays held for the game while the stick stays pushed; a short press (a roll on its own) is not kept. Letting go of the stick or pressing A again stops it (a long hold keeps it again). Only while Link is yours to move: an event (a talk, a cutscene), the pause menu, the map, the Insert menu and the ocarina's notes end it, so A never picks an entry, skips text or plays a note there.
- Rumble strength scales the controller's rumble: 100% is the game's own, Off turns it off. The game's HD rumble goes to a controller's heavy and light motors by its frequency.
- Motion controls (Controls tab, Motion page): the controller's gyroscope aims where the game uses motion, as on the Switch. It works with
Switch Pro controllers and pads in Switch mode, DualSense and DualShock 4 (through SDL). Its row
says whether the connected pad has a gyroscope; Off leaves the game seeing a pad lying still. Motion sensitivity X/Y
scale the left-right and up-down aim (100% is the console's), Invert motion X/Y turn either direction around. The game gets the motion
state as a Switch (and Eden) builds it, so how you hold the pad when motion starts does not matter. Motion follows the pad used
last. The gyroscope's drift is learned while the pad rests on a table, so set it down for a second if the aim
creeps.
HOS_MOTION_DEBUG=1(inhookshot_env.txt) logs what the game gets twice a second. - Layout preset: Nintendo has A on the right face button, Xbox / PC and Swap Face put A on the bottom one. Changing a button yourself sets it to Custom.
- Button prompts (on the Controls page): the button icons in the game's texts, hints and menus. Auto shows the first controller's; with no controller connected, the keyboard's. Keyboard shows the key or mouse button your controls put each action on (the first of its two), and WASD and the mouse for the sticks; the ocarina's notes and the pause menu's controller keep the Switch's buttons.
- Save my pipeline list (Debug tab, under Developer): see Send your pipeline list.
Use a controller, or the keyboard and mouse. On the keyboard, W A S D move and the arrow keys (or I J K L) turn the camera. With the default keyboard bindings, press E to select New Game on the title screen.
Mouse in the game's menus (Windows): the title screen and its file list, the pause menu, the Key Items, Threads of Time and Map pages, the options and the save dialogs free the mouse while they are shown. Point at an entry to select it, left-click to choose it (A) and right-click to go back (B); the tabs, the L and R signs and the Back prompt can be clicked too. The wheel turns the pause menu's pages and scrolls lists; on the map it changes floors and zooms. Drag with the left button to pan the map and the tapestry or turn a stone on Key Items. The cursor stays hidden while you play on a controller or the keyboard, until the mouse moves.
Rumble: a Nintendo Switch Pro Controller or Joy-Con plays the game's HD rumble as the Switch does, each side and
both frequency bands as the game asks, with SDL3 (the Windows game brings it; on Linux the system's SDL3, where it has
one). Other controllers, Switch 2 controllers, a pair of Joy-Cons used as one controller, and SDL2's own library get
the game's rumble on their two motors. The menu's Rumble strength scales it too. HOS_HD_RUMBLE=0 sends the Switch
controllers the motor rumble too. On Linux, SDL talks to the Switch controller itself through its hidraw device, which
needs read and write access for your user; Steam's udev rules (the steam-devices package on most distributions) give
it. Without them the kernel's hid-nintendo driver runs the controller, and it gets the motor rumble. HD rumble goes to
anything SDL reports as a Switch Pro Controller or Joy-Con, and that includes third-party controllers in Switch mode
(8BitDo, GameSir and others; SDL gives them Nintendo's ids). Some of them may turn it into weak rumble or none: set
HOS_HD_RUMBLE=0 to give them the plain motor rumble.
To change which gamepad button or key presses a Switch button, or which keys move and turn the camera, open the
Controls tab's Controls page. Choose a row and a column (Input 1 or 2 for the gamepad, Key 1 or 2 for the keyboard: each
control takes two of each), press Enter (or the bottom face button), then the new button or key. Esc cancels, Delete clears it, and Reset to defaults
puts them all back. A gamepad button taken from another Switch button swaps with it. The page saves them in
hookshot_options.ini.
Ocarina notes: the page gains five rows, Ocarina note (L), (R), (A), (Y), (X), unset by default: the game's own
buttons play until you bind a note to a key or gamepad input of your own, and a bound note then answers only that input while
the game waits for it. A dialogue or cutscene that takes the buttons ends the wait, and a song lesson keeps the game's own too.
Writing the controls in hookshot_options.ini yourself
pad_a=0
key_a=69,13pad_<button> is a gamepad input by position: 0 bottom face button, 1 right, 2 left, 3 top, 4 Select or Back, 5 Home,
6 Start, 7 and 8 the stick presses, 9 and 10 the shoulder buttons, 11 to 14 the D-pad (up, down, left, right), 15 and
16 the triggers, -1 none. key_<button> is one or two
Windows key codes in decimal (69 is
E, 13 Enter), 0 none; the mouse's buttons are 1 (left), 2 (right), 4 (middle), 5 and 6 (side
buttons), and count while the mouse is captured. The buttons are a b x y l r zl zr plus minus ls
rs left up right down, for keys only the left stick's and the camera's directions: move_up
move_down move_left move_right cam_up cam_down cam_left cam_right, and the ocarina's five notes,
which also take a pad_ line: note_l note_r note_a note_y note_x. A button the file leaves out keeps
its default.
Put mods in the game folder's mods folder, in the layout emulators use (mods/<name>/romfs/...). Unlike Hookshot,
BlueShell also applies code mods: .pchtxt and .ips patches in mods/<name>/exefs are applied to the game's code
before it is translated, so they need a rebuild (Update in the Builder). Tested with GameBanana's Ultrawide + HUD Fix:
set Aspect ratio to 16:9 and Stretch to window on with it. Mods are not included in releases: download them
from their own pages.
BlueShell builds the same way as Hookshot: see Hookshot's
Build from source. The Builder (builder/BlueShellBuilder)
runs nx2/make_game.py for you.
BlueShell is Hookshot with Mario Kart World's own changes, so it exists thanks to everyone who made Hookshot:
- NotRexed: Hookshot, BlueShell (Mario Kart World), Skybound (Tears of the Kingdom) and the a64-kit tools.
- Eden and Eglantine: the shader recompiler and Switch 2 shader work.
- suyu: the graphics decoders and the AArch64 translator.
- seedds/nxnative: reference for how task and mesh shaders work.
- EvilBoyce / evilmfkr (EvilOOT): the GPU culling that brings back Kokiri's foliage (trees, ferns, grass, falling leaves, fireflies), the ambient light probes, the pond's water, the game's own fog, the freeze after Load (Horizon's mutex handoff) and the exposure flicker fix.
- zortos293/Lichii: reference for Ampere shader lowering, and its compare-exchange retry fix.
- mstorsjo/llvm-mingw: the bundled Windows compiler (no Visual Studio needed).
- NVIDIA DLSS: builds made with NVIDIA's DLSS SDK (optional, downloaded by each build, never bundled) use NVIDIA DLSS Super Resolution, NVIDIA's technology. NVIDIA and DLSS are trademarks of NVIDIA Corporation.
- AMD FSR 3.1 and FSR 4: every build has AMD FidelityFX Super Resolution 3.1, built from AMD's MIT-licensed FidelityFX SDK shaders; builds made with FSR 4 (optional; AMD's DLLs are never bundled) use AMD FidelityFX Super Resolution 4 through AMD's MIT-licensed FSR API headers. Both are AMD's technology. AMD, Radeon and FidelityFX are trademarks of Advanced Micro Devices, Inc. Longshot: Fork of Hookshot, for some bug fixes and launcher additions
- kinnay/zbic, Opus and SDL: decompression, audio and controllers.
- sostenesfreitas/ocarina-recomp: this README's layout, and its notes confirmed the mesh stage's control section.
- MythosOfs/Orchid: the fog and exposure workaround Ocarina of Time used before its fog and lighting were fixed.
- Mesa (NAK): the reference for Ampere's instruction encoding.
- Everyone who sent fixes: SkippySteve (Linux and the AppImage, and many more), monsterlag, klimovich008, hckrman101 (NVIDIA DLSS, DLAA and Reflex, the exposure flicker and fog fixes, build speed, CI), madebyjordan (AMD FSR 4.1), N3oTraX (FSR 4 on Linux), shayderrr, gab9281, Wpaif, nicholasgower, ZurielAtr, Joey-Magnus, Zorkats, d3zessete, chrispository, vzeol, leonidasmark, Segmentree, ShyVortex, hiKareeem and i900gaming, among others.
- adriadam10/mkw-recomp and Ca1nM's save editor (MIT): Unlock everything.
BlueShell, like Hookshot, is free software under the GNU General Public License, version 3 or later (GPL-3.0-or-later). It includes code from Eden and suyu, which are under the GPL too. Third-party parts under other licenses that work with the GPL (Sirit, the Vulkan Memory Allocator, SDL, Opus, Dear ImGui, zstd, the Libertinus fonts, zbic and the a64-kit tools) keep their own notices in their folders.
BlueShell is an unofficial fan project, not affiliated with or endorsed by Nintendo. Mario Kart is a trademark of Nintendo.
