Memory Card GUI Module (mcgui)

Provides the save and load screens for the Memory Card in game titles.

Overview

The Memory Card GUI module (McGUI) is a program that complies with the TRC (Technical Requirements Checklist). It provides the Memory Card load and save functions together with their user interface. A game title that includes McGUI therefore needs less code for its Memory Card screens.¹

A program that uses McGUI links with mcgui.obj and includes mcgui.h, which defines the structures, functions and macros of the module. McGUI uses the following libraries, and the program must link them as well:¹²

This library is part of the run-time library that Sony distributed with the Psy-Q development tools.³

Module Functions

McGUI has two functions. McGuiSave() saves game data and McGuiLoad() loads it. Before either is called, a McGuiEnv structure is set up with the values for the screen. The module checks some of the values, but not all conditions, so an invalid value does not always give an error.¹

McGuiSave() runs the save operation of the Memory Card screen. The user selects a slot, the module checks its status, such as no card or an unformatted card, and checks its contents for earlier saves and empty blocks. It then saves the game data and returns to the title. McGuiLoad() runs the load operation in the same way and checks for earlier saved data. Both functions return 1 when the operation completes, 0 when the user cancels on the slot selection screen and -1 for an invalid value in McGuiEnv.¹⁴²⁵

McGuiEnv Structure

McGuiEnv is the main structure of the module, and each of its members is a structure of its own:⁶

sMcGuiCards holds the file name of up to 20 ASCII characters and the Shift-JIS document name of 32 full-size characters. It also holds the number of icon images from 1 to 3 and the TIM address of the icon. The address of the game data and its size in 128-byte units complete it, and the data occupies 1 to 15 blocks.⁷

sMcGuiBg selects the background. Mode 0 scrolls an internal 64 x 64 tiled texture in one of 8 directions at a speed of 1/60, 1/30 or 1/20 second, and mode 1 shows the still image of the TIM at timadr.⁸

sMcGuiController holds the two receive buffers of the controllers. For each controller type, the default controller, the mouse, the analog joystick or DUAL SHOCK, and the NeGcon, it holds a flag and the button codes of OK and cancel. The flag is 1 for a supported type and 0 for an unsupported one.⁹

sMcGuiSnd holds the main volume and the reverb setting together with two groups of sound data. The BGM group gives the SEQ data with its VH and VB data and the SEQ volume. The sound effect group gives the VH and VB data, the volume, the program number and the tone numbers of the confirm, cancel, cursor and error sounds. sMcGuiCursor sets the color of the menu cursor, while its shape (type) is not supported.¹⁰¹¹

Controllers

McGUI supports the following controller terminal types, and it does not support guns or Multi Taps except at ports 1-A and 2-A:⁴

Initialization and Termination

McGUI calls SsInit(), SsStart(), ResetGraph() and ResetCallback() itself, and it calls SsEnd(), SsQuit() and StopCallback() when it exits. Before it calls a McGUI function, the application initializes libmcrd with MemCardInit() and runs MemCardStart() and MemCardStop() as needed. It also initializes the controllers with functions that set up receive buffers in the application, such as InitPAD() and PadInitDirect(), and gives the buffer address in McGuiEnv. PadInit() cannot set up such a buffer and is not supported.⁴¹²

Limitations

The block count of a save is fixed by the first save made with McGUI. Existing data cannot be overwritten by data of more blocks, so a game whose saves grow makes its first save at the largest size.¹²

The TIM header of the texture data sets where the images and CLUTs load in the frame buffer, and these areas must not be in use by the game. McGUI also uses the 67 lines below the image as a work area, which must not overlap the CLUT. The images load at the start of a texture page, the texture always uses 128 x 128 8-bit CLUT mode, and the positions and sizes of the titles and the mouse cursor are fixed.¹²

The screen resolution is fixed at 320 x 240. Drawing uses two frame buffers, so the frame buffer area (0, 0) to (319, 479) is destroyed.¹³

SEQ data always plays at TICK60 and is made for TICK60. Up to 23 voices sound at once, and the 24th is reserved for sound effects, which play with SsUtKeyOnV() at note 60 and fine 0. The contents of the sound buffer are not guaranteed after McGUI ends, so the game transfers its waveform data again as needed.¹³

Functions

McGUI has the following functions:²⁵

References