ZeldaWWHDRecomp

https://github.com/zeldawwhdrecomp/zeldawwhdrecomp
Admin
ZeldaWWHDRecomp is a static recompilation and native port of The Legend of Zelda: The Wind Waker HD...
Tokens:224,982
Snippets:1,546
Trust Score:6.2
License:MPL-2.0
Update:1 week ago
Show doc for...
Tokens:
Raw
### Scripted setup help

Source: https://github.com/zeldawwhdrecomp/zeldawwhdrecomp/blob/main/README.md

Shows help for the scripted setup interface. Run this to see available options for the installer script.

```bash
tools/installer/setup.py --help
```

--------------------------------

### setup.py --language-source with .wux image and disc key

Source: https://github.com/zeldawwhdrecomp/zeldawwhdrecomp/blob/main/docs/language-packs.md

Adds a language source from a European or Japanese .wux/.wud image, specifying the disc key and common key. The USA game must be installed. Setup verifies the title ID and extracts only the permanent_2d_*.pack files and meta.xml.

```bash
setup.py --language-source "Wind Waker HD (EUR).wux" --language-disc-key eur.key --common-key common.key
```

--------------------------------

### Linux AppImage: Run setup with --setup

Source: https://github.com/zeldawwhdrecomp/zeldawwhdrecomp/blob/main/README.md

Use this flag to repair or change the game when running the AppImage.

```bash
--setup
```

--------------------------------

### Build guest mods with make

Source: https://github.com/zeldawwhdrecomp/zeldawwhdrecomp/blob/main/examples/guest-mods/README.md

Builds all example guest mods using clang with the PowerPC target and ld.lld. Requires clang with the PowerPC target and ld.lld; on macOS install via `brew install llvm lld`. The command specifies the clang and lld paths.

```sh
make CLANG=/opt/homebrew/opt/llvm/bin/clang LLD=/opt/homebrew/opt/lld/bin/ld.lld
```

--------------------------------

### Terminal setup scripts for each OS

Source: https://github.com/zeldawwhdrecomp/zeldawwhdrecomp/blob/main/README.md

These scripts run the setup in a terminal as a fallback. Use the appropriate one for your operating system.

```bash
tools/Setup in Terminal.command
```

```bash
tools/Setup in a console window.bat
```

```bash
tools/setup-in-terminal.sh
```

--------------------------------

### Read-only resource capture command

Source: https://github.com/zeldawwhdrecomp/zeldawwhdrecomp/blob/main/docs/android-device-checklist.md

Run this command on a debuggable build to capture resource usage for a job. Get the job ID from the private no_backup/ondevice/setup.json pointer. Start before resuming setup; it stops when the job completes/fails or the capture window ends. It never installs, pauses, or resumes the app.

```bash
python3 tools/android/resource_sampler.py --serial SERIAL --job-id JOB_ID --seconds 3600 --output phone-resources.json
```

--------------------------------

### Run picture check script

Source: https://github.com/zeldawwhdrecomp/zeldawwhdrecomp/blob/main/docs/vulkan.md

Example command for running tools/bench/run_picture_check.py with baseline and candidate builds. Requires Pillow installed via python3 -m pip install Pillow. Use --validation when Khronos layers are installed. Output should be kept under ignored build/ or another local evidence directory.

```sh
python3 tools/bench/run_picture_check.py \
  --baseline /absolute/path/to/baseline/wwhd --baseline-revision BASELINE_COMMIT \
  --candidate build/cmake/wwhd --candidate-revision CHANGED_COMMIT \
  --game game --save save --state-dir /absolute/path/to/local/states \
  --scene outset --origin-load-steps 180 --capture-load-step 200 --seconds 2 \
  --out build/bench/picture-check
```

--------------------------------

### setup.py --gui-protocol

Source: https://github.com/zeldawwhdrecomp/zeldawwhdrecomp/blob/main/tools/installer/README.md

The setup.py GUI protocol uses JSON objects on stdin and stdout. Events are emitted on stdout and requests are sent on stdin.

```APIDOC
## setup.py --gui-protocol

### Description
Interactive JSON line-based protocol for controlling the setup.py installer. Events are emitted on stdout, requests are sent on stdin.

### Events (stdout)

Each event is a JSON object with an `"event"` field.

#### hello
- **version** (string) - Version of setup.py
- **platform** (string) - Platform identifier
- **data_dir** (string) - Data directory
- **app_dir** (string) - Application directory
- **log** (string) - Log file path
- **portable** (boolean) - Whether portable mode is active
- **package** (string) - Package identifier
- **installed** (object|null) - Installation state or null
- **game_files** (array) - List of game files
- **game_dir** (string) - Game directory
- **save_exists** (boolean) - Whether a save exists
- **legacy** (string|null) - Earlier installation to copy from
- **free_bytes** (number) - Free disk space in bytes
- **language_sources** (array) - Language sources as in the `language_sources` reply
- **toolchain** (string) - Toolchain identifier

#### log
- **text** (string) - Log message (also written to setup.log)

#### plan
- **steps** (array) - List of steps: `[{id, title}]`

#### step
- **n** (number) - Current step number
- **total** (number) - Total steps
- **title** (string) - Step title
- **id** (string) - Step identifier (one of `keys`, `archive`, `folder`, `compiler`, `extract`, `copy`, `translate`, `compile`, `app`)

#### progress
- **label** (string) - Progress label
- **done** (number) - Completed units
- **total** (number) - Total units
- **detail** (string) - Additional detail

#### reply
- **id** (number) - Request ID
- **cmd** (string) - Command that was requested
- **ok** (boolean) - Success flag
- **problem** (string, optional) - Problem code on failure
- **message** (string, optional) - Error message on failure

#### fatal
- **message** (string) - Fatal error message (setup cannot run)

### Requests (stdin)

Requests are JSON objects: `{"cmd": ..., "id": n, ...}`

#### probe
- **path** (string) - Path to probe

Reply fields:
- **kind** (string) - `image`, `archive`, or `folder`
- **disc_key** (string, optional) - Disc key found next to the image
- **common_key** (string, optional) - Common key found
- **in_place** (boolean, optional) - For folder: whether in place
- **bytes** (number, optional) - For folder: byte count
- **title** (string, optional) - For archive: title
- **folder** (string, optional) - For archive: folder
- **message** (string, optional) - For archive: which title is used and why

Problems: `wrong_title` when the archive has no usable game

#### check_keys
- **image** (string) - Path to the game image
- **disc_key_file** (string, optional) - Path to disc key file
- **common_key_file** (string, optional) - Path to common key file
- **common_key_hex** (string, optional) - Common key in hex

Reply fields:
- **title_id** (string) - Title ID
- **files** (array) - List of files
- **bytes** (number) - Total bytes

Problems: `disc_key_wrong`, `common_key_wrong`, `wrong_title`, etc.

#### install
- **source** (string) - `image`, `archive`, `folder`, or `installed`
- **path** (string) - Source path
- **jobs** (number, optional) - Number of parallel jobs

Streams `plan`/`step`/`progress`/`log` events, then reply with:
- **app** (string) - Application path
- **exe** (string) - Executable path
- **data_dir** (string) - Data directory
- **game_dir** (string) - Game directory
- **toolchain_bytes** (number) - Toolchain size in bytes

#### import_save
- **kind** (string) - `hd` or `gc`
- **path** (string) - Path to save
- **replace** (boolean, optional) - Whether to replace existing save

Reply fields:
- **message** (string) - Result message

Problem: `exists` when a save is installed and `replace` is not set (with `replace`, old save moved to `save/user.backup-<time>`)

#### import_existing
- **path** (string, optional) - Path to another release folder (none: earlier per-user installation)
- **replace** (boolean, optional) - Whether to replace existing data

Reply fields:
- **message** (string) - Result message (saves and settings copied, never moved)

Problem: `exists` as above

#### language_sources
No additional fields.

Reply fields:
- **sources** (array) - List of `{region (EU/JP), title_id, source, packs: [{file, language, bytes, sha256}]}`

#### add_language_source
- **path** (string) - Path to a European or Japanese `.wux`/`.wud`, `.wua` or extracted folder
- **disc_key_file** (string, optional) - For image: disc key file
- **common_key_file** (string, optional) - For image: common key file
- **common_key_hex** (string, optional) - For image: common key in hex

Reply fields:
- **sources** (array) - The added sources

Only `content/Common/Pack/permanent_2d_*.pack` and `meta/meta.xml` are taken, into `data/game-lang/<EU|JP>`.

Problems: `language_source` (e.g. USA game, update, no packs) or key problems as for `check_keys`

#### remove_language_source
- **region** (string) - `EU` or `JP`

Reply fields:
- **removed** (string) - The removed folder

#### remove_toolchain
No additional fields.

Reply fields:
- **freed** (number) - Freed bytes

#### shortcut
No additional fields.

Reply fields:
- **path** (string) - Path of the created shortcut

#### launch
No additional fields.

Starts the installed game.

#### quit
No additional fields.

Quits the protocol.

### Notes
- Keys from the last successful `check_keys` are used for image installs; they stay in memory and are dropped when extraction starts.
- Requests are never logged or echoed, and no key is written to disk or passed on a command line.
```

--------------------------------

### Linux AppImage: Run with --appimage-extract-and-run

Source: https://github.com/zeldawwhdrecomp/zeldawwhdrecomp/blob/main/README.md

On Ubuntu 24.04 and newer without FUSE, start the AppImage with this flag to extract and run it. Also use --setup to repair or change the game.

```bash
--appimage-extract-and-run
```

--------------------------------

### setup.py --language-source with extracted folder

Source: https://github.com/zeldawwhdrecomp/zeldawwhdrecomp/blob/main/docs/language-packs.md

Adds a language source from an extracted game folder. The folder must be from a European or Japanese copy of the game. Setup extracts only the needed language packs.

```bash
setup.py --language-source /path/to/extracted/eur-game
```

--------------------------------

### setup.py --language-source with Cemu .wua archive

Source: https://github.com/zeldawwhdrecomp/zeldawwhdrecomp/blob/main/docs/language-packs.md

Adds a language source from a Cemu .wua archive. The archive must be from a European or Japanese copy of the game. Setup extracts only the needed language packs.

```bash
setup.py --language-source wwhd-eur.wua
```

--------------------------------

### Run the game with ./build/cmake/wwhd

Source: https://github.com/zeldawwhdrecomp/zeldawwhdrecomp/blob/main/README.md

Launches the game from the build directory. Options include --game DIR for the default game and --save DIR for the default save.

```sh
./build/cmake/wwhd                 # options: --game DIR (default game), --save DIR (default save)
```

--------------------------------

### Install pycryptodome

Source: https://github.com/zeldawwhdrecomp/zeldawwhdrecomp/blob/main/README.md

Install the Python pycryptodome package required for tools/wudextract.py.

```bash
pip3 install pycryptodome
```
Tokens:
Raw