Dolphin Emulator

Dolphin's auto-update system uses a separate application to modify the main Dolphin executable and its files, as applications cannot overwrite themselves.

Key Constraints & Behavior:

• Platform Support: Only supported on Windows and macOS.
• Update Tracks: There are four frequency tracks: Dev (every commit), Beta (a few times a year), Stable (rarely), and Disabled.
• Updater Lifecycle: When an update is triggered, the system creates a copy of the updater application. This copy updates both Dolphin and the original updater. To prevent clutter, Dolphin deletes any existing updater copy automatically upon launch.

A wia_exception_t represents a 20-byte difference between recalculated hash data and the original hash data. This is used to restore hashes for Wii partition data.

Implementation Details:

• When recalculating hashes for a wia_group_t not evenly divisible by 2 MiB, missing bytes should be treated as zeroes.
• Dolphin vs wit: wit only outputs exceptions for mismatches in actual hash data. Dolphin outputs exceptions for both hash data and padding data.
• If Dolphin writes exceptions for a 32-byte padding area, it writes two wia_exception_t structs (one for the first 20 bytes and one for the last 20 bytes), resulting in a 12-byte overlap.

WIA (version 1.00) is a compressed disc image format for GameCube and Wii discs, implemented in wit v2.40a.

Key Features:

• Supports bzip2, LZMA, and LZMA2 compression algorithms.
• Wii partition data is stored decrypted and without hashes, which improves compression efficiency.
• Data is divided into blocks (chunks) that are compressed separately, enabling random access to compressed data.

Technical Constraints:

• All integers are big endian unless otherwise noted.
• The type sha1_hash_t refers to a 20-byte array.
• Data can be stored in any order unless specified.

WIA handles Wii partition data differently than standard disc data. In a WIA file, Wii partition data is stored decrypted and with hashes removed to allow for better compression.

Key Details:

• For every 0x8000 bytes on the original disc, only 0x7C00 bytes are stored in the WIA file (prior to compression).
• To recover the original hashes, a reader must recalculate them and then apply hash exceptions stored in wia_except_list_t.
• Partition data is managed via wia_part_t structs, which contain a 128-bit AES part_key for re-encryption.
• wia_part_t splits data into two segments: pd[0] (management data like boot/fst) and pd[1] (remaining data).

The wia_segment_t struct is used specifically by the PURGE compression method to store runs of zeroes efficiently.

How it works: Each PURGE chunk contains zero or more wia_segment_t structs ordered by ascending offset. Any bytes in the decompressed data not covered by a segment are treated as 0x00. A SHA-1 hash (0x14 bytes) follows the segments, covering the wia_except_list_t structs (if any) and the wia_segment_t structs.

Structure:

• u32 offset: The offset of data within the decompressed data (excluding wia_except_list_t structs).
• u32 size: The number of bytes in data.
• u8 data[size]: The actual data payload.

Dolphin provides a virtual IOS device at /dev/dolphin. Homebrew applications and game mods can attempt to open() this device to determine if they are running within the Dolphin emulator.

If the open() call is successful, the application is running on Dolphin and can safely skip tasks that are only necessary on real hardware (such as patching IOS) or enable emulator-specific features.

Dolphin allows content creators to overwrite internal graphics pipeline data (currently limited to the pixel shader) using graphics mods. To trigger this capability, you must use the custom_pipeline action type within your mod's feature definitions.

Action Data Requirements

The custom_pipeline action requires a passes array. Currently, Dolphin only supports a single pass in this array. Each pass must include a pixel_material_asset identifier, which refers to the name of a material asset defined in your mod's assets section.

{
    "features": [
        {
            "action": "custom_pipeline",
            "action_data": {
              "passes":  [
                {
                  "pixel_material_asset": "material_replace_normal"
                }
              ]
            },
            "group": "PipelineTarget"
        }
    ]
}