Skip to main content

Memory Card

Here we discuss the Twilight Princess save file structure on the memory card at a high level. If you are interested in things like rupees and poe souls, please see the Quest Log.

Overview​

Blocks​

You can think of a memory card as a filesystem. Each file on the memory card is composed of a number of "blocks", and each block is 0x2000 bytes long.

The first 5 blocks of a memory card are used to manage the filesystem:

OffsetSizeDescription
0x00000x2000Header
0x20000x2000Directory
0x40000x2000Directory (backup)
0x60000x2000Block Allocation Map
0x80000x2000Block Allocation Map (backup)

A file on a memory card will consist of a certain number of blocks which are located somewhere after the first 5 filesystem blocks.

For example, TP's save data is 4 blocks long, so these blocks might be located at offsets 0xa000, 0xc000, 0xe000, and 0x10000 on a fresh memory card, but they could also be at 0x22000, 0x24000, 0x26000, and 0x28000.

The blocks do not have to be contiguous, so the save data could also be in the blocks at offsets 0x36000, 0x20000, 0x28000, and 0x44000, but it is fine to think of them as contiguous in most cases.

tip

The official memory card types are Memory Card 59, Memory Card 251, and Memory Card 1019. Do you notice a pattern?
64 - 5 is 59, 256 - 5 is 251, and 1024 - 5 is 1019.

DirectoryEntry​

The Directory blocks contain a list of entries which are each 0x40 bytes long. Each of these entries is referred to as a DirectoryEntry.

A DirectoryEntry contains metadata about a file on the memory card. Each DirectoryEntry points to one file, and each file is pointed to by one DirectoryEntry.

Twilight Princess Save Data​

The Twilight Princess data on the memory card is a combination of a save file (which is 4 blocks long) and its metadata (a DirectoryEntry).

SizeDescription
0x40DirectoryEntry
0x80004 Blocks

Note that a GCI file is exactly these two things back-to-back as shown above.

Blocks​

TP save data is composed of 4 blocks which are each 0x2000 bytes long:

BlockNoDescription
1Header
2Header (continued)
3Quest Log Data
4Quest Log Data (backup)

Header Blocks​

The Header continues into the second block, so those two blocks will be treated as a chunk of 0x4000 bytes for discussion purposes. Remember that the two blocks may not actually be back-to-back on the memory card.

OffsetSizeDescription
0x00000xc00Banner pixel data
0x0c000x200Banner palette data
0x0e000x400Icon pixel data
0x12000x400Icon pixel data (copy)
0x16000x400Icon pixel data (copy)
0x1a000x400Icon pixel data (copy)
0x1e000x400Icon pixel data (copy)
0x22000x200Icon palette data
0x24000x20Comment 1
0x24200x20Comment 2
0x24400x1bc0Unused/garbage
zelda2_gc_banner.bti

A file on the memory card can have a banner. The banner always has dimensions 0x60 by 0x20 pixels (96 x 32 decimal).

TP's banner is in CI8 format (indicated in the DirectoryEntry) which means it uses one byte per pixel. 0x60 width * 0x20 height gives 0xc00 pixels total. At one byte per pixel, TP's banner is 0xc00 bytes long.

If a banner is in CI8 format, the 0x200 bytes following the pixel data are allocated to store its palette data. Each palette entry is 2 bytes, meaning a CI8 banner can use up to 0x100 unique palette entries. Each byte in the pixel data has a value between 0x00 and 0xff which is an offset to an entry in the palette data.

Note that TP's banner only makes use of the first 0x160 bytes of the palette data space.

Icons​

zelda2_gc_banner.bti

A file on the memory card can have between 0 and 8 icons. An icon always has dimensions 0x20 by 0x20 pixels (32 x 32 decimal). Multiple icons can be used to create an animated icon.

TP specifies in its DirectoryEntry that it has 5 icons and that each icon is in CI8 format with a shared color palette following all of the pixel data. CI8 format means each pixel takes one byte. Each icon has dimensions 0x20 by 0x20, so each icon is 0x400 bytes long.

As with the banner, the icon palette data must fit in the 0x200 bytes following the end of the pixel data. For its icons, TP makes use of the full 0x200 bytes of palette data.

info

The zelda2_gc_banner.bti and zelda2_gc_icon.bti are located in the Yaz0-encoded /res/CardIcon/cardicon.arc. "Card" here is short for Memory Card.

Fun Fact

The banner and icon both have a single semi-transparent pixel (most likely mistakes). If position x:0,y:0 is the top left pixel of the image, then the banner has this pixel at x:12,y:30, and the icon has it at x:2,y:1.

Comments 1 and 2​

Each comment is a null-terminated string which can use up to 0x20 bytes.

The comments (in addition to the banner and icon) are visible when managing memory card data on your GameCube.

For the US GameCube version of TP, the first comment is always "Zelda: Twilight Princess", and the second comment is something like "6/26 Save Data" (which is Month/Day).

Below is an image which shows the banner, icon, and comments in the Gamecube IPL.

zelda2_gc_banner.bti

Unused/Garbage​

The last 0x1bc0 of Block 2 is not used for anything.

If you inspect memory card data for TP in a hex editor, you may see what appears to be quest log data in this space. This is a side effect of using a shared buffer for writing blocks to the memory card. The buffer is not memset with zeroes before constructing the Header blocks like it is before copying in Quest Log blocks.

  • The buffer is zeroed out when you load the game.
  • If you tell the game to create a save file on the memory card, the buffer becomes dirty afterward.
  • When data is restored from the memory card for the file select screen, the buffer becomes dirty.

This means the only time you can save before the buffer becomes dirty is when you tell the game to create new Twilight Princess data on the memory card.

Other garbage​

Other bytes which may contain garbage in the first two blocks are as follows:

  • The last 0x40 bytes of the banner's palette data (starting at offset 0xd60)
  • In each comment (offsets 0x2400 and 0x2420), the bytes which follow the null termination character of the comment

Quest Log Blocks​

Block 3 contains the data for the 3 Quest Logs, which are the 3 files you pick between on the file select screen. Block 4 is a backup copy of block 3, so its data will normally match block 3's exactly (assuming nothing unexpected happened during any memory card writes).

The Quest Log block structure is as follows:

OffsetSizeDescription
0x00000x800000000 00000006
0x00080xa94Quest Log 1 Data
0x0a9c0xa94Quest Log 2 Data
0x15300xa94Quest Log 3 Data
0x1fc40x38Unused/garbage
0x1ffc0x4Checksum

First 8 Bytes​

The first eight bytes are always set to:
00 00 00 00 00 00 00 06

My guess is that this is a version number for the quest log structure which was incremented during development, and they ended on 6.

Quest Log Data​

Each Quest Log's data has the same structure. The structure is rather complex, so it is covered separately.

Unused/Garbage​

Note that each of the 0xa94 Quest Log Data sections contain unused/garbage bytes as well, but that is covered separately.

Checksum​

The checksum function runs over the first 0x1ffc bytes of the Quest Log block. The generated checksum is 4 bytes long, and it is stored as the final 4 bytes of a Quest Log block.

Here is the algorithm written in JavaScript:

function questLogBlockChecksum(arrBuf, offset, len) {
  const view = new DataView(arrBuf);
  let sum = 0;
  let negSum = 0;

  let index = offset;
  const iterations = len >> 1;
  for (let i = 0; i < iterations; i++) {
    const val = view.getUint16(index);
    sum += val;
    negSum += ~val;
    negSum &= 0xffff;
    index += 2;
  }
  return ((sum << 0x10) & 0xffff0000) + negSum;
}

DirectoryEntry​

These 0x40 bytes contain metadata about the Twilight Princess save data on the memory card. They live in a Directory block, hence the name. These are also the first 0x40 bytes of a GCI file.

OffsetTypeDescription
0x00u8[4]gameCode
0x04u8[2]publisherCode
0x06u8padding_06
0x07u8imageFlags
0x08u8[0x20]filename
0x28u32lastModified
0x2cu32imageDataOffset
0x30u16iconFormats
0x32u16iconAnimationSpeeds
0x34u8permissions
0x35u8copyCounter
0x36u16firstBlockIndex
0x38u16numBlocks
0x3au8[2]padding_38
0x3cu32commentsOffset

gameCode​

gameCode will be one of the following depending on the game region:

gameCodeRegion
GZ2EUSA
GZ2JJapan
GZ2PEurope and other PAL regions such as Australia

G is for Gamecube, Z2 is the title code for Twilight Princess, and the last character is dependent on the region as shown above.
Read more about it here: GameIDs - Dolphin Emulator Wiki

These bytes are available at address 0x80000000 which is where they are copied from when creating the DirectoryEntry.

publisherCode​

publisherCode will always be "01" (0x3031) which is the publisherCode for Nintendo.

These bytes are available at address 0x80000004 which is where they are copied from when creating the DirectoryEntry.

padding_06​

Unused byte which is always 0xff under normal conditions.
See Why is the padding 0xff? for more info.

imageFlags​

imageFlags is always 0x05 under normal conditions.

The image flags are the least significant 3 bits of the byte at offset 0x07. Bits 0 and 1 are used to indicate the banner format:

bannerFormatRegion
00No banner
018 bits per pixel, 16 bits per palette entry in RGB5A3
10Direct color, 16 bits per pixel in RGB5A3
11No banner

For TP, this value will always be 01, meaning the banner's palette data immediately follows its pixel data.

The third bit (bit 2) indicates the icon animation order.

iconAnimPatternRegion
0Loop (abcabcabc)
1Bounce (abcbabcba)

For TP, this value will always be 1.

Putting these values on top of a 0x00 byte, we get 0b00000101 or 0x05.

filename​

The filename for a TP save file is always "gczelda2", which is likely short for "Gamecube Zelda 2".

There are 0x20 bytes allocated for the filename, and under normal conditions any leftover bytes are set to 0x00.

info

"gczelda" (without the 2 on the end) is the filename for The Legend of Zelda: The Wind Waker save data.

lastModified​

This is the last time the file which the DirectoryEntry points to was modified. This value is stored as the number of seconds since 2000/01/01 00:00.

This value is calculated by dividing the OSTicks returned from OSGetTime by 40,500,000 (OSTicks per second) then taking the lower 32 bits of the 64 bit result.

LastModified to Time Converter

imageDataOffset​

Offset to the image data (banner and icons) relative to the start of the file.

For TP this value is always 0 (the banner data starts at the very front of the first block).

iconFormats​

The icon formats are stored as 8 groups of 2 bits which amounts to 2 bytes total (16 bits). Each 2-bit group indicates an icon's format as follows:

bitsDescription
00No icon
01CI8 with a shared color palette after the last icon's pixel data
10RGB5A3
11CI8 with its own palette following its pixel data

For TP iconFormats will always have the value 0x0155. If we convert this to binary, we get 0b0000000101010101. Grouping by 2 bits and starting from the least-significant (right) side, we get the following:

Index01234567
Value0101010101000000

Therefore TP has 5 icons which all share palette data after the 5th icon's pixel data.

iconAnimationSpeeds​

The icon animation speeds are stored as 8 groups of 2 bits which amounts to 2 bytes total (16 bits). Each 2-bit group indicates how many frames an icon displays during the animation.

bitsDescription
00No icon
014 frames
108 frames
1112 frames

For TP iconAnimationSpeeds will always have the value 0x0155. If we convert this to binary, we get 0b0000000101010101. Grouping by 2 bits and starting from the least-significant (right) side, we get the following:

Index01234567
Value0101010101000000

Therefore TP has 5 icons which each display for 4 frames before the next one is shown in the animation.

note

Each icon has identical pixel and palette data. This gives the appearance of a single icon, but there are actually 5.

permissions​

There are 3 permissions which are each 1 bit.

bitPermissionDescription
4No moveFile cannot be moved by the IPL
3No copyFile cannot be copied by the IPL
2publicFile can be read by any game

TP never changes this value from the default 0x04 meaning public (only bit 2 is set).

copyCounter​

copyCounter indicates how many times the file has been copied to a different memory card.

Starts at 0 and increments by 1.

firstBlockIndex​

The index of the first TP save data block on the memory card. This value must always be at least 0x0005 since the first 5 blocks are used to manage the filesystem.

For a GCI file, the value here is unimportant since a GCI file only contains blocks for a single game, and the blocks are always in order.

numBlocks​

The number of blocks a game uses. For TP this value is always 0x0004.

padding_38​

Two unused bytes which are both 0xff under normal conditions.
See Why is the padding 0xff? for more info.

commentsOffset​

Offset to the comments relative to the start of the file.

For TP, this value will always be 0x00002400.

info

The 0x40 byte chunk for the comments must be contained within a single block.

DirectoryEntry Follow-up​

Why is the padding 0xff?​

Short version:

  • The padding bytes are set to 0xff when the memory card is formatted.
  • They are never changed after that point.

Longer version:

When a memory card is formatted, its Directory blocks are mostly filled with 0xff:

OffsetSizeDescription
0x00000x1ffa0xff bytes
0x1ffa0x0002updateCounter
0x1ffc0x0002checksum1
0x1ffe0x0002checksum2

That is to say, all bytes are 0xff except the last 6.

Shortly after starting up the game (before the WARNING-HEALTH AND SAFETY screen shows), the two Directory blocks are read from the memory card into RAM. When you tell TP to create save data on the memory card, a portion of this RAM is overwritten with TP DirectoryEntry data which is then copied back to the memory card.

Within the 0x40 bytes in RAM into which the TP DirectoryEntry is written, the padding bytes are never overwritten since there is nothing which needs to be stored there. This means they maintain whatever value they had on the memory card. This value is expected to always be 0xff since the only time these bytes are modified is when the memory card is formatted.

However, you can manually manipulate the memory card beforehand so that these bytes are a different value. When you create a save file, you will see that the padding bytes are not modified from whatever value they had.

Below is a memory card raw image you can download which has had its first DirectoryEntry slot filled with 0xaa (other than the first byte which needs to be 0xff):

Download mem59_dirEntryAaBytes.USA.raw

If you create TP save data on a memory card with that image, you will see that the padding bytes never change from 0xaa.

Note that this applies to the padding at offset 0x06 and at offset 0x3a.

Thoughts on lastModified​

  • A time of 2136/02/07 06:28:15 would give 0xffffffff seconds after 2000/01/01 00:00. I think the only way to get your Gamecube's date this high is to set it to 2099 and wait 30+ years. Even then, it is possible that the OSTick count returned from OSGetTime is based on a fixed clock and is not adjusted with any changes you make in the IPL (this could be tested). In any case, the clock battery would probably die before this became an issue.
  • The 64 bit OSTicks count wouldn't get its sign bit set until around Sep 18, 9216 at 15:12:36.908044, so this is not worth thinking about.

CheckCardStat​

When restoring data from the memory card, one of the things TP does is run a function called m_Do_MemCardRWmng::mDoMemCdRWm_CheckCardStat. This runs a few checks on the loaded DirectoryEntry data. If any of these fail it is considered a fatal error, and the game will act as if you don't have any save data on the memory card (meaning it will ask you to create save data).

Here are the checks which must always pass:

  • imageDataOffset is 0x00000000
  • commentsOffset is 0x00002400
  • imageFlags: the least signficant 3 bits are 0b101
  • iconFormats is 0x0155
  • iconAnimationSpeeds is 0x0155

Room for custom data?​

As discussed in Why is the padding 0xff?, we can manipulate the padding bytes to any value and their value will persist between saves. Are there any other places like this in the DirectoryEntry?

In CheckCardStat, we determined some things which we can't change without upsetting the game. Skipping over those and the padding, we are left with the following:

gameCode, publisherCode, upper 5 bits of imageFlags, filename, lastModified, certain permissions bits, copyCounter, firstBlockIndex, numBlocks

gameCode, publisherCode, filename​

gameCode, publisherCode, and the filename contents up to and including the first 0x00 byte are used to locate the TP save file on the memory card, so these cannot be changed.

However, since the filename string comparison stops when it hits the first null byte, we can put whatever we want in the remaining 0x17 bytes.

imageFlags​

After the very first write, the DirectoryEntry looks like the following:

47 5A 32 45 30 31 FF 00 67 63 7A 65 6C 64 61 32
00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
00 00 00 00 00 00 00 00 28 69 BB 43 FF FF FF FF
00 00 00 01 04 00 00 05 00 04 FF FF FF FF FF FF

Most of the values are filled with defaults. This is quickly overwritten with TP-specific values:

47 5A 32 45 30 31 FF 05 67 63 7A 65 6C 64 61 32
00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
00 00 00 00 00 00 00 00 28 69 BB 43 00 00 00 00
01 55 01 55 04 00 00 05 00 04 FF FF 00 00 24 00

Initially, the imageFlags byte (offset 0x07) is set to its default value of 0. It is during the 2nd write that TP fills in the 3 important bits.

We know that the least significant 3 bits must be 0b101 for TP to accept the save file as valid. However, the top 5 bits are never checked, and they are only overwritten when they are initialized to 0. This means that we can set those 5 bits to whatever we want and they will maintain their value.

lastModified​

lastModified gets updated every time the save file is updated, so any data you put here will be lost.

permissions​

permissions is set to 0x04 (public) during the initial DirectoryEntry creation. For TP, the permissions are never changed after this point. Since only 3 of the bits on the permissions byte carry any meaning, we can do as we please with the other 5 bits.

copyCounter​

This is incremented when copying between memory cards, so there is not much point in putting anything here.

firstBlockIndex, numBlocks​

These are critical metadata which must not be changed.

For a GCI file, firstBlockIndex is irrelevant so it can be changed, but its value will be lost if it gets imported to a memory card.

Summary​

We can put whatever data we want at the following locations with no adverse effects:

  • padding_06 which is 1 byte
  • Unused 5 bits in imageFlags
  • 0x17 (23 decimal) bytes following the filename's null termination byte
  • Unused 5 bits in permissions
  • padding_3a which is 2 bytes

These gives us a total of 26 bytes and 10 bits.

Below is a memory card raw image which has had these locations in the DirectoryEntry modified. TP will recognize the save file and everything will behave normally from a memory card perspective. The custom data in the DirectoryEntry will be maintained even if you save the game.

Download mem59_tpCustomDataDirEntry.raw

Note that you will lose some of the data if you transfer the TP save file between memory cards using the Gamecube IPL:

  • Padding bytes are not copied.
  • Any bytes in the filename after the null termination byte are lost.

Other Formats​

GCIs​

You can think of a GCI as a portable version of a game's data on a memory card.

  • A Twilight Princess GCI file is 0x8040 bytes long and is simply the DirectoryEntry (0x40 bytes) followed by the 4 Blocks (0x8000 bytes).
  • The value of the DirectoryEntry's firstBlockIndex is not important in a GCI file.

Wii​

  • TBD

Nvidia Shield​

The Shield's save data is 0x4000 bytes long. It is composed of Blocks 3 and 4, which are the Quest Log data block and its backup.

  • The Header blocks are not important since their only purpose is to provide banner, icon, and comments data to the Gamecube IPL.
  • The DirectoryEntry is not important since it only provides metadata about the Header blocks and other values which are specific to the memory card (such as firstBlockIndex).

Closing Thoughts​

Here we only covered as much as was necessary to talk about the memory card in the context of TP. If you would like to read more about the structure of data on the memory card, check out these links:

Note that YAGCD is wrong about imageFlags in the DirectoryEntry, so be sure to check the Dolphin source code for that one.

Why 5 identical icons?​

You might have noticed that 87% of block 2 is unused and that we could easily fit the Header on a single block if we did not store 5 copies of the same icon pixel data.

In short, the Header could have been a single block making the game 3 total blocks instead of 4. An animated icon was probably planned at some point but never came to fruition. Below is the detailed explanation.

Icon metadata for some games which do not have an animated icon:

GameiconFormatsiconAnimationSpeedsiconAnimPattern bit
Metroid Prime0x00010x00020
Resident Evil 00x00020x00020
Resident Evil 40x00010x00031
Super Smash Bros. Melee0x00010x00030
Tales of Symphonia0x00020x00030
The Legend of Zelda: Four Swords Adventures0x00010x00030
The Legend of Zelda: The Wind Waker0x00010x00030

All of these games indicate that they have a single icon in the iconFormats field.

Icon metadata for some games with an animated icon:

GameiconFormatsiconAnimationSpeedsiconAnimPattern bit
Fire Emblem: Path of Radiance0x00150x003b1
Kirby Air Ride0x55550xef550
Luigi's Mansion0x40410xffff1
Mario Kart: Double Dash!!0x00150x002a0
Sonic Adventure 2 Battle0x000a0x000f1
Soulcalibur II0x55550xaaaf1
Super Mario Sunshine0x00050x000f0
The Legend of Zelda: Ocarina of Time Master Quest0x002a0x002a1
The Legend of Zelda: Twilight Princess0x01550x01551

These games which have animated icons indicate multiple icons in their iconFormats field. It it clear that Twilight Princess's icon metadata (bottom row of table) matches the pattern of the animated icons.

Another other important thing to note is that The Wind Waker only has a single icon, and its metadata lines up with what you would expect (see the bottom row of the first table). It would not make sense for the developers to take something which was already working and make it worse for no reason.

Additionally, an animated icon is the only valid use case for storing multiple icons in a file on the memory card.

For these reasons, I think it is pretty evident that the developers had plans for an animated icon. I suspect that they either ran out of time or decided against it, and they never went back to update the code. Either way, what we end up with is a game with save data which takes 4 blocks when it could have easily taken 3.

Below is a modified memory card which contains TP data which has been adjusted to take only 3 blocks. You can download it and view it in a Gamecube IPL or Dolphin's Memory Card Manager to see that it only uses 3 blocks yet provides the same icon, banner, and comments metadata. If you inspect it in a hex editor, you will see that it contains the 2 Quest Log blocks as well.

Download mem59_tp3Blocks.USA.raw

Note that the data will not work with the Twilight Princess game since TP expects its save data to be 4 blocks, and it verifies that the metadata (DirectoryEntry) matches certain values. The above file is just to demonstrate that the Header blocks (which exist purely for the IPL's sake) could have been a single block and been functionally indistinguishable from the normal 2 block header.

For your convenience, below is an image of what this would look like. The image is taken from a Gamecube IPL running in Dolphin.

zelda2_gc_banner.bti

Default selection on the file select screen?​

You might expect there to be some metadata outside of the quest log data which indicates the quest log to default to on the file select screen, but this is not the case.

The default is picked this way:

  • From the set which includes Quest Log 1 and any other Quest Logs which pass their checksum test, pick the Quest Log which has the latest timestamp (compared at the seconds level).
  • In the case of a tie, Quest Log 1 has the highest priority and Quest Log 3 has the lowest priority.
info

Quest Logs which fail their checksum test say "This Quest Log is corrupted."

Naming​

General​

Names on this page were decided in this way:

  1. Pick the best name from a group of memory card references.
  2. Make adjustments with clarity, accuracy, and styling in mind.

Some examples:

  • publisherCode is called makercode in some of the references, but it was changed here since publisher is more accurate. Using an example from YAGCD, Retro Studios developed Metroid Prime, but the publisherCode is still "01" for Nintendo.
  • "animation speed" was changed to "iconAnimationSpeeds" so you can quickly tell that it relates to icons and that the field stores multiple speeds.

DirectoryEntry​

This DirectoryEntry data is written as an entry on the Directory Block, hence the name DirectoryEntry. We are using this name for a couple of reasons:

  • Variations of "directory entry" (such as 'DEntry' and '_card_direntry') are what you will see in other places.
  • We can afford to be more descriptive with the name since this is only documentation and not source code.

The OS functions CARDGetStatus and CARDSetStatus handle reading and writing data to the DirectoryEntry through a similar object structure which might have been called CARDStat. libogc calls the structure _card_stat, and frameworkF.map mentions these functions as coming from CARDStat.o.

TP also has funtions m_Do_MemCardRWmng::mDoMemCdRWm_SetCardStat and m_Do_MemCardRWmng::mDoMemCdRWm_CheckCardStat which call the OS functions internally.

These function names bring to mind the Linux command stat which is said to "display file or file system status". The data in this 0x40 byte chunk is essentially what you would see if you could run that command on a memory card (metadata about a file stored in the filesystem).

The term "Directory Block" is supported by the OS function card::__CARDGetDirBlock.

References​