Patch:Galaxy menu tutorial

This page is a tutorial on the structure and function of the main menu actions for the Keen Galaxy games. It is divided into three sections; first a brief overview, followed by a section that deals with 'menu setups' which control the screen layout of a menu. The third section deals with 'menu options' each of which controls one option in a given menu.

Menu organization

A menu consists of several 'menu setups' and 'menu options'. Only one menu setup can be used at a time and it typically uses all the menu options available to it. Several related setups are often close together such as the Keyboard, Joystick and Gravis Gamepad menu setups.

Both setups and options are 22 and 18 byte long strings of data that are read by the game in a similar fashion to sprite actions. Each menu option and setup thus also has a unique 'address' that can be pointed to.

Menu setups

As noted menu setups control how a menu is set out. It is what the game calls when it wishes to display a menu onscreen. A menu setup patch looks something like this:

Menu setup

#Menu setup
%patch $1F6B4 $0008W $0004W $000BW $0000W $0000W $1F69RW $00000000L   $0000W $0000W $0000W

The ten values that make up the menu setup have the following basic structure:

Value	Function
1	Horizontal text offset
2	Vertical text offset
3	Menu bitmap
4	Unknown
5	Unknown
6	Start of menu options
7	Menu code
8	Unknown
9	Unknown
10	Unknown

Horizontal and vertical text offset: These two variables control where the menu text is positioned onscreen. The point 0,0 is the top left of the computerwrist screen and larger values of these two variables moves the menu texts down and right. This affects all menu options.

Menu bitmap: This variable controls what image appears above the menu being displayed. For the Main menu for example this is the 'MAIN MENU' bitmap. Bitmaps are centered above the menu (Their location depends on their size.). A value of 0 means that the currently displayed bitmap is not altered.

Start of options: This variable gives the 'address' of the first menu option the menu uses. If this is 0 then no options are used. Otherwise it is simply the location of the menu option minus its last digit. As an example the value $1F69RW points to the location $1F690. (The 'RW' means that the address is relative and doesn't affect the location.) This means that menu actions can only start at addresses ending in '0' since the last digit is 'amputated' in the pointer. (Following menu options are not limited in this way, only the first.)

Menu code: This is the code run by the menu when it is accessed. This is responsible for the function of most items when they are selected, such as loading a game or turning music off.

Menu options

Menu options are 18 byte strings of data each of which controls a single item in a menu. A menu points to its first option and options are read until a type 0 option is encountered. (This is usually a string of 18 empty bytes.) Menu options look as follows:

Menu option

#Menu options
%patch $1F690 $0001W $0000W $0000W $41F6W $0000W $00000000L  $0000W $0000W

#Menu text
%patch $34F26 "DEBUG" $00

The eight values that make up the menu setup have the following basic structure:

Value	Function
1	Option type
2	Next option vertical offset
3	Scancode
4	Text pointer
5	Select return value
6	Select menu pointer
7	Unknown
8	Unknown

Option type: This governs how the option works. There are four possible values for the type:

0	Empty
1	Return value
2	Refresh menu
3	Refresh menu, run code

Type 0, as noted signifies an 'empty' option and tells the game that there are no more menu options to read. The game will crash if the first menu option is empty.

Type 1 returns a value to the game's code such as the difficulty of game to start. This value then does something. Type 2 refreshes the screen while changing something. This is used for example by the music menu to turn music on or off. Type 3 also refreshes the screen but also runs the option's code, usually changing the current menu.

Next option vertical offset: This is how far down, in pixels, the next option will appear. A value of 0 makes the next option's text appear 1 pixel below while a value of 8 will create a one-line 'gap'. This is only used in the configure menu to separate to sections of options.

Scancode: This is the 'shortcut key' that causes the game to jump tot his menu option. Scancodes are listed here. As an example in the music menu the 'No music' option has the scancode $0031W which is the 'N' key. Pressing N wil thus jump to that option.

Text pointer: This is a pointer to the option's text. If 0 then the option gets its text in the menu code. Some options point to 'empty strings' that is 'text' that contains no text at all so as not to interfere with the code text. Text pointers are explained in Patch:Text patches.

Select return value: For type 1 actions this is the value returned to the menu code when the option is selected. This is used to do something such as start a game of a specific difficulty.

Select menu pointer: This is a pointer to a different menu. In the same way menus point to options options can point to a menu and change to that menu when selected. The pointer is more complex. To find the address of the menu the first four digits have an 0 added to the end then the next four digits are added to that number. As an example $1F7F007ERL points to $1F86E. ($1F7F,$007E -> $1F7F0 + $007E = $1F86E.)