Skip to content
RetrogamingDeep Dive Published Updated 9 min readViews unavailable

Dolphin GCI Folder Cards: Save Routing, Migration, and Netplay

Understand Dolphin's folder-backed GameCube memory cards, how GCI records differ from raw images, and how to migrate and test saves safely.

A GameCube save can exist as one record, as part of a directory-backed virtual card, or inside a complete raw card image. Those are different storage objects, even when each is casually called a “memory card file.” The distinction matters when moving a save, changing regions, testing a backup, or joining a netplay session.

This guide focuses on Dolphin’s GCI Folder backend and its current implementation, pinned to Dolphin commit 8d2ad1a662472955497e5bb79d7b9ec6999e1f0d. It does not cover Wii NAND, GameCube EXI command timing, or recovery of corrupted data. Treat the source links as implementation evidence for that revision, not a permanent compatibility promise for every future Dolphin version or every third-party save utility.

A GCI record is not a whole card image

In a raw-card backend, Dolphin reads and writes a complete card image. Its parser reads the card header, two directory blocks, two block-allocation-table blocks, and the remaining save-data blocks. The duplicate directory and allocation blocks are part of the image model, not extra copies of every game save. This is why preserving the full .raw file is the right baseline when you want to retain the entire card as Dolphin sees it.

A .gci file instead represents an individual card record. In the pinned Dolphin implementation, the loader reads one 64-byte directory entry, then checks that the file contains exactly the number of 8,192-byte data blocks declared by that entry. A GCI therefore carries a save record and its blocks, not the raw image’s complete card header, directory history, allocation tables, other game records, or the entire card capacity. Dolphin’s Memory Card Manager exposes individual GCI export alongside the complete card-file workflow. The raw-card parser and the format definitions make those boundaries explicit.

Representation What Dolphin reads as the card Useful when Do not assume
Raw image, commonly .raw A complete card image with card-wide structures and save data Archiving or cloning the whole card; using a manager that opens card images A GCI export is a byte-for-byte substitute
GCI Folder A directory of individual .gci records and optional MC_SYSTEM_AREA card metadata Keeping records as ordinary files and isolating a test copy Every file in the directory will load, or capacity is unlimited
Individual .gci One save record with its directory entry and allocated data blocks Moving one selected save between supported tools or a folder-backed card Other saves, card-wide state, or the source card’s identity came with it

The table describes Dolphin’s backend behavior, not a universal definition of every file named .raw or .gci. Extensions are useful clues, but confirm the selected slot and actual configured path before copying anything.

How Dolphin assembles a GCI Folder card

The folder backend does more than enumerate save files. GCMemcardDirectory constructs the card header, directory, and allocation-table state that the emulated GameCube reads through its memory-card interface. It loads .gci files from the configured directory, compares the internal game code with the running game’s ID, reserves blocks in its virtual allocation table, and maps reads and writes to the corresponding save data. When present, MC_SYSTEM_AREA supplies a persisted card header block. See the pinned folder backend and EXI memory-card setup.

That reconstruction has meaningful limits:

  • The card model still has a fixed directory and finite allocation table. Dolphin’s current definitions use 127 directory entries; a folder is not an infinite physical memory card.
  • A record with an invalid block count, an unreadable header, an inconsistent file length, or insufficient free blocks can be skipped or rejected. A file’s presence in the folder is not proof that the running game can see it.
  • Two files with the same internal save identity are not loaded as two distinct records. Keeping multiple differently named copies of one record in the live folder is not a version-history mechanism.
  • Dolphin prioritizes records for the currently running title. Its implementation also has a session option to load only that game’s records, used by the netplay configuration path. Exact filtering and capacity policy are version-specific; do not use a folder full of unrelated GCI files as an archival guarantee.

The netplay path is especially worth separating from ordinary play. In the pinned configuration loader, the savedata-load path enables current-game-only GCI-folder behavior; when the client is not hosting, it also overrides the two folder paths to session-specific Card A and Card B directories and assigns region-specific raw-card paths. This is evidence of Dolphin’s netplay isolation strategy in that code revision. It is not a reason to copy temporary netplay card data over your everyday card after a session. See the pinned netplay configuration loader.

Why a region change can look like a missing save

Dolphin derives default raw-card paths from the slot and GameCube region; for some card sizes the generated name also includes a size-related suffix. The default GCI Folder path is likewise separated by slot and region. A custom configured path may contain a recognized region-code component that Dolphin substitutes when it selects the active region. The pinned path helpers show why switching a title, region, or card configuration can cause Dolphin to open a different file or directory without deleting the original data.

Before diagnosing an empty card, record the exact game ID, region shown for the content, slot A or B, card type, and the path shown in Dolphin’s GameCube settings. Do not create another blank card at the suspected path or rename an image to match a guessed filename. First search the configured user directory and any explicit custom paths, then compare timestamps and hashes of candidate copies while Dolphin is closed.

A controlled migration and verification workflow

Use a duplicate so that format conversion is an experiment, not an edit to your only copy:

  1. Record and close. Note the Dolphin version, GameCube region, active slot, selected raw-card or GCI Folder mode, and configured paths. Exit Dolphin normally and confirm it is no longer running. A folder-backed card can flush modified records while emulation is active, so do not copy its files mid-session.
  2. Preserve both sides. Copy the complete raw image to a separate backup location. If a GCI Folder already exists, copy the whole directory, including MC_SYSTEM_AREA and all .gci files. Keep the untouched copies outside active cloud synchronization. Record a SHA-256 digest for the raw image before testing; for a directory, hash each file or create a manifest rather than trying to hash the directory name.
  3. Choose the operation. To move one save from a raw card, use Dolphin’s Memory Card Manager to export the selected record as GCI, then place that export in a separate test folder configured for the intended slot. The manager’s source code distinguishes native GCI from other recognized save formats such as GCS and SAV. Do not treat importing one GCI as importing the raw card. The pinned manager implementation documents these supported operations.
  4. Check automatic migration before first launch. In the pinned EXI implementation, automatic migration is enabled for the ordinary/default GCI Folder path. Any non-empty GCI-folder path override disables that migration flag, not just a netplay session override. When migration remains enabled and the default destination does not yet exist, Dolphin attempts to open the slot’s configured raw card and export valid entries into GCI files. If the destination already exists as a directory, the absent-folder migration branch is bypassed; do not assume that choosing folder mode always imports an existing raw card. To exercise this behavior, use an isolated Dolphin user directory with the default GCI Folder path unmodified and a copied source image; a custom non-empty destination will not test the automatic-migration branch.
  5. Test the correct title. Start the exact game revision and region whose save you exported. Confirm the game recognizes the expected profile, then make a harmless in-game save to the test copy. Exit normally, reopen the same configuration, and confirm the save persists. Do not use a save state as a substitute for testing the card write path.
  6. Compare and promote deliberately. Recheck that the original raw image’s hash is unchanged. Inspect the test folder for the expected GCI record and any Dolphin-managed metadata. Only after the in-game read, write, clean exit, and second launch all pass should you decide which copy will be authoritative. Keep the original raw image as a separate rollback artifact.

For example, on macOS a read-only hash comparison after Dolphin is fully closed can use:

shasum -a 256 "/path/to/MemoryCardA.raw" "/backup/MemoryCardA.before-test.raw"

Matching digests show that the two raw files contain the same bytes at the time of checking. They do not prove the card is valid, that the right region was selected, or that a GCI record will load in the game. On Linux, sha256sum provides the equivalent digest operation. Replace example paths with the actual configured paths; do not run hash or copy commands against a live, writable card.

Keep format, scope, and ownership clear

Use a raw image when you need an unchanged whole-card artifact. Use a GCI export when you intentionally want one save record. Use a GCI Folder when Dolphin should present a directory-backed card to a title, while understanding that the emulator reconstructs card structures and applies title, capacity, and session rules. Keep Wii NAND separate: it is console system storage, not another way to package a GameCube card. For general evidence-preserving response to a corrupted or overwritten save, use the separate save recovery workflow; for Wii system imports, see Dolphin Wii NAND isolation.

The durable practice is simple: preserve the complete source, verify which backend and path Dolphin actually selected, test one copy with the target game, and promote it only after a normal save survives a clean restart. A folder of GCI files is a useful emulator representation, but it is neither a byte-identical raw card nor an unlimited, self-validating archive.

Related:

Sources:

Comments