Logging and inspecting errors

Witgui runs on top of the wit/wwt command line tools. When an error occurs or something doesn’t behave as intended with the generated game files, it can be useful to inspect the output of these tools. If the output contains something like this:

!! wit: ERROR #126 [FATAL ERROR] in wd_read_part() @ src/libwbfs/wiidisc.c#865

it’s likely to be an issue with the wit/wwt tools, so you should try to get help on the official support forum: https://gbatemp.net/threads/wwt-wit-wiimms-wbfs-iso-tools.182236

  1. Open the Terminal (in /Applications/Utilities).
  2. Copy and paste “/Applications/Witgui.app/Contents/MacOS/Witgui -log” into the Terminal and press Enter.
  3. A new app instance will open. Reproduce the issue.
  4. A bunch of lines will appear inside the Terminal that contain some logs.
  5. After analyzing the Terminal output, you can quit Witgui and the Terminal.

Installing wit/wwt

Witgui is based on the wit and wwt executables which are part of the Wiimms ISO Tools. These tools are the core for listing and converting your games and most of the other features that Witgui offers.

wit and wwt can be downloaded from the File menu with a single click. After a successful download, the executables will be placed in the Application Support directory.

If you already have your own installation of wit or wwt, you can locate them by selecting “File > Locate wit/wwt …” while pressing the alt/option key. By default Witgui tries to locate wit and wwt in the following order: it first checks the supplied installation (if any), then searches in the Application Support directory and last in “/usr/local/bin”. When selecting “File > Download wit/wwt”, any reference to the custom installation path will be removed.

Naming presets

When composing the name of a file to convert, renaming a file or exporting a game list, special tags can be inserted into the text field by clicking on the “+” button on the left side. Frequently used naming presets can be selected, too.

To add a custom naming preset to the list, compose your preset in the text field, click on the “+” button and hold the alt/option key. Select the first menu item which has changed to “Add current value to presets”.

To remove a naming preset from the list, click on the “+” button and hold the alt/option key. Select the menu item corresponding to the preset you want to remove (it will read “Clear: <preset>”).

Note: tags which are undefined or naming presets that contain tags which are undefined for any of the selected games will be disabled.

Merging and splitting files

When you select a different option than “Don’t split” in the conversion modal panel, the created file will be split up into multiple files if it is larger than the selected option. This is necessary if you are going to play a game on a FAT partition, which doesn’t support files larger than 4GB.

To merge a multi-part file into one single file or split a single file into multiple parts, select the corresponding game in the source window and drag it to the destination window. Now select the same filetype as the original file (which you can see in the Filetype column of the game list) and select the desired split size from the popup menu (if you want to merge a multi-part file, select “Don’t”). Click on Save and wait till the conversion has finished.

Adding a game to a WBFS partition

Before being able to open a WBFS partition, you have to install wwt and grant access to the partition. To open a WBFS partition, select “Open WBFS partition” from the File menu and choose your WBFS partition from the combo box.

Make sure you can see the game you want to transfer in the source window (which will usually represent a folder on your Mac). Once you’ve selected the game, you can drag it to the destination window which represents the WBFS partition. A panel will appear asking if you want to keep only the CHAN and DATA partitions: usually this option reduces the final size of the game, but if you are unsure, just leave it unchecked. When you click the OK button, the conversion will start and you can follow the progress by clicking the Conversions button on the right side of the toolbar.

Gaining access to WBFS partitions and formatting a partition as WBFS

To gain access to a WBFS partition or to format a partition as WBFS you first need to install wwt, which you are prompted to download when you launch Witgui for the first time.

Besides, you somehow need to have privileged permissions. The first time you download wwt you’ll be prompted whether to set it automatically to be executable as root by everyone: accepting is the easiest way to do it (this is not as secure as the next option, so you are responsible for everything bad that could happen – which normally shouldn’t). Another way is to change the access rights of the partition every time you plug it in (just scroll down to see the instructions). The last option listed on this page describes how to set wwt to be executable as root by everyone manually.

Changing access rights of a partition

  1. Open the Terminal (which you can find in Applications/Utilities), type
    diskutil list

    and press Return. You’ll get a list of the currently available devices.

  2. Plug in the device. An alert may appear saying that the device could not be mounted: click on “Ignore”. Now you have to type again in the Terminal the previous line of code (or simply press the UP arrow) and then press Return. By comparing the first to the second output you can get the name of the device you plugged in (it should be something like /dev/disk1).
  3. Type
    sudo chmod 666 /dev/disk1

    (or whatever name you got previously) and press Return. After typing your password (it won’t be printed on screen) and pressing Return you can close the Terminal.

  4. Now you can access the partition as long as it is plugged in. Because the permissions get lost every time you plug the device out, you’ll have to repeat these steps if you want to access it again afterwards.

Setting wwt to be executable as root by everyone

  1. Open the Terminal (which you can find in /Applications/Utilities).
  2. Type the following two lines (you’ll have to type your password after pressing Return the first time):
    sudo chown root:wheel ~/Library/Application\ Support/Witgui/wwt
    sudo chmod u+s ~/Library/Application\ Support/Witgui/wwt