mirror of
https://git.triforceproject.com/triforce/source
synced 2026-11-19 16:20:01 -04:00
150 lines
8.2 KiB
Markdown
150 lines
8.2 KiB
Markdown
# Contributing to Triforce
|
|
|
|
Triforce is a native PC port of the Switch 2 *The Legend of Zelda: Ocarina of Time* remake. The game's code is
|
|
translated to C and built on your own PC from your own copy of the game; the system and the graphics are rebuilt
|
|
natively, with the graphics replayed on Vulkan. No emulator is involved. Triforce builds on the open-source Hookshot
|
|
project (GPL-3.0), and its code keeps that license.
|
|
|
|
This page covers what to send, how to build and test it, and the rules that keep the project out of trouble. The
|
|
[development guide](docs/development.md) has the full pipeline and its commands; the [design notes](docs/design.md)
|
|
have the architecture.
|
|
|
|
## The rule with no exceptions
|
|
|
|
**No game files, keys, or anything made from them leave your PC.** The repository does not contain the game and
|
|
never will. That includes:
|
|
|
|
- the `.nup`, `romfs`, `exefs`, `.nso`, `.nca`, `.nsp`, `.xci` or `.nsz`/`.xcz` files, and any title keys;
|
|
- `work/` and everything in it: the extracted dump, `image.bin`, the translated C, test builds, runs and screenshots;
|
|
- `Triforce.exe`, `triforce_vk.dll`, `triforce_shaders.bin`, `triforce_programs.bin` (and `.idx`),
|
|
`triforce_pipelines.bin`, `mkw_vk_pipelines.bin` and every other file a build or a run makes;
|
|
- saves (`user/`), `triforce_options.ini`, `triforce_env.txt` and `language.txt`.
|
|
|
|
Do not open an issue or a pull request asking where to get the game, how to decrypt it, or for someone else's files.
|
|
A screenshot, a video and `triforce_log.txt` are fine and often necessary; the log holds no game data.
|
|
|
|
`.gitignore` covers most of this, but check `git status` before you commit. If you are not sure whether a file is
|
|
game data, leave it out.
|
|
|
|
## Reporting a problem
|
|
|
|
Open an [issue](https://github.com/ruckus7382sfgsgdf/CBeta0.2/issues) and include:
|
|
|
|
- the Triforce version (the release name, or the first line of `triforce_log.txt`);
|
|
- your graphics card, its driver version, and your Windows version;
|
|
- where you were in the game and what you did;
|
|
- the logs:
|
|
- **a game problem:** `triforce_log.txt` from your game folder (the folder with `Triforce.exe`). If you started the
|
|
game again after the problem, send `triforce_log.1.txt` too: each start keeps the four runs before it as
|
|
`triforce_log.1.txt` (the last) to `triforce_log.4.txt`.
|
|
- **a Setup or build problem:** `setup.log` from `%LOCALAPPDATA%\Programs\Triforce`, and for a failed build the text
|
|
from **Show details** on the build page.
|
|
|
|
Before you report:
|
|
|
|
- Try the [newest release](https://github.com/ruckus7382sfgsgdf/CBeta0.2/releases) first.
|
|
- Search the open issues; if yours is there, add your details to it.
|
|
- For graphics or performance problems, test without ReShade, overlays, shader-cache tools and frame-generation
|
|
injectors: they change what Triforce does.
|
|
- If graphics look wrong after an update, clearing the shader caches often helps: close the game and delete
|
|
`triforce_programs.bin`, `triforce_programs.idx`, `triforce_pipelines.bin`, `triforce_pipeline_states.bin`,
|
|
`triforce_computes.bin`, `mkw_vk_pipelines.bin` and `triforce_prepared.bin` from the game folder (never
|
|
`triforce_shaders.bin`). The next start prepares them again.
|
|
|
|
One topic per issue or pull request, in English, please.
|
|
|
|
## Ways to help
|
|
|
|
| | What |
|
|
|---|---|
|
|
| **Test on other hardware** | NVIDIA cards are the most tested. Reports from AMD and Intel cards and other drivers are useful even when everything works. |
|
|
| **Play further** | Reaching new areas, cutscenes, menus and items finds problems nobody has seen yet. |
|
|
| **Report what is broken** | As above, with the version, your hardware, where you were and the log. |
|
|
| **Send a fix** | Fork, fix, test, open a pull request. Small, focused changes are easiest to review. |
|
|
| **Improve the docs** | Corrections and clearer steps are welcome. |
|
|
|
|
## Development setup
|
|
|
|
You need your own supported copy of the game: program `0400486024DEC000`, update v131072, build `e0f3ccfa`. Other
|
|
versions do not work, and the build reads your files where they are without changing them. A build needs about 60 GB
|
|
free and takes around 40 minutes; a run uses about 10 GB of RAM. Build on an SSD if you can.
|
|
|
|
The easy way to get every tool a build needs is **Triforce Setup** from the
|
|
[releases](https://github.com/ruckus7382sfgsgdf/CBeta0.2/releases): it installs the tools (Python with its packages,
|
|
llvm-mingw, the Vulkan headers, FFmpeg, SDL2) into `%LOCALAPPDATA%\Programs\Triforce\tools`.
|
|
|
|
To build from a clone instead:
|
|
|
|
1. Install Python 3 from [python.org](https://www.python.org/downloads/) (not the Microsoft Store build) and the
|
|
pipeline's packages: `python -m pip install -r requirements.txt`.
|
|
2. Get [llvm-mingw](https://github.com/mstorsjo/llvm-mingw) (the `ucrt-x86_64` build) and set `HOOKSHOT_MINGW` to its
|
|
folder.
|
|
3. From the installed tools folder, point `RX_CPM` at `tools\cpm` and `WGPU_NATIVE` at `tools\wgpu-native`, and copy
|
|
`tools\third_party` into `third_party\` and `tools\work` into `work\`.
|
|
4. Run everything with `python -I` from the repository root.
|
|
|
|
(Some environment variables still carry the older `HOOKSHOT_` name; they work as documented.).
|
|
|
|
### Triforce Setup
|
|
|
|
The launcher lives in `setup/`: a .NET Framework 4.8 WPF app, built with `powershell -File setup\build.ps1` (needs the
|
|
C# compiler from Visual Studio Build Tools). `setup\pack_tools.ps1` packs the tools zip a release carries. Never run a
|
|
development build's install, update or uninstall without `TRIFORCE_TEST_ROOT` set to a scratch folder: it would act
|
|
on your real install.
|
|
|
|
## Building
|
|
|
|
| Command | What it does |
|
|
|---|---|
|
|
| `python -I nx2/make_game.py --nup "C:\path\your-game.nup" --out "C:\Games\Triforce" --language en-US` | Build a complete game folder from a `.nup`. |
|
|
| `python -I nx2/make_game.py --romfs "C:\path\romfs" --exefs "C:\path\exefs" --out "C:\Games\Triforce"` | The same, from extracted folders. |
|
|
| `python -I nx2/make_game.py --check --nup "C:\path\your-game.nup"` | Check the game and its version without building. |
|
|
|
|
The translated C and every build are local files; they are never committed.
|
|
|
|
## Testing
|
|
|
|
The game-free checks need no game files:
|
|
|
|
```powershell
|
|
python -I -B tests/run_all.py
|
|
```
|
|
|
|
It runs every `tests/test_*.py` and `nx2/test_*.py`, the C++ unit tests under `gpu/vk/tests`, and a byte-compile of
|
|
every Python file, and ends with a table of results. Name a check to run only the ones whose path contains it. A new
|
|
`test_*.py` file is picked up by itself.
|
|
|
|
When you add a fix, add a game-free test where the behavior can be tested without the game. For a renderer or runtime
|
|
fix, say what you saw before and after, on which GPU and driver, and where in the game.
|
|
|
|
## Code conventions
|
|
|
|
- Match the file you are editing: its indentation, comment style and naming. Do not reformat unrelated code.
|
|
- Do not modify `third_party/`. Its parts are unmodified upstream copies, each with its notice in its own
|
|
`PROVENANCE.md`.
|
|
- New switches use the `RX_` prefix in the renderer and `HOS_` in the runtime, are off unless asked for, and cost
|
|
nothing while off.
|
|
- Rendering fixes must reproduce what the game itself does, not tuned factors that only look right on one screen.
|
|
- Python runs with `-I`; tests stay on the standard library. Keep line endings LF.
|
|
|
|
## Pull requests
|
|
|
|
1. Fork the repository and branch from `main`.
|
|
2. One topic per pull request: a fix does not carry a refactor.
|
|
3. Title: a short imperative sentence. Body: why it is needed, what changed, how it was tested (GPU, driver, game
|
|
area, fps before and after), and the issue it fixes.
|
|
4. Screenshots for anything that shows on screen, before and after.
|
|
5. No build output, dumps or generated files. Check `git status`.
|
|
|
|
## Licensing
|
|
|
|
Triforce is free software under the [GNU General Public License, version 3 or later](LICENSE), like the Hookshot code
|
|
it builds on. By submitting a change you agree to license it under those terms. Do not paste code from a project with
|
|
an incompatible license, and never paste decompiled game code or anything generated from the game files.
|
|
|
|
The third-party parts (Eden, suyu, Sirit, the Vulkan Memory Allocator, SDL, Opus, Dear ImGui, zstd, the Libertinus
|
|
fonts, zbic and the a64-kit tools) keep their own notices. Preserve them.
|
|
|
|
Thanks for testing, reporting and sending fixes. Every report from a different GPU and every area played further
|
|
moves the port forward.
|