diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml deleted file mode 100644 index 0a441a73..00000000 --- a/.github/FUNDING.yml +++ /dev/null @@ -1 +0,0 @@ -custom: ['https://www.donationalerts.com/r/another project'] diff --git a/.github/ISSUE_TEMPLATE/1-crash.yml b/.github/ISSUE_TEMPLATE/1-crash.yml index 085ec4de..f6235128 100644 --- a/.github/ISSUE_TEMPLATE/1-crash.yml +++ b/.github/ISSUE_TEMPLATE/1-crash.yml @@ -5,41 +5,21 @@ body: - type: markdown attributes: value: | - Check the pinned issues at the top of the issue list first: they cover the known crashes and their workarounds. + Search the open and closed issues for this crash first. Do not attach or link game files, keys, firmware or builds. Issues that do are closed. - - type: checkboxes - id: duplicates - attributes: - label: Existing issues - options: - - label: I read the pinned issues and [searched open and closed issues](https://github.com/another recompilation project/issues?q=is%3Aissue) for this crash. - required: true - type: input id: version attributes: label: Version - description: The title line of the settings menu (F1), for example "NX2navi 0.1.0, game 1.4.3". + description: The title line of the settings menu (F1), for example "Ocarina Recomp 0.0.1-ocarina - game 1.1.1". validations: required: true - type: input - id: last-good - attributes: - label: Last version that worked - description: If an earlier version did not crash at this point, which one. - - type: textarea id: system attributes: - label: System info - description: Paste what Copy system info (F1, Advanced tab) puts on the clipboard. On a Steam Deck, add LCD or OLED. - render: text - validations: - required: true - - type: textarea - id: mods - attributes: - label: Mods and cheats - description: The folders in mods/ with their download links, or "none". Say whether it also crashes without them. + label: GPU, driver and Windows version + description: For example "RTX 4070, driver 591.44, Windows 11 24H2". validations: required: true - type: dropdown @@ -47,11 +27,11 @@ body: attributes: label: When does it crash? options: - - At startup, before the Nintendo logo - - Between the Nintendo logo and the title screen + - At startup, before the title screen - While loading a save - In gameplay - In a cutscene + - In a menu validations: required: true - type: dropdown @@ -74,9 +54,7 @@ body: value: | ### The log - - The log of the run that crashed is `logs\nx2navi.log` in the folder of `nx2navi.exe` (F1, Advanced tab, Open log folder). Copy it before you start the game again: the next start renames it to `nx2navi.1.log`, and after five starts it is gone. - - Attach the whole file. Do not cut or edit it: the crash report is at the end, the GPU and driver lines are at the start. - - The log says `device lost` or `VK_ERROR_DEVICE_LOST` and the GPU is an NVIDIA one: set GPU pass marks to On (F1, Advanced tab, Diagnostics), restart the game, make it crash again and attach that log. The `vk: pass marks` lines then name what the GPU was drawing. + The log of the run that crashed is `logs\nx2navi.log` in the game's folder. Copy it before you start the game again: the next start renames it to `nx2navi.1.log`, and after five starts it is gone. Attach the whole file without editing it. - type: textarea id: log attributes: @@ -84,17 +62,8 @@ body: description: Drag nx2navi.log into this field. validations: required: true - - type: markdown - attributes: - value: | - ### Save and input recording - - When the crash comes back at one place in the game (an area, a shrine, a cutscene, a quest step), the save that gets there lets us crash it on our machine. - - 1. Zip the `profile` folder next to `nx2navi.exe` and attach it. Say which slot you load, or that you use the autosave. - 2. If it takes more than walking a few steps from the save: turn on Input recording (F1, Advanced tab, Diagnostics), restart the game, load the save, make it crash, and attach `input-record.txt` from the logs folder together with the `nx2navi.log` of that run. - type: textarea id: save attributes: - label: Save and input recording - description: Drag the zipped profile folder and input-record.txt into this field, when the crash comes back at one place. + label: Save + description: When the crash comes back at one place, zip the `profile` folder next to the game and attach it, and say which file you load. diff --git a/.github/ISSUE_TEMPLATE/2-graphics.yml b/.github/ISSUE_TEMPLATE/2-graphics.yml index ccbf1cbc..9588b7d1 100644 --- a/.github/ISSUE_TEMPLATE/2-graphics.yml +++ b/.github/ISSUE_TEMPLATE/2-graphics.yml @@ -1,74 +1,38 @@ -name: Graphics glitch -description: Artifacts, missing or broken textures, flicker, wrong colours or shadows. +name: Graphics problem +description: Something is drawn wrong, missing, flickering, too dark or too bright. labels: [bug, graphics] body: - type: markdown attributes: value: | - Check the pinned issues at the top of the issue list first: they cover the known glitches on each GPU. - - Do not attach or link game files, keys, firmware or builds. Issues that do are closed. - - type: checkboxes - id: duplicates - attributes: - label: Existing issues - options: - - label: I read the pinned issues and [searched open and closed issues](https://github.com/another recompilation project/issues?q=is%3Aissue) for this glitch. - required: true + Search the open and closed issues first. A screenshot of the problem helps most; add the place in the game where it happens. - type: input id: version attributes: label: Version - description: The title line of the settings menu (F1), for example "NX2navi 0.1.0, game 1.4.3". + description: The title line of the settings menu (F1). validations: required: true - type: input - id: last-good - attributes: - label: Last version that worked - description: If an earlier version drew this correctly, which one. - - type: textarea id: system attributes: - label: System info - description: Paste what Copy system info (F1, Advanced tab) puts on the clipboard. It lists the settings you changed too. On a Steam Deck, add LCD or OLED. - render: text + label: GPU, driver and Windows version validations: required: true - type: textarea - id: mods + id: what attributes: - label: Mods and cheats - description: The folders in mods/ with their download links, or "none". Say whether the glitch also shows without them. Turn off ReShade and other overlays that draw into the game before you report. + label: What looks wrong, and where + description: The area, the time of day, what Link is doing. Drag screenshots into this field. validations: required: true - type: textarea - id: screenshot + id: settings attributes: - label: Screenshot or video - description: Drag the file into this field. Say where in the game it was taken. Flicker needs a video. - validations: - required: true - - type: textarea - id: details - attributes: - label: What looks wrong and when - description: Does it show all the time, in one place, or after some time in play? Does it go away after a restart, or when you change a setting? - validations: - required: true - - type: dropdown - id: blocker - attributes: - label: Can you keep playing? - options: - - "Yes" - - "No, I cannot see enough to play" - validations: - required: true + label: Settings changed from the defaults + description: Scaling, widescreen, frame rate limit and anything else you changed in the menu, or "none". - type: textarea id: log attributes: label: Log - description: Drag logs\nx2navi.log from the folder of nx2navi.exe into this field, from the run that showed the glitch. Copy it before you start the game again. - validations: - required: true + description: Drag `logs\nx2navi.log` from the game's folder into this field. diff --git a/.github/ISSUE_TEMPLATE/3-performance.yml b/.github/ISSUE_TEMPLATE/3-performance.yml index d810653e..9fdfaa6d 100644 --- a/.github/ISSUE_TEMPLATE/3-performance.yml +++ b/.github/ISSUE_TEMPLATE/3-performance.yml @@ -1,108 +1,44 @@ -name: Performance -description: Low frame rate, freezes, hitches, stutter or long loading. +name: Performance problem +description: Low frame rate, stutter or long loading. labels: [performance] body: - - type: markdown - attributes: - value: | - Check the pinned issues at the top of the issue list first. - - Shaders the setup did not prepare are built the first time they are needed, so a short hitch the first time an area or effect shows is expected. Report it when it happens again in the same place. - - Do not attach or link game files, keys, firmware or builds. Issues that do are closed. - - type: checkboxes - id: duplicates - attributes: - label: Existing issues - options: - - label: I read the pinned issues and [searched open and closed issues](https://github.com/another recompilation project/issues?q=is%3Aissue) for this problem. - required: true - type: input id: version attributes: label: Version - description: The title line of the settings menu (F1), for example "NX2navi 0.1.0, game 1.4.3". + description: The title line of the settings menu (F1). validations: required: true - type: input - id: last-good - attributes: - label: Last version that ran better - description: If an earlier version was faster in the same place, which one. - - type: textarea id: system attributes: - label: System info - description: Paste what Copy system info (F1, Advanced tab) puts on the clipboard. It lists the settings you changed too. On a Steam Deck, add LCD or OLED. - render: text + label: CPU, GPU, driver, RAM and Windows version + validations: + required: true + - type: textarea + id: what + attributes: + label: What happens, and where + description: The frame rate you see (performance overlay, F10), the place in the game, and whether it is constant or in bursts. A screenshot with the full overlay on helps. validations: required: true - type: dropdown - id: machine + id: first attributes: - label: Machine + label: Only on the first start? + description: The first start after an install, a game update or a driver update prepares shaders and can stutter for a while. options: - - Desktop PC - - Laptop, on mains power - - Laptop, on battery - - Steam Deck - - Other handheld PC + - "No, it happens every time" + - "Yes, only on the first start" validations: required: true - type: textarea - id: mods + id: settings attributes: - label: Mods and cheats - description: The folders in mods/ with their download links, or "none". - validations: - required: true - - type: dropdown - id: kind - attributes: - label: What kind of problem? - options: - - The frame rate is low all the time - - Short freezes or hitches that come back in the same place - - The frame rate is fine, but motion is not smooth - - It gets slower the longer I play - - Loading takes long - validations: - required: true - - type: textarea - id: where - attributes: - label: Where and what you were doing - description: For example "Lookout Landing, walking to the tower", "the Depths below Hyrule Castle", "fighting a Talus in the Sky". How long into the session it started. - validations: - required: true - - type: textarea - id: overlay - attributes: - label: Performance overlay - description: Press F10 twice (or both stick clicks) for the full panel. Stay a minute in the place and write down the frame rate, the mean and the longest frame time, or attach a screenshot of the panel. - validations: - required: true - - type: markdown - attributes: - value: | - ### Recording the log - - 1. In the settings menu (F1), Advanced tab, Diagnostics: turn on Performance log. For freezes and hitches, also turn on Flight recorder. Restart the game: both take effect at the next start. - 2. Play at least three minutes in the place where it happens. The log gets a frame-time summary every 60 s, and a line for every frame over 50 ms that names what the frame waited for. - 3. With the flight recorder on, press F8 right after a hitch. It also saves on its own after every frame longer than the freeze threshold (100 ms), at most once per 10 s. - 4. Close the game with Quit game in the menu or the window's close button. Do not end it from Task Manager: the last summary is written when the game exits. - 5. Copy `logs\nx2navi.log` from the folder of `nx2navi.exe` before you start the game again. - 6. Each flight recorder save is a folder; the log line `flight: dump` names it. Zip the folders and attach them. - 7. Turn both off again afterwards: they cost a little frame time. + label: Settings changed from the defaults + description: Window size, scaling, widescreen, frame rate limit, presentation, or "none". - type: textarea id: log attributes: label: Log - description: Drag nx2navi.log into this field. - validations: - required: true - - type: textarea - id: flight - attributes: - label: Flight recorder saves - description: Drag the zipped folders into this field, for freezes and hitches. + description: Drag `logs\nx2navi.log` from the game's folder into this field. diff --git a/.github/ISSUE_TEMPLATE/4-bug.yml b/.github/ISSUE_TEMPLATE/4-bug.yml index 4f9896de..7bb9ba64 100644 --- a/.github/ISSUE_TEMPLATE/4-bug.yml +++ b/.github/ISSUE_TEMPLATE/4-bug.yml @@ -1,94 +1,35 @@ name: Other bug -description: Sound, controls, the settings menu, the installer, or game logic. +description: Input, sound, saves, settings or anything else that does not work as on the console. labels: [bug] body: - - type: markdown - attributes: - value: | - Check the pinned issues at the top of the issue list first. Crashes, graphics glitches and performance have their own templates. - - Do not attach or link game files, keys, firmware or builds. Issues that do are closed. - - type: checkboxes - id: duplicates - attributes: - label: Existing issues - options: - - label: I read the pinned issues and [searched open and closed issues](https://github.com/another recompilation project/issues?q=is%3Aissue) for this bug. - required: true - - type: dropdown - id: area - attributes: - label: Area - options: - - Audio - - Controls and input - - Settings menu and overlay - - Installer - - Game logic and physics - - Something else - validations: - required: true - type: input id: version attributes: label: Version - description: The title line of the settings menu (F1), for example "NX2navi 0.1.0, game 1.4.3". For the installer, the version of NX2navi-Setup. + description: The title line of the settings menu (F1). validations: required: true - type: input - id: last-good - attributes: - label: Last version that worked - description: If an earlier version did this correctly, which one. - - type: textarea id: system attributes: - label: System info - description: Paste what Copy system info (F1, Advanced tab) puts on the clipboard. On a Steam Deck, add LCD or OLED. For the installer, write your OS and the install disk. - render: text + label: System + description: GPU, Windows version, and the controller if it is an input problem. validations: required: true - type: textarea - id: mods + id: what attributes: - label: Mods and cheats - description: The folders in mods/ with their download links, or "none". Say whether it also happens without them. - validations: - required: true - - type: dropdown - id: blocker - attributes: - label: Can you keep playing? - options: - - "Yes" - - "No, it stops the game or a quest" + label: What happens, and what you expected validations: required: true - type: textarea id: steps attributes: - label: What happened and how to reproduce it - description: What you expected, what happened instead, and the steps that lead there. + label: Steps to make it happen validations: required: true - - type: markdown - attributes: - value: | - ### What to attach for your area - - Close the game with Quit game in the menu or the window's close button, then copy `logs\nx2navi.log` from the folder of `nx2navi.exe` before you start the game again. - - **Audio.** Open `nx2navi.ini` in the folder of `nx2navi.exe` and add the line `trace = audio`; when the file already has `trace = perf` (Performance log on), change it to `trace = perf,audio`. Start the game, play at least two minutes where the sound goes wrong and close the game. The log then has an `audio:` line every 5 s with the buffer underruns. Name the output device and how it is connected (speakers, headphones, USB, Bluetooth, HDMI), and attach a short video with sound if you can. Remove the line afterwards. - - **Controls and input.** Name the controller and how it is connected (USB, Bluetooth, Steam Input). Does it also happen with keyboard and mouse? - - **Controls, game logic, anything you can trigger again.** Turn on Input recording (F1, Advanced tab, Diagnostics), restart the game, load a save, make the bug happen and close the game. Attach `input-record.txt` from the logs folder and a zip of the save you loaded: the `profile` folder next to `nx2navi.exe`. The recording replays what you did, so we can see the bug on our machine. - - **Installer.** Attach the newest `install-*.log` from `temp\logs` in the folder of `NX2navi-Setup.exe` (on Linux: `.setup-temp/logs` in the install folder), and the log file the error message names. - type: textarea id: log attributes: - label: Log and other files - description: Drag nx2navi.log and the files your area asks for into this field. - validations: - required: true + label: Log + description: Drag `logs\nx2navi.log` from the game's folder into this field. diff --git a/.github/ISSUE_TEMPLATE/5-feature.yml b/.github/ISSUE_TEMPLATE/5-feature.yml index 5ff0f34b..c081d6b0 100644 --- a/.github/ISSUE_TEMPLATE/5-feature.yml +++ b/.github/ISSUE_TEMPLATE/5-feature.yml @@ -2,13 +2,9 @@ name: Feature request description: A setting, option or support for something the port does not do yet. labels: [enhancement] body: - - type: checkboxes - id: duplicates + - type: markdown attributes: - label: Existing issues - options: - - label: I [searched open and closed issues](https://github.com/another recompilation project/issues?q=is%3Aissue) and the Planned section of the README for this request. - required: true + value: Search the open and closed issues for this request first. - type: textarea id: request attributes: diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index d5dc6718..3ba13e0c 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -1,5 +1 @@ blank_issues_enabled: false -contact_links: - - name: Question or help with setup - url: https://github.com/another recompilation project/discussions - about: Installing, updating and configuring the port. Ask in Discussions. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ceabb907..bc1857ac 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -25,7 +25,8 @@ GPL projects (the hardware, suyu, OpenSmash-Ultimate, Unicorn inside the game bi ## Reporting bugs -Use the issue form. Include the port version and game update from the title line of the settings menu (F1), your GPU and driver (Copy system info in the menu's Advanced tab copies them), the log (`logs\nx2navi.log` next to `nx2navi.exe`; after a crash, copy it before you start the game again), and the steps to reproduce. Screenshots are fine; recordings of long gameplay are not needed. +Use the issue form. Include the port version and game update from the title line of the settings menu (F1), your GPU and driver, the log (`logs +x2navi.log` in the game folder; after a crash, copy it before you start the game again), and the steps to reproduce. Screenshots are fine; recordings of long gameplay are not needed. ## Pull requests diff --git a/README.md b/README.md index 911df4df..a2d539e2 100644 --- a/README.md +++ b/README.md @@ -12,16 +12,22 @@ version 1.1.1) into a native x86-64 application for Windows, with a Vulkan rende ## Status -Early development. Kokiri Forest and the areas around it play at 60 fps; visual bugs and crashes are still expected. +Early development. Kokiri Forest and the areas around it play at 60 fps and above; visual bugs and crashes are still +expected. + +## Screenshots + + Report problems as issues, following [CONTRIBUTING.md](CONTRIBUTING.md). ## Features - Native code, not emulation -- 60 fps, at the game's own resolution +- 60 fps by default, or a limit of 30 to 240 fps, the display's refresh rate or unlimited +- Native widescreen and ultrawide (the window's shape, 21:9 or 32:9) with the HUD, menus and movies kept 16:9 - AMD FSR 1 or bilinear scaling to the window, with a sharpness setting; black bars or stretch -- Colour profiles and brightness, contrast, saturation and gamma settings - In-game settings menu (F1, or Minus and Plus together on a gamepad) and performance overlay (F10) - Keyboard, mouse and gamepads with remapping, Nintendo or Xbox button layout, rumble and gyro; the game follows whichever connected gamepad you press diff --git a/config.example.toml b/config.example.toml index 0f1e2a53..01b04719 100644 --- a/config.example.toml +++ b/config.example.toml @@ -1,11 +1,11 @@ # Copy to config.local.toml (ignored by git) and point it at your own files. [input] -# Base game 1.0.0, title id 0100F2C0115B6000, as NSP or XCI. +# The base game, dumped from your own console as NSP or XCI. base = 'C:\Games\NX2navi\base.nsp' -# Cumulative update NSPs, title id 0100F2C0115B6800. Each is identified by its code hash; 1.4.3 and 1.2.1 are supported. -# Leave the list empty for 1.0.0 only. -updates = ['C:\Games\NX2navi\update-1.4.3.nsp'] +# The update NSP, identified by its code hash; 1.1.1 is supported. +# Leave the list empty to build the base version. +updates = ['C:\Games\NX2navi\update-1.1.1.nsp'] # Keys dumped from your own console. Never printed or copied by the tools. keys = 'C:\Switch\prod.keys' # Optional: a firmware NCA directory (an unpacked firmware, or an emulator's installed registered/ directory). diff --git a/docs/cheats.md b/docs/cheats.md deleted file mode 100644 index 5ba2f3c2..00000000 --- a/docs/cheats.md +++ /dev/null @@ -1,74 +0,0 @@ -# Cheats - -The port reads Atmosphère cheat files, the format Switch homebrew and the emulators use. It ships no cheat files: a cheat file goes into a mod in the `mods` folder next to `nx2navi.exe`, like any other mod ([mods.md](mods.md)). Open the menu (F1) and switch the cheats on the Cheats tab. The switches are saved under `[cheats]` in `nx2navi.ini`. - -## Adding a cheat file - -1. Find the cheat file for your update. Cheat sites and collections name it after the first 8 bytes of the game's build id: - - | Update | File | - |---|---| - | 1.2.1 | `9B4E43650501A4D4.txt` | - | 1.4.3 | `277178B7DBA1B6D4.txt` | - - The Cheats tab names the file the installed game reads when no mod holds one, and `logs\nx2navi.log` says `cheats: no enabled mod holds cheats/.txt`. -2. Put it in the `cheats` folder of a mod, a folder of its own under `mods`: - - ``` - mods\ - My cheats\ - cheats\ - 277178B7DBA1B6D4.txt - ``` - - A download laid out for the Switch's SD card or an emulator works as it is: unpack it into a folder of its own under `mods`, and the port finds `atmosphere\contents\0100F2C0115B6000\cheats`, `contents\0100F2C0115B6000\cheats` or `0100F2C0115B6000\cheats` inside it. The file name's case does not matter. -3. Start the game. Cheats that write the game's memory work now. -4. Cheats that change the game's code need the game rebuilt with them. When the game starts and finds such cheats it did not build, it opens the setup's rebuild window, which builds them in (a few minutes; the shaders stay prepared) and starts the game again. Until then they are greyed out with "after the rebuild". When the rebuild fails or you cancel it, the game starts without them and does not try again for the same cheats; "Rebuild the game now" on the Cheats tab tries again. `mods_rebuild = off` under `[mods]` in `nx2navi.ini` turns the automatic rebuild off; running `NX2navi-Setup.exe` on the same folder does the same job by hand. Saves and settings are kept. -5. Switch the cheats on the Cheats tab of the menu. - -The Cheats tab lists the cheats grouped by mod, in the order of the Mods tab. A mod switched off on the Mods tab, or one the port cannot use, contributes no cheats; the change applies at the next start. The Mods tab says how many cheats each mod brought. - -## The file format - -Standard Atmosphère: a `[name]` line starts a cheat, `{name}` a master cheat that is always on, and the cheat's opcodes follow as 8-digit hex words. A name with no opcodes is shown as a heading. The file's title line (the one with `TID=`) is not shown. - -``` -[The Legend of Zelda: Ocarina of Time v1.4.3 TID=0100F2C0115B6000 BID=277178B7DBA1B6D4] - -[Player] -[A code cheat] -040A0000 XXXXXXXX YYYYYYYY - -[A data cheat (Hold ZL+X)] -80000104 -580F0000 XXXXXXXX -640F0000 00000000 YYYYYYYY -20000000 -``` - -The words above are placeholders: `XXXXXXXX` an offset, `YYYYYYYY` a value. - -Each cheat's switch is `cheat_ = 1`, where the hash is FNV-1a 32 of `/`. A name repeated in one file gets `#2`, `#3` and so on. The build names each code cheat the same way, so renaming a mod's folder resets its cheats' switches to off and makes the next start rebuild its code cheats. Rename the folder before you switch its cheats on. - -## How cheats run - -The game's code is compiled ahead of time, so a cheat cannot write new instructions into it while the game runs. The port sorts each cheat by what it writes (`tools/cheats.py` at setup, `runtime/cheats.c` in game): - -| Kind | What the cheat does | How the port runs it | -|---|---|---| -| code | Opcode 0 writes into main's code | Built into the game at setup as a patch set (`recomp/patches.py`); switches at once. | -| key | Code writes inside a button condition (`8` mask, writes, `21` else, the original words, `20`) | A patch set that is on while the cheat is on and the buttons are held. | -| data | Writes data only: heap, main's data, pointer chains, button conditions | Runs in a cheat VM after dmnt's, opcodes 0 to A, every presented frame while on. | -| master | `{name}` with code writes | A patch set that is always on. | -| restore | Writes back only the game's original instructions | Not needed: switching a cheat off restores them. Greyed out. | - -A cheat whose code writes call or jump into a code cave the cheat writes itself (into main's zero padding) gets the cave inlined at the call site. The setup builds the code cheats of every mod in the `mods` folder, switched on or off, so switching a mod on later needs only a restart. A code cheat added or edited after the last build waits for the rebuild; a data cheat runs at the next start. - -Not supported, and shown greyed out with the reason: - -- the 0xC and 0xF opcode extensions; -- opcode 5 with a register offset; -- code writes mixed with other opcodes, except the button pattern above; -- code writes that change the CPU flags differently from the game's instruction, or code caves with branches or pc-relative instructions. - -`build-cache\cheats.status` next to `nx2navi.exe`, written by the setup, records which cheats were built and how; the log line `cheats: ...` sums them up at start. When the code cheats cannot be built, the setup warns and installs the game without them. diff --git a/docs/mods.md b/docs/mods.md deleted file mode 100644 index c0f01e5a..00000000 --- a/docs/mods.md +++ /dev/null @@ -1,107 +0,0 @@ -# Mods - -NX2navi loads the mods players make for the Switch emulators (Ryujinx, the hardware and its forks): texture and model -packs, gameplay and text changes from GameBanana and similar sites, a mod manager's merged output, code patches (`.ips`, -`.pchtxt`) and Atmosphère cheat files. No mod or cheat file ships with the port. - -## Install a mod - -1. Open the settings menu (F1, Esc, or Minus and Plus together on a controller), go to the Mods tab and choose - **Open mods folder**. That is the `mods` folder next to `nx2navi.exe`; the menu creates it when it is missing. -2. Make one folder per mod in it and unpack the mod's archive into that folder. The mod's own folders (`romfs`, - `exefs`, `cheats`) must sit directly inside the mod's folder: - - ``` - mods\ - Better Grass\ - romfs\ - ... - Fast Travel Anywhere\ - exefs\ - patch.pchtxt - My cheats\ - cheats\ - 277178B7DBA1B6D4.txt - ``` - - An archive laid out for a Switch SD card or an emulator works as it is. Inside the mod's folder the port also finds - `atmosphere\contents\0100F2C0115B6000\romfs`, `contents\0100F2C0115B6000\romfs` and `0100F2C0115B6000\romfs`, the - same places for `exefs` and `cheats`, and `atmosphere\exefs_patches\\` for code patches. -3. Start the game. A mod that patches the game's code makes the game rebuild itself first (see Code patches below). -4. Open the Mods tab to check the mod. Each row says how many game files the mod replaces and adds, how many cheats it - brings, and why a part of it is not used. - -## Order and switches - -The Mods tab lists every folder in `mods`. Select a mod and press A or Enter to switch it on or off. The top face button -or Ctrl+Up moves it up, the left face button or Ctrl+Down moves it down. When two mods change the same file, the -higher one wins; the lower mod's row says how many of its files the higher one covers. Changes apply after a restart. - -The menu saves the order and the switches in `nx2navi.ini`, under `[mods]`, by folder name: `mods_order` and -`mods_disabled`. A folder the list does not name yet, such as a new or renamed one, goes below the named ones. - -### Mods that change the same files - -Two mods that edit the same game file do not combine: the higher one wins the whole file. Merge such mods with -[a mod manager](https://github.com/a mod manager-Team/mod manager) (NX2navi Mod Manager) and set its export location to an empty folder inside -`mods`, for example `mods\merged`. The exported folder then counts as one mod here. Mods packaged for a mod manager only -(`.tkcl` files) go the same way. - -The port merges the resource size table on its own: at every start with mods on, it combines the tables the mods ship -and raises the entries for files a mod made larger or added. A separate RESTBL mod is not needed. - -## Code patches (ExeFS) - -A mod with `.ips` or `.pchtxt` files patches the game's code. A patch is for one game update: an `.ips` file is named -after the build id of the update's code, a `.pchtxt` file names it on its `@nsobid` line. The game's code is compiled -ahead of time, so these patches are built into `nx2navi.exe`: - -1. The first start after such a mod is added closes the game and opens the setup's rebuild window. The rebuild takes - a few minutes (the shaders stay prepared), then the game starts again. Saves and settings are kept. -2. Until the rebuild succeeds, the whole mod stays off, its other files included. -3. After the rebuild the mod switches on and off from the Mods tab like any other, without another rebuild. - -The rebuild needs the setup folder the game was installed from. When that folder was moved or deleted, run -`NX2navi-Setup.exe` again on the same install folder: it does the same job. `mods_rebuild = off` under `[mods]` in -`nx2navi.ini` turns the automatic rebuild off. - -A code patch over one of the port's own patches (the 60 FPS patch, the resolution patch and the other entries under -**Built into the port**) turns that built-in patch off while the mod is on. The mod's row names it. - -## Cheats - -A cheat file is part of a mod: `mods\\cheats\.txt`, switched cheat by cheat on the Cheats tab. Cheats -that change the game's code need the same rebuild as code patches. [cheats.md](cheats.md) explains the file names for -each game update, the rebuild and which cheats cannot run. - -## Renaming a mod folder - -The port keys a mod by its folder name. A renamed folder counts as a new mod: - -- it moves below the mods the list names, and comes back switched on; -- its cheats come back switched off; -- its code patches and code cheats are built again, so the next start runs the rebuild. - -Rename mod folders before you set them up in the menu, not after. - -## What does not work - -| On the Mods tab | Why | What to do | -|---|---|---| -| This folder has no romfs, exefs or cheats files. | The archive was unpacked one level too deep (`mods\Mod\Mod\romfs`), or it holds no game files. | Move the folders up so `romfs` sits directly in the mod's folder. | -| ... files are made for another game version and are left out. | The mod's files carry another update's version in their names (`.Product..`). | Download the mod's release for your game update. | -| Its code patches (exefs) are made for another game version. | The patch files name another update's build id. | Same: get the release for your update. | -| This mod brings its own game code (a subsdk plugin or a replaced main). | Mods such as UltraCam ship compiled Switch code. The port cannot load it. | No workaround; the whole mod stays off. | -| This mod patches the game code (exefs) in a way the port cannot apply. | The patch writes the game's data, not its code, or changes code in a form the port cannot build. | No workaround; the reason follows on the row. | -| The folder name contains \|. | The mod list uses `\|` between names. | Rename the folder. | - -A mod never stops the game from starting. Whatever the port cannot use is left out and shown on the Mods tab. - -## When something looks wrong - -1. Switch the newest mod off on the Mods tab and restart. If the problem goes away, check that the mod is made for your - game update and does not fight another mod over the same files. -2. `logs\nx2navi.log` next to `nx2navi.exe` names every mod at the start (lines starting with `mods:`), the cheats - (`cheats:`) and the resource size table (`RomFS: resource size table:`). Open log folder on the Advanced tab of - the menu shows the logs. -3. When reporting a problem, attach `nx2navi.log` and list your mods with the links you downloaded them from. diff --git a/docs/tester-guide.md b/docs/tester-guide.md deleted file mode 100644 index 0be997ea..00000000 --- a/docs/tester-guide.md +++ /dev/null @@ -1,109 +0,0 @@ -# Tester guide: running NX2navi on your GPU - -This guide is for testing the build on a GPU other than the developer's (AMD RX 9070). You build it from source with -your own copy of the game and your own console keys. Nothing from the game is in this repository, and nothing you build -from it may be shared. - -## What you need - -- Windows 10 or later, an x86-64 CPU with SSE4.2 (AVX2/FMA recommended: they build the default, faster version), about - 60 GB free. -- A GPU with Vulkan 1.3 and `VK_EXT_external_memory_host`, with a current driver. -- *Ocarina of Time* base game (1.0.0) and the 1.1.0, 1.2.1 or 1.4.3 update, dumped from your own Switch as NSP or XCI. -- `prod.keys` dumped from your own Switch. Never send it to anyone, and never paste it into a log or an issue. - -## Build - -1. Follow [building.md](building.md): the toolchain, then build steps 1-6 (Python environments, `config.local.toml` - with your own paths, extraction, the shader translator, lifting and linking, shader preparation). The result is - `build\\nx2navi.exe`, with `` the game version you built (`v143` or `v121`). -2. Check the build without the game: `build\\nx2navi.exe --selftest` must print a pass. -3. To run the build on another of your machines, package a portable folder ([building.md](building.md), "Portable - folder"). The folder holds game code: for your own machines only. -4. The installer ([installer.md](installer.md)) is the other route to a machine without the toolchain: it builds the - game there from your own files. No installer release is published yet. - -## Run and collect the log - -Every run writes its log to `logs\nx2navi.log` next to `nx2navi.exe`; the four runs before it are kept as `nx2navi.1.log` to -`nx2navi.4.log`, and Open log folder in the settings menu's Advanced tab (F1) shows them. Copy the log before you start the -game again. A file stops at 64 MiB. Started with `2> file`, the game writes its log to that file instead. - -From `cmd.exe` in the repository root, with the validation layer on: - -```bat -set NX2NAVI_VK_VALIDATION=1 -build\\nx2navi.exe -``` - -`NX2NAVI_VK_VALIDATION=1` turns on the Vulkan validation layer (it comes with the Vulkan SDK). It makes the game slower; -do one run with it and one without (`set NX2NAVI_VK_VALIDATION=`). - -If the game stops with a lost device (the log says `device lost` or `VK_ERROR_DEVICE_LOST`), the lines starting with -`vk: pass marks` name the render pass or dispatch the GPU was running. AMD GPUs write them by default. On an NVIDIA GPU, -`set NX2NAVI_PASS_CRUMBS=1` (or GPU pass marks: On in the Advanced tab) before the run that reproduces the crash. - -The game keeps running behind other windows (`assume_focus = 0` in `nx2navi.ini` pauses it instead). Shaders the preparation did not cover compile on first use, so -the first minutes of play can stutter. -Play into the open field (load a save, walk around for a minute, fight something if you can), then close the window. - -## Choosing the GPU - -A laptop with an iGPU and a discrete GPU, or two cards, lists every GPU at the top of the log (`vk: gpu 0: ...`). - -- `set NX2NAVI_GPU_NAME=Radeon` picks the first usable GPU whose name contains that text (case does not matter). -- `set NX2NAVI_GPU_INDEX=1` picks GPU 1 from that list. - -The line `vk: using gpu N: ` says which one ran. - -## Mods - -Mods and cheats made for the emulators go into `mods/` next to `nx2navi.exe`, one folder per mod. [mods.md](mods.md) covers -installing them, their order, code patches, what does not work and what to check when something looks wrong; -[cheats.md](cheats.md) covers cheat files. The log names every mod at the start (`mods: : ...`); when you -report a problem with mods, list them with their download links. - -## What to send back - -1. `logs\nx2navi.log` from each run. It contains no keys and no game files. The lines that matter most start with - `vk caps:` (GPU, driver, features and the fallbacks taken), `vk: gpu`, `validation` and `gfx_shader:`. -2. GPU model, driver version, CPU, RAM, and whether it is a laptop. Copy system info in the settings menu's Advanced - tab (F1) puts these and your changed settings on the clipboard. Say which game update you ran. -3. What you saw: how far it got (menu, loading, field), roughly how smooth it ran, and screenshots of anything wrong - (black or missing areas, flickering, wrong colours, missing grass). Win+Shift+S is fine. -4. If it crashed or hung: what you were doing. The log of that run ends with the crash report, so send it whole. -5. For a bug you can trigger again: a recording of your input (`set NX2NAVI_INPUT_RECORD=input.txt`, see - [controls.md](controls.md), "Scripted input") and the save you started from. - -## Steam Deck - -Build or install on Linux ([installer.md](installer.md), "Linux release"), in Desktop Mode. The game then runs in either -mode; for Game Mode, add `nx2navi` from the install folder to Steam as a non-Steam game. - -The game recognises the Deck (LCD and OLED) and uses its device profile for every setting `nx2navi.ini` does not set: -fullscreen, the screen's own 1280x800 (16:10: the camera and interface take that shape), the game's own 3D scale, -vsync and a 40 fps limit. These are starting points, not measurements. What helps most: - -1. The performance overlay (F10, or both stick clicks L3 + R3) in full mode: the frame rate, mean and longest frame - time over a minute in Lookout Landing, in the Depths and in the Sky, with the settings named. -2. The same with `fps_limit` 30, 45 and 60 and `render_scale` 50, 67 and game, so the defaults can be picked from - measurements. Steam's own performance overlay (the ... button) adds power draw and temperatures. -3. LCD or OLED, SteamOS version (`uname -r` in Desktop Mode's terminal), and the game update. -4. Anything that looks stretched, squeezed or cut off, with a screenshot. At 16:10 the menus keep their 16:9 - proportions in the middle of the taller screen, the HUD sits at the top and bottom edges, and full-screen - backgrounds reach them; pre-rendered cutscenes play stretched. - -`device_profile = desktop` in `nx2navi.ini` turns the profile off; `deck` turns it on elsewhere, to try the Deck's -settings on a PC. - -## Switches for the developer's questions - -Only set these when asked; each forces a fallback the build picks by itself on GPUs that need it. - -| Variable | Effect | -|---|---| -| `NX2NAVI_VK_NO_FLOAT64=1` | Translate shaders without 64-bit floats | -| `NX2NAVI_VK_SSBO_ALIGN=64` | Treat storage buffers as needing 64-byte alignment | -| `NX2NAVI_VK_SUBGROUP_PIN=0` | Do not pin shaders to 32 lanes; tell the translator the GPU's own subgroup size | - -Each switch makes the first launch translate every shader again. diff --git a/nx2navi.ini.example b/nx2navi.ini.example index e5b17d03..cd14419e 100644 --- a/nx2navi.ini.example +++ b/nx2navi.ini.example @@ -36,8 +36,8 @@ # game waits for the GPU; adds up to a frame of latency. # replay_async = 0 # EXPERIMENTAL, THE GAME CRASHES WITH 1. 1 lifts the virtual core gate: guest threads run without the console's limit -# of one thread per core, and the game keeps per-core data without locks. With 1, 1.2.1 and 1.4.3 crash or hang, -# usually at start (#212). Keep 0 to play. +# of one thread per core, and the game keeps per-core data without locks. With 1 the game crashes or hangs, +# usually at start. Keep 0 to play. # free_cores = 0 # Windows timer resolution of 1 ms for steadier frame pacing (0 = the Windows default). # timer_1ms = 1 @@ -158,22 +158,10 @@ # window is no longer stretched as it used to be; stretch fills the window. Changes while the game runs take effect at # once. # aspect = fit -# Field of view, in percent of the game's own: 70 to 140, 100 (the default) leaves the camera as it is. Higher shows -# more of the world around Link. Game version 1.4.3 only. Changes while the game runs take effect at once. -# fov = 100 # Anisotropic filtering of surface textures: game (the level the game asks for, as on the Switch) or 2, 4, 8, 16. Keeps # ground, roads and walls seen at a shallow angle sharp into the distance. Only filtered, mipmapped textures that tile # are raised; shadow maps, data maps and screen-sized buffers keep the game's setting. Read at start. # aniso = game -# Colour adjustment of the picture, HUD included, before it is scaled to the window: brightness (-30 to 30, added in %), -# contrast and saturation (70 to 150 and 50 to 200 %), gamma (0.8 to 1.2, below 1 brightens dark tones). At 0, 100, -# 100 and 1 nothing runs. color_preset is the menu's profile (default, vivid, clarity, custom), which sets the four. -# Changes while the game runs take effect at once. -# color_preset = default -# color_brightness = 0 -# color_contrast = 100 -# color_saturation = 100 -# color_gamma = 1 # Sun shadow map size: game (the game's own, which changes with the view and drops to about 400 near the ground, so # leaf shadows look blocky and jump) or a fixed 256, 512, 768, 1024, 1536 or 2048. Above 960 the texture heap grows with # it. 256 is coarser than the game's own and is for integrated GPUs short of memory bandwidth. Read at start. @@ -204,7 +192,7 @@ # What DLSS works from: dlaa (the 3D scene at full size), quality, balanced, performance or ultra_performance (the # scene at 67, 58, 50 or 33 % of the output, scaled up by DLSS; these replace render_scale and sharpen texture filtering # to match). They apply only with dlaa = 1 and the DLSS model next to the executable; otherwise the scene follows -# render_scale. Changes while the game runs take effect at once (1.4.3; 1.2.1 at the next start). +# render_scale. Changes while the game runs take effect at once. # dlss = dlaa # The DLSS model: default (NVIDIA's advice per mode: K for dlaa, quality and balanced, M for performance, L for # ultra_performance), k (K in every mode) or j (the other transformer model: slightly less ghosting behind moving @@ -227,7 +215,7 @@ # HDR output: hdr = 1 sends the picture as HDR10 (needs HDR on in Windows, "Use HDR", or a Wayland compositor with # colour management; without it the picture stays SDR). The game's tonemap keeps highlights up to hdr_peak_nits (your # display's peak); hdr_game_nits is the picture's white (paper white, 203 is the HDR reference) and hdr_ui_nits the -# HUD's and the menu's. hdr is read at start, the nits at once. The colour profile above is for SDR only. +# HUD's and the menu's. hdr is read at start, the nits at once. # hdr = 0 # hdr_peak_nits = 1000 # hdr_game_nits = 203 @@ -301,13 +289,9 @@ # lstick_deadzone = 8 # rstick_deadzone = 8 # Mouse camera mode: direct (default) or stick. Direct turns the camera by the raw mouse motion, the same on both axes, -# with no stick dead zone or response curve (game 1.4.3; other game versions use stick emulation). Stick makes the +# with no stick dead zone or response curve. Stick makes the # mouse a right stick. Neither changes the gamepad. The Controls tab changes this while the game runs. # mouse_mode = direct -# The mouse in the game's menus, 1.4.3 only (title, inventory, System tab, Options, shops, dialogue choices): while a -# menu has the game's focus box the pointer shows, the item under it takes the focus, a left click is A on it and a -# right click is B. 0 leaves the menus to the keys and the pad. Changes while the game runs. -# menu_cursor = 1 # Mouse camera sensitivity (0 to 10; 0 = no mouse camera and no cursor capture). # mouse_sens = 1 # The keyboard's sticks are all or nothing, so the game only sees a full tilt from them; while this key is held the