November 12, 2001 Volume 1, Issue 6 ©2001 Nintendo. All rights reserved. Avoiding Lot Check Pitfalls By Nintendo SDSG bugs or Guideline violations. If your game passes, the same procedure is performed at Nintendo Co. In This Issue: SDSG has been very busy these past few weeks Ltd. assisting developers with the Lot Check process Lot Check Pitfalls 1 and the Nintendo Guidelines. Now that we are Follow the Nintendo GameCube Nomenclature Moving from Dev Kit to over the launch title hump, we thought it would Document Production Console 7 be appropriate and beneficial to share what There are very specific ways of referring to the we’ve learned. This article covers some WAVEBIRD 8 Nintendo GameCube and its assorted components common pitfalls that were encountered by the and peripherals. Make sure you follow the launch title developers. (Names have been guidelines published by Nintendo. Our Legal removed to protect the innocent.) department is very particular about this. A game First, let's provide some background failed Lot Check because they used "Nintendo information. Lot Check is made up of dedicated Gamecube" instead of "Nintendo GameCube" game testers who methodically explore every (among other things). So be careful! possible unwanted scenario that your game may Follow Figure 2 in the Nintendo GameCube encounter. Their purpose is to ensure that Memory Card Guidelines players are satisfied with a consistent, bug-free interface to your game and to the Nintendo- Every launch title had this problem. (Send flame specific features. Lot Check also tests your mail to [email protected].) The flowchart in Figure game on every hardware revision that Nintendo 2 should be followed every time a Memory Card is releases (hence the name “Lot Check”). When mounted, and it’s required at the beginning of your you submit your game to Nintendo of America game (before gameplay). You may change the Inc., Lot Check will test your game to find any (continued on next page) HOW TO AVOID THE MOST COMMON LOT CHECK PITFALLS: ¾ Follow the Nintendo GameCube Nomenclature Document ¾ Follow Figure 2 of the Nintendo GameCube Memory Card Guidelines ¾ Use Informative Memory Card Error Messages ¾ Use One Memory Card File (if possible) ¾ Handle Hot-Swapping Support ¾ Create Memory Card IDs SDK Version ¾ Make Memory Card Messages Slot-Specific ¾ Handle All Memory Card Configurations The current release is ¾ Avoid Variable-Length Memory Card Files dated Sept. 8, 2001. ¾ Disable the Rumble Feature per the Guidelines Look for Patch 3 at ¾ Manage RESET Button Correctly www.warioworld.com. ¾ Handle Erase Errors and Program Errors (Memory Card Emulator) ¾ Handle Optical Disc Drive Fatal and Retry Errors 2 NINTENDO GAMECUBE™ Development News Avoiding Lot Check Pitfalls Use Informative Memory Card Error Messages (continued from previous page) When you first read through the Guidelines, you may notice the messages, but all possible Memory Card configurations are lack of very specific error messages for the specific error states circumscribed by the requirements in Figure 2. described above. Lot Check has found that giving specific While the messages may change, the error states will not change messages is often more confusing than not. Messages and display for a given CARD library. Be sure to recognize the various error formats are very game-specific, thus it is difficult to generate a states produced by the CARD library. There is a specific state list of messages that are not subject to change depending on game that applies to every return value for every CARD API, and design. Lot Check’s Memory Card Guidelines serve the most Memory Card issues are due to improper handling of these fundamental purpose of protecting and informing the player of errors. For example, CARD_RESULT_FATAL_ERROR is due any potential problems. Specifically, Lot Check wants to protect to program design or usage error. The CARD_RESULT_BUSY the player from loss of data or hours of gameplay. Your game is error means the current function is busy or waiting for another required to reflect these guidelines with proper, informative function to finish, so your program should call the function messages that alert the player to any possible problems. again. Table 1 provides a list of common error states and their That being said, we have compiled a list of error messages in path through Figure 2. Table 2. Keep in mind that these are only examples provided by (continued on next page) Table 1. A technical view of the current error states and their API path through Figure 2 of the Memory Card Guidelines Error Description Path through Memory Card Guidelines Figure 2 Capacity Your game must be aware of the Memory Card The application must verify card capacity. capacity. This only affects messages and management CARDProbeEx() returns card size in Mbits. screens that describe the number of free files or blocks. Sector Your game (as of this newsletter) must support only The application must verify card sector size. 8KB sector-sized Memory Cards. CARDProbeEx() returns sector size in bytes. Encoding Region encoding enforcement. CARDProbeEx(): CARD_RESULT_READY CARDMount(): CARD_RESULT_ENCODING Program/Erase Program and Erase errors are two scenarios of Will not necessarily show up in Figure 2. Any damaged Memory Cards. CARD API that attempts to write to a block will return CARD_RESULT_IOERROR. For example, CARDWrite(): CARD_RESULT_IOERROR CARDCreate(): CARD_RESULT_IOERROR CARDFormat(): CARD_RESULT_IOERROR Damaged A physically damaged Memory Card. CARDProbeEx(): CARD_RESULT_READY CARDMount(): CARD_RESULT_IOERROR Corrupt Corrupted system area. CARDProbeEx(): CARD_RESULT_READY CARDMount(): CARD_RESULT_BROKEN CARDCheck(): CARD_RESULT_BROKEN Recoverable Recoverable corruption to system area. CARDProbeEx(): CARD_RESULT_READY CARDMount(): CARD_RESULT_BROKEN CARDCheck(): CARD_RESULT_READY Data Corrupt The data portion of file is corrupted. The application must validate its own user data by use of a checksum, CRC, etc. at any data load time. NINTENDO GAMECUBE™ Development News 3 Avoiding Lot Check Pitfalls (continued from previous page) proper messages. Lot Check solely for this article. Lot Check reserves the right to Player options are very important. Lot Check prefers users to have change or refuse these messages if they do not correspond to the the following options for consistency across games: current Memory Card Guidelines. • Continue Without Saving The trickiest message is the “Full” message. Notice that Table 2 • Retry doesn’t give a clear answer in the “Error” column for the • Manage Memory Card “Capacity” entry. You will need to take into account your game’s save structure, including the number and size of the files “Continue Without Saving” has been around as long as the N64 created. There may be times when you can save one or several, and has become a Nintendo standard. Please use this exact phrasing but not all, of your game files to a Memory Card. Generate a where appropriate to meet Lot Check standards. matrix of all possible “Full” scenarios for your particular configuration, and make sure that the user is fully informed with (continued next page) Table 2. Example messages and options that correspond to the errors listed in Table 1 Error Message Options Action Upon Selection Capacity Game-specific. Used for messages relating to space availability Sector The Memory Card in Slot Continue Without Saving Continue Without Saving—proceed with game. A/B is incompatible with No other save opportunities are required. Retry the <Game Title> Save File. Retry—Allow consumer to insert a different Memory Card. Recheck status of new Memory Card. Encoding The Memory Card in Slot Continue Without Saving Continue Without Saving—proceed with game. A/B is formatted for another No other save opportunities are required. Retry market. Retry—Allow consumer to insert a different Format Memory Card. Recheck status of new Memory Card. Format—Format Memory Card. Program/Erase The Memory Card in Slot Continue Without Saving Continue Without Saving—proceed with game. A/B is damaged. It cannot No other save opportunities are required. Retry be used. Retry—Allow consumer to insert a different Memory Card. Recheck status of new Memory Card. Damaged The Memory Card in Slot Continue Without Saving Continue Without Saving—proceed with game. A/B is damaged. It cannot No other save opportunities are required. Retry be used. Retry—Allow consumer to insert a different Memory Card. Recheck status of new Memory Card. Corrupt The Memory Card in Slot OK OK—Format Memory Card, then proceed with A/B is corrupt. It needs to Save process. be formatted. Recoverable Processed in background. Data Corrupt The file on Memory Card in OK OK—Erase affected file, then proceed with Slot A contains corrupt data. Save option. The file must be erased. 4 NINTENDO GAMECUBE™ Development News Avoiding Lot Check Pitfalls (continued from previous page) Listing 1. Determining the number of files available “Retry” allows the user to insert another // return number of files available card and retry the current option (i.e., call // or return -1 if error accessing card s32 GetNumFilesAvail( s32 chan ) the API in Memory Card Guidelines { Figure 2). u32 numBlocks; u32 filesAvailable; Handling the “Manage Memory Card” s32 filesNotUsed; option is a little tricky. This option only s32 freeBytes; s32 freeBlocks; pertains to the full Memory Card message. u32 sectorSize; When your game is first booted and a full s32 result; card is inserted, we recommend resetting u16 cardSize; the system and forcing the Memory Card s32 totalSize; Menu to be displayed so that the player do can manage his card using the IPL. Since { result = CARDGetSectorSize(chan, &sectorSize); this must happen at the very beginning of } while (result == CARD_RESULT_BUSY); your game, the player cannot lose any if (result != CARD_RESULT_READY) data. return -1; However, during gameplay, the user may do { lose data if the system is rebooted. If your result = CARDFreeBlocks(chan, &freeBytes, &filesNotUsed); game saves multiple files, then the user } while (result == CARD_RESULT_BUSY); can fill up his or her Memory Card with if (result != CARD_RESULT_READY) your game’s files.