Fujiology Archive

home *** CD-ROM | disk | FTP | other *** search

/ Fujiology Archive / fujiology_archive_v1_0.iso / !FALCON / !BONUS / GAMES / TETR141.ZIP / HELP / TETRHELP.ENG < prev next >

Wrap

Text File | 1996-01-29 | 79KB | 1,474 lines

TETRHEX, version 1.40 (24/01/1996) ¯¯¯¯¯¯¯ This text contains the whole TETRHEX documentation. It can be obtained in 3 different ways: directly by reading the file TETRHELP.ENG, by choosing the item "Help about TETRHEX" (Help key) in TETRHEX, or by typing "tetrhex -h" in a shell. In case it is the second way, here are the used keys: up and down arrows (1 line), with Ctrl (4 lines), with Shift (1 page), with Ctrl-Shift (4 pages), Clr-Home (begining of the document), Shift-Clr-Home (end of the document), Esc (quit). TETRHEX is a SHAREWARE game. If you want the complete version (without any limitation), you must get registered by sending me 50 FF or 20 DM (or more if you want) to the following address: Vincent Lefèvre 24 rue Louis Blanc 31400 Toulouse FRANCE Don't forget to give me your name and your address! If you have Internet access, I recommend that you contact me first by e-mail: vlefevre@ens.ens-lyon.fr The last unregistered version is available at: http://www.ens-lyon.fr/~vlefevre/tetrhex/index_eng.html Contents ¯¯¯¯¯¯¯¯ 0. Standard Disclaimer 1. Introduction 2. System Requirements 3. Compatibility 3.1. Floppy Disk or Removable Hard Disk 3.2. Screen Blaster Card 3.3. Blow-Up 3.4. Let 'em Fly 3.5. Winx (version 2.2) 3.6. NVDI (versions 2.5 and 3) 3.7. SpeedoGDOS (version 4.xx) 3.8. Outside (Virtual Memory) 3.9. LED Panel 3.10. Idle (Screen Saver) 3.11. System Other Than TOS 4. Starting and Configuring TETRHEX 5. TETRHEX Game 5.1. Main Menu 5.2. Help 5.3. Player Name 5.4. Game 5.5. Highest Scores Display 6. Rule Files 6.1. Data Occuring During a Game 6.2. Actions 6.3. Signals 6.4. Game Phases 6.5. Special Variables 6.6. Color Codes 6.7. PAUSE Modes 6.8. Rule File Structure 6.9. RUL Language 7. Messages 8. Technical Notes 8.1. Program Flags 8.2. Error Codes 8.3. Moving the Window 8.4. Palette Modification 9. Limitations of the Unregistered Version 0. Standard Disclaimer ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯ I cannot be held responsible for any damage caused by this software. Use is entirely at your own risk. 1. Introduction ¯¯¯¯¯¯¯¯¯¯¯¯ TETRHEX is a game, or rather a group of Tetris-like or Columns-like games, being played on a hexagonal board, with hexagonal cells. Its main features are: _ You can modify existing rule files and create your own rules in a TETRHEX-specific language. 3 rules are provided with TETRHEX: Tetrhex, Hexcolumns and Tet'light. _ Special pieces, that make the game more interesting. _ TETRHEX uses GEM functions, except for some displays. Therefore it is compatible with many system programs (in the AUTO folder): NVDI, SpeedoGDOS, Screen Blaster card, Outside, MiNT/MultiTOS, ... _ TETRHEX can display outline fonts if SpeedoGDOS or NVDI 3 is active. You can choose the fonts. TETRHEX automatically selects the most suitable font height, according to the font and the text to display. _ Many options; configuration on 2 levels as Unix-like options: permanent (in a file) and at the start. _ You can play on the whole screen or in a GEM window (AES 4.1 is supported: the window can be iconified). _ You can use TETRHEX as an accessory. _ List of languages to use in order of preference, particularly useful because of the help in rule files. By default, the language of the system is preferably used. _ The hexagonal board has a variable size (4 different sizes). _ TETRHEX can save up to 255 scores for each rule and each size of the hexagonal board. _ You can give a group of relocatable routines enabling TETRHEX to communicate with the outside. Possible applications (some routines don't exist yet): playing with the Joypad (instead of the keyboard) or even playing using your voice (thanks to the DSP), having .MOD modules played in the background at given moments, putting images in the background, making the computer play, rule file debuggers, ... 2. System Requirements ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯ TETRHEX has been written for Falcon, but should be able to run on any Atari (or other TOS-based computer) having a 680x0 with x ≥ 2 and a Falcon compatible (i.e. interlaced planes) graphic mode 256 colors ≥ 640 * 480, possibly with a substitute operating system (TOS/GEM compatible). On a Falcon, TETRHEX can run with any type of color screen. However a VGA monitor is recommended; for on a RGB screen, TETRHEX must run in interlaced mode. TETRHEX needs about 300 KB free RAM (ST RAM or TT RAM). One of the timers A and D is required (cf section "Starting and Configuring TETRHEX"); the default timer is the timer D. 3. Compatibility ¯¯¯¯¯¯¯¯¯¯¯¯¯ Unlike most games, TETRHEX is generally compatible with the programs being in the AUTO folder. However sometimes there may be some problems. Idem for the hardware. The list of tested software/hardware and encountered problems is given below. In whole screen mode, if you aren't in an adequate resolution, TETRHEX automatically tries to change the resolution. The main problem is that some AUTO programs don't allow this. Either you have to remove these programs, or you have to switch to an adequate resolution before starting TETRHEX. Note: the order of the programs in the AUTO folder is very important; some information given below may be more or less correct, according to the order. 3.1. Floppy Disk or Removable Hard Disk ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯ If the rule file has been loaded from a floppy disk or a removable hard disk (SyQuest), you mustn't change the disk if the list of the scores can be modified (this is generally the case), particurlarly if the new disk has a file with the same name and the same path. 3.2. Screen Blaster Card ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯ TETRHEX never tries to change the resolution, otherwise the computer bombs. In order to know whether the Screen Blaster card is active, the OSBL cookie is searched for. Note: this cookie can be removed only after a complete reboot (Ctrl-Alt-Rshift-Delete); therefore the resolution change may be refused whereas the card isn't active (after a partial reboot). Like with other programs / cards that enhances the resolution, in whole screen mode, only the centered 640 * 480 part of the screen is used. 3.3. Blow-Up ¯¯¯¯¯¯¯ In whole screen mode, TETRHEX bombs if the Y-resolution isn't a multiple of 16. I don't know why. 3.4. Let 'em Fly ¯¯¯¯¯¯¯¯¯¯¯ If the "Send Redraw" option is selected, there is a display problem after the file selector is called: in GEM window mode, a redraw message is sent (this just wastes time); in whole screen mode, the part under the file selector is cleared (it's more embarrassing). Thus it is recommended not to select the "Send Redraw" option if you need to load other rule files, particularly in whole screen mode. 3.5. Winx (version 2.2) ¯¯¯¯ There's no problem. In GEM window mode, you can untop the window by clicking on the title bar. 3.6. NVDI (versions 2.5 and 3) ¯¯¯¯ It is impossible to change the resolution, but in general the computer doesn't bomb (it bombs if LED Panel is installed). It is recommended to select the "TOS compatibility" option if you need to load other rule files. Otherwise you'll have the same problem as with Let 'em Fly with the "Send Redraw" option (cf above). With NVDI 3 you can use outline fonts. But don't use them in the help: that completely bugs. 3.7. SpeedoGDOS (version 4.xx) ¯¯¯¯¯¯¯¯¯¯ If SpeedoGDOS is installed (this is recommended, except if NVDI 3 is installed), you can use outline fonts. It is impossible to change the resolution, but the computer doesn't bomb. If some outline text has been underlined (in the help), filled rectangles aren't displayed any longer: you have to quit. This seems to come from a bug from SpeedoGDOS. 3.8. Outside (Virtual Memory) ¯¯¯¯¯¯¯ There's no problem. Flags about the TT-RAM may be set. 3.9. LED Panel ¯¯¯¯¯¯¯¯¯ In order to avoid display conflicts, LED Panel can be desactivated in whole screen mode. LED Panel is reactivated when TETRHEX ends. 3.10. Idle (Screen Saver) ¯¯¯¯ When the protection is activated, TETRHEX memory blocks may be altered (tests with Idle 2.2). 3.11. System Other Than TOS ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯ Memory protection mustn't be used if video memory is protected against read/write. A rule file loaded by TETRHEX mustn't be modified if the list of the highest scores can be modified, because TETRHEX wouldn't be aware of it and the file structure could become bad. 4. Starting and Configuring TETRHEX ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯ TETRHEX can be started either by double-clicking on its icon from the desktop, or from a shell (for instance Gemini shell). Unix-like options can be given. TETRHEX creates a string composed of the configuration file TETRHEX.CFG (if it exists), followed by the command line options (if there are ones); an example will be given after the list of options. Note: to have the possibility to enter options after double-clicking on the icon, you must replace the extension .PRG by the extension .GTP (.TTP equivalent for a GEM program). The options start with the '-' character and are separated by blanks (space and control characters, i.e. characters whose ASCII code is ≤ 32). The command line mustn't have more than 125 characters; if there are too many options, store them in a file and use the -o option. If the syntax of the whole string isn't correct, the program immediately ends (and returns an non-zero error code). Here are the options: -b <Ir> <Ig> <Ib> <Dr> <Dg> <Db> Colors of the hexagonal board. This option is followed by 6 numbers, between 0 and 255. The first 3 numbers are the intensities of the red, green and blue components of the frame. The last 3 numbers are values to substract from the intensities to display the next part of the frame towards the background. These values multipled by 3 must be respectively less or equal to the first 3 values, because there are 3 background planes. The 6 default numbers are 240, 240, 240, 48, 48, 48. If the conditions aren't consistent, the option isn't taken into account. -cd <R> <G> <B> [Color Date] Color of the date. This option is followed by 3 numbers between 0 and 255: the intensities of the red, green and blue components. If a number is out of range, the corresponding intensity isn't changed. If after all the "-cd" options the intensities are 0, then the 3 intensities are set to 255 (white). -ch <R> <G> <B> [Color Help] Color of the help text. Cf "-cd" option. -ci <number> [Color Icon] Index of the color of the icon (as of AES 4.1), between 0 and 15. -cp <number> [Color Pause] Index of the color of "-- PAUSE --" (window pause mode), between 0 and 15. -ct <R> <G> <B> [Color Time] Color of the time. Cf "-cd" option. -da [Display All] The date and the time are displayed (like "-dy -ds"). -dd [Display Date] The date is displayed without the year. -dn [Display Nothing] Neither the date nor the time is displayed. -ds [Display Seconds] The time is displayed with the seconds. -dt [Display Time] The time is displayed without the seconds. -dy [Display Year] The date is displayed with the year. -e[+/-] [Error display] Error messages may be sent to the standard output. You should use this option only in the following cases: you're under MultiTOS and you have a console, and/or TETRHEX doesn't work as you want to and you'd like to know the reason. -f+ <number> Number to add to the numbers of the outline fonts to obtain the index (used by the VDI). Default value: 0. According the SpeedoGDOS version, it's usually 0 or 5000. In the following options "-f? <number>", the number must be preceded by a '+' if it's an outline font. -fe <number> [Font mEnu] Number of the font used to display "Menu". -fg <number> [Font Game] Number of the font used in the game. -fh <number> [Font Help] Number of the font used to display the help text. -fm <number> [Font Menu] Number of the font used in the menus. -fn <number> [Font Name] Number of the font used to display the rule name. -fo <number> [Font game Over] Number of the font used to display "game over". -fp <number> [Font Pause] Number of the font used to display "-- PAUSE --". -fr <number> [Font Register] Number of the font used to display the text under "Shareware". -fs <number> [Font Score] Number of the font used to display the scores. -ft <number> [Font Tetrhex] Number of the font used to display "TETRHEX x.xx". -fw <number> [Font shareWare] Number of the font used to display "Shareware". -gdos TETRHEX behaves as if SpeedoGDOS were installed (useful if the GDOS flag isn't correct). -h or -help Help: the help file is written to the standard output. -i off Internal speaker off. N.B.: the speaker won't be switched on again at the end of the program. -i on Internal speaker on. N.B.: the speaker won't be switched off again at the end of the program. -l <param> Language preferences. There are as many parameters as you want (possibly none). Each parameter is either a nonnegative number, that indicates the language in an absolute way (cf below), or the '?' character, that indicates the language given by the _AKP cookie (language used by the system), or the '*' character, that indicates one or several languages close to the one used by the system (there are only 3 language groups: {0, 3}, {1, 8} and {2, 7}). The default parameter string is "* 0 3". Country codes: 0: USA, 1: Germany, 2: France, 3: United Kingdom, 4: Spain, 5: Italy, 6: Sweden, 7: Switzerland (French), 8: Switzerland (German), 9: Turkey, 10: Finland, 11: Norway, 12: Denmark, 13: Saudi Arabia, 14: Holland, 15: Czechoslovakia, 16: Hungary. -ma [Memory Allocate] The memory block containing the background image will never be freed (except when the program ends), so this image will never be calculated again. -mf [Memory Free] The memory block containing the background image will always be freed after the image is displayed, and the background image will always be calculated again when it is to be displayed again. -n <number> Length of an edge of the hexagonal board (between 6 and 9). -o <file> [Options] The list of the remaining options is replaced by the file; this allows to have several configuration files. -p <string> [Player] The string contains the player name between simple or double quotes. If the string is empty (default string), the player will have to enter his name if his score is high enough to enter in the list of the highest scores. -r <file> [Rule] Rule file (.RUL extension) to load by default. -s <file> Message file (.MSG extension), allowing TETRHEX to communicate with other programs (cf section "Messages"). -ta [Timer A] The timer A will be used (whether the Lshift key is pressed or not). -td [Timer D] The timer D will be used (whether the Lshift key is pressed or not). -u[+/-] The list of the highest scores mustn't be modified. -vhc <n0> <n1> <n2> <n3> <n4> <n5> <n6> <n7> [Video Hex Color] Intensities of the 8 levels to display the hexagons. The first number corresponds to the darkest level, and the last one to the brightest level. For instance, for a yellow hexagon, the intensities of the red and green components will have the value given by the option, and the intensity of the blue component will be 0. The default values are: $30, $60, $78, $90, $A8, $C8, $D8, $F8. -vhw <n0> <n1> <n2> <n3> <n4> <n5> <n6> <n7> [Video Hex White] Intensities to add to each component of the corresponding level (given by the "-vhc" option). If, for one or several components, the sum is greater than 255, then it is set back to 255. The default values are: $00, $00, $00, $00, $10, $20, $50, $80. -vl[+/-] [Video LED Panel] LED Panel is switched off in whole screen mode (nothing is done in GEM window mode). LED Panel status will be restored at the end of the program. -vr[+/-] [Video Resolution] The resolution mustn't be changed; if it is not correct, an error is returned. -vs[+/-] [Video Synchro] Synchronization with the VBL interruption for some displays, particularly for the outline fonts display; in this last case, this option is useful only if the display is fast enough. It's the case of NVDI 3, but it isn't the case of SpeedoGDOS 4. -wp <x0> <y0> [Window Position] Position of the upper-left point of the window (in GEM window mode). If this position is out of range, the window is placed at the default position. -wpc [Window Position: Centered] The window is centered (in GEM window mode). -ws [Window Screen] Whole screen mode. This is the default option when the MiNT cookie isn't present. This option should be avoided in a multitasking environment. -wu[+/-] [Window Update] In whole screen mode, the screen semaphore is always active. So the background processes (i.e. generally the accessories) can't display anything. -ww [Window Window] GEM window mode. This is the default option when the MiNT cookie is present. The numbers are in the decimal base, except if they are preceded by a '$', where they are in the hexadecimal base. For the "-u", "-vl", "-vr", "-vs" and "-wu" options, a following '-' means that the option is deselected; the possible '+' means that the option is selected. Instead of giving options in the command line, you can drag an option file, a rule file or a message file to TETRHEX icon. This operation respectively corresponds to the "-o", "-r" and "-s" options. Some options have opposite effects (ta/td, -vr+/-vr-, -vs+/-vs-, ...); only the last one in the string is taken into account. For instance, if the file TETRHEX.CFG contains the string "-ww -wpc -n 6", and the parameters are "-ws -vs", then the game will run in whole screen mode, with video synchronization and a hexagonal board whose edges have 6 hexagons. At the start, if the Lshift key is pressed, the timer A will be used (except if the "-td" option is given) instead of the timer D (useful if the serial port is used while TETRHEX is running). With a module player accessory or/and a message file, you can have modules played in the background; the timer D (default timer) must be chosen for TETRHEX. But on a Falcon 030 without an accelerator board, you'll get interferences each time the palette is changed, i.e. during the presentation and when the screen changes. You can use TETRHEX as an accessory. To do that, copy TETRHEX.PRG/GTP to the root folder of the boot partition (C:\ in general) and rename it into TETRHEX.ACC; copy also the rule files, TETRHEX.CFG and TETRHEX.LNG to the same place. Warning! there remain two big problems: a memory management problem (the computer may crash, in particular, don't start or quit an application while you're playing); another problem is the fact that TETRHEX uses a current path for the rule files, but under the TOS, the current path isn't local to the application, so that a saved score may cause an error. For the moment, when there is an error, you can't use the TETRHEX accessory any longer. This possibility to use TETRHEX as an accessory is new and may be improved later. N.B.: the rule file TETRHEX.RUL must be in the same folder as the application TETRHEX.PRG/GTP/ACC. 5. TETRHEX Game ¯¯¯¯¯¯¯¯¯¯¯¯ After starting TETRHEX, a window is immediately displayed if the game is to run in a GEM window. In whole screen mode, first TETRHEX tries to change the resolution if need be, except if the "-vr" option is selected, but may fail because of some AUTO programs (cf "Compatibility"); then a short presentation starts, while the background image is computed; hit any key to go to the main menu. At every time you can free the memory allocated for the background image by typing Ctrl-F, or, if you are in GEM window mode, by clicking anywhere with the right button of the mouse. In GEM window mode, you can quit whenever you want by closing the window (click on the closer). As of AES 4.1, you can iconify the window by clicking on the iconifier, or untop the window by clicking on the title bar. You can also move the window, but it will always remind entirely on the screen. Note: during a game, the window will only move between two pieces. If it is is untopped, the window is cleared and the string "-- PAUSE --" is displayed in the center: the window is said to be in pause mode (there are 2 kinds of pause mode: the window pause mode and the game pause mode; cf subsection "Game"). 5.1. Main Menu ¯¯¯¯¯¯¯¯¯ Each item of the main menu can be chosen either by hitting the corresponding key or by clicking on the item (possible only in GEM window mode). The list of the items is given below. The name of the rule file is displayed. The player name is also displayed if there is one. _ Item "help about TETRHEX" (Help key): this file is displayed. If nothing is displayed, you have to modify the file TETRHEX.LNG: add (or modify) the HELP line corresponding to the right language; after "HELP:", write the name of this file (path relative to the program + file name). _ Item "help about the rule" (Shift-Help key): help about the loaded rule. If nothing is displayed, this means that there is no help. _ Item "load a rule" (Undo key): a file selector is displayed so that you can choose a rule file. This item can be selected only if the resolution was not changed. _ Item "player name" (N key): this item allows the player to enter his name (cf subsection "Player Name"). This item is displayed only if the -u option is not active. _ Item "play" (Return key): cf subsection "Game". _ Item "high scores" (keys F1 to F20): the scores are displayed. Clicking on this item is equivalent to hitting the F1 key. Cf subsection "Highest Scores Display". _ Item "bottom" (Ctrl-Tab key): untop the window; this is equivalent to clicking on the title bar. This item is displayed only in GEM window mode. _ Item "quit" (Ctrl-Q key): quit TETRHEX; this is equivalent to closing the window. By typing Ctrl + one of the 4 top keys of the numeric pad ("(", ")", "/", "*") you change the size of the hexagonal board: the k-th key corresponds to edges having k+5 hexagons. 5.2. Help ¯¯¯¯ In both the general help and the help about a rule, the keys are: up and down arrows to do a 1-line scroll; with the Shift key (left or right), you go to the previous or the next page. If the Ctrl key is pressed, the move is multipled by 4. Hit the Clr-Home key to go to the beginning of the text; hit Shift-Clr-Home to go to the end of the text. Hit Esc to quit the help and to come back to the main menu. 5.3. Player Name ¯¯¯¯¯¯¯¯¯¯¯ The player name is used when a score is saved. It can be entered in 3 different ways: as an option at the start, from the main menu, or at the end of a game if the score is to be saved. If there's only one player, the first two ways are better. If there are several players, the third way is better. Only the last two ways will be considered here. A filled rectangle is displayed at the upper-left corner in order that you enter your name. You can enter only non-control characters. You can delete the last character with the Backspace key. Hit Esc to delete the whole name. With the right arrow, you can undelete the last deleted character (or possibly an old character which had the same position). With the up arrow, you can undelete all the deleted characters. Hit Return or Enter to valid. You can cancel this operation and return an empty name by typing Ctrl-C. Once the entry is validated (with Return or Enter) or canceled (with Ctrl-C), the mini-buffer used to undelete characters isn't cleared, except the first character, so that you can retrieve the last entered name at the next entry (after entering the first character). If the name is entered from the main menu and an empty name is returned, there won't be a player name: if a score is to be saved, the player will have to enter his name at the end of the game. If the name is entered at the end of a game, you can't validate an empty name (with Return or Enter). However the player can cancel the entry with Ctrl-C and the score won't be saved. 5.4. Game ¯¯¯¯ The rules depend on the rule file; read the corresponding help (Shift-Help from the main menu) to know them. But rules have common points, which are given here. The game is played on a hexagonal board whose edges have 6 to 9 hexagonal cells. Either a cell is empty or it contains a hexagon, which comes from an piece. A hexagon has one of the 6 following colors: red, green, blue, cyan, magenta, yellow. Moreover it may contain a pattern, whose meaning depends on the rule file. A piece contains 1 to 4 hexagons; the shape, the probability to appear, etc... depend on the rule file. Pieces appear at the top, in the center, and go down. Their speed also depends on the rule file. When a piece can't go down any longer, it enters the board, and some hexagons may be destroyed (possibly in several stages). When a hexagon is destroyed, the upper hexagons (in the same column) go down one cell. Generally the game ends when the next piece can't appear. Up to 8 numbers can be displayed in the right part of the window: the score, the level, etc... Their definition (text, number of digits, position, etc...) entirely depends on the rule file. The next piece can be displayed (radar) or not: this also depends on the rule file. When the next piece is displayed, it is centered at the top. In the game pause mode, the string "-- PAUSE --" is displayed in the upper-left part. In GEM window mode, if the window is untopped, you enter the window pause mode. When the window is topped back, you enter the game pause mode if the rule file accepts it (more precisely, a PAUS signal is sent, cf section "Rule Files"), in order to avoid that the game immediately continues. 5.5. Highest Scores Display ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯ The highest scores can be displayed in groups of 10. When you hit an Fn key (1 ≤ n ≤ 20, F(n+10) = Shift-Fn), the scores from the rank 10n-9 to the rank 10n are displayed. Hit Esc to come back to the main menu. Note 1: the scores depend on the size of the hexagonal board. To display the scores that correspond to a given size, first select this size from the main menu (cf subsection "Main Menu"). Note 2: although they can be saved, the scores from the rank 201 to the rank 255 can't be displayed in TETRHEX. 6. Rule Files ¯¯¯¯¯¯¯¯¯¯ One of the most interesting features of TETRHEX is the possibility of creating one's own rules (and modifying the existing rules). Hence TETRHEX allows to have various games and similar games with different levels of difficulty. The rules are stored in separate files (extension .RUL), called rule files. This section describes what these files contain, and their exact structure. 6.1. Data Occuring During a Game ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯ This section shortly describes the data that occurs in the game, i.e. the data contained in a rule file and those only used at run-time. It also describes the different phases of the game (which will be dealt with again in the other subsections), staying quite general. In its header, a rule file contains some data linked to the rule, but that don't change the way the game occurs, like the rule name, the fonts used for the rule, the colors, the number of scores. The rule file also contains a help (possibly in several languages), and at the end, the list of the highest scores for each size of the hexagonal board. A rule can be defined so that it runs for a fixed size of the board or for a variable size from 6 to 9 hexagons in an edge. A variable size is better, but a fixed size may be needed if some sizes aren't suitable. The rules have some common points, given in the subsection "Game", section "TETRHEX Game", which clearly don't have to be defined in a rule file. The following data remain to be determined: the shape of the piece, the patterns on the hexagons, the numbers that will be displayed, the signals (cf below) and the behavior during the game. One of the sections of the rule file contains all the possible shapes, each shape being identified in the part "behavior" by a number. Idem for the patterns. The definition of the numbers contains the text that will be displayed near the number, the position of this text relative to the position of the number, the size and the color of the text and the number, the number of digits of the number; the modification of these numbers, which is directly linked to the behavior, is described later. The behavior is described with the language RUL, specific to TETRHEX. It's an interpreted language dealing with expressions in the prefixed notation; however there are also some control commands (branches). An expression always represents a 32-bit signed integer. 2 additional data structures are used: an array of 64 variables and a stack of 32-bit integers whose size is given in the header of the rule file. Some of the variables have a special meaning (cf subsection "Special Variables"), the other may freely be used by the programmer; a special variable is associated with each displayed number. At the beginning of the game, all the variables are initialized to 0, and the stack is empty. In a game, one plays with an input peripherial (keyboard, mouse, joystick, ...), and according to what one does with the peripherial (action from the player), something or other occurs in the game (game action). In most games, there's almost no difference between the 2 kinds of actions: sometimes there is no difference at all; sometimes, if one plays with the keyboard, one can choose the keys; sometimes one can also choose between the keyboard, the mouse and the joystick... but this remains limited. In TETRHEX, an intermediate element called signal is used, so we have 2 conversions, which one can control. The data that come from the considered peripherials are first converted into signals by TETRHEX or by a message file. Then the signal is converted into a game action by the rule file. The user can intervene in the first conversion by giving a message file; if the conversion is performed by TETRHEX, then only the keyboard is considered, and the keys are defined in the rule file. The programmer of the rule file intervenes in the second conversion. A signal is internally (i.e. in RUL programs) identified by a nonzero byte, i.e. by an integer between 1 and 255, and externally (i.e. in message files) by a long word (32 bits). An action is identified by a signed 32-bit integer. The game is composed of several phases. There's an initialization phase (phase 0) at the very beginning of the game (after the variables have been initialized to 0); this phase is used in order to initialize some data: variables (particularly some displayed numbers), speed of the piece fall, etc... Before a new piece appears or when the radar is activated (if it hasn't been activated twice before another piece has appeared), a phase determining this piece (phase A) is called: the piece must be defined by setting some special variables (cf subsection "Special Variables"). During the piece fall or a pause, phase B is called to convert signals into actions. When a piece can't fall any longer, it sinks into the board and phase C is called; this phase allows to destroy hexagons (in one or several stages), and to update some data (score, level, ...). Note: data can also be updated in phase A. Finally, when the player has lost, a termination phase (phase S) is called: it returns the score of the player. There exist 2 other phases, linked to the window pause mode; these phases are described in subsection "Pause Modes". It is possible to branch a variable to the timer. This variable is decreased at each second (1 Hz frequency). 6.2. Actions ¯¯¯¯¯¯¯ There are 2 kinds of actions: simple actions, i.e. after which the piece isn't changed, that are identified by positive values, and actions that make directly go to phase C or phase S (abort), identified by negative values. When an action is not possible, it is not performed. The list of actions defined in this version of TETRHEX is given below. Some of the actions that make directly go to phase C store an additional integer into V[18] (as indicated in the list below). Note: in future versions of TETRHEX, there may be new actions. _ 0: no action. _ 1: a cell downwards. _ 2: a cell downwards to the left (i.e. 8 o'clock). _ 3: a cell downwards to the right (i.e. 4 o'clock). _ 4: left or direct rotation (counterclockwise). _ 5: right or indirect rotation (clockwise). _ 6: a cell to the left, at the same height. _ 7: a cell to the right, at the same height. _ 8: pause / end of pause. _ 9: radar on / off. _ 10: send a message (cf section "Messages", message $0206). _ -1: abort. Go to phase S (no phase C). _ -2: drop: the piece is dropped. The number of performed DOWNs is stored into V[18], which corresponds to the number of covered cells + 1, since the last DOWN is used to stop the piece. _ -3: explosion: all the hexagons that are on the hexagonal board are destroyed. The number of destroyed hexagons (those of the current piece included) is stored into V[18]. _ -4: the current piece is destroyed. Note: when a piece is at the top of the board, actions 6 and 7 behave like actions 2 and 3. 6.3. Signals ¯¯¯¯¯¯¯ The signals are entirely defined in the rule file. However there are standard signals, you'd better respect, since they may be used in message files. The rule file also gives the mapping internal identifiers / external identifiers and the default keys, a key being identified by its position on the keyboard (scancode) and the state of the special keys. The list of the standard signals, defined by the external identifiers, but ordered according to the internal identifiers, is given below. You should take the same internal identifiers, even though this isn't important for the moment. The keys chosen in the rule files provided with TETRHEX (it is advised to take the same keys) and the corresponding actions are also given. It is important to perform the same actions. Note: here the term "action" is different from the one considered in the previous section; however there's a direct correspondence for most actions. $01 : DOWN : A.............. a cell downwards (action 1). $02 : LFDN : Insert......... a cell downwards to the left (action 2). $03 : RGDN : Clr-Home....... a cell downwards to the right (action 3). $04 : ROTL : Down arrow..... left rotation (action 4). $05 : ROTR : Up arrow....... right rotation (action 5). $06 : LEFT : <--............ a cell to the left (action 6). $07 : RGHT : -->............ a cell to the right (action 7). $08 : DROP : Space bar...... drop (action -2). $09 : STOP : Ctrl-Esc....... abort (action -1). $0A : PAUS : Undo........... pause mode (action 8). $0B : CONT : Return......... end of pause mode (action 8). $0C : NEXT : + (numpad)..... next level (code + action 0). $0D : PREV : - (numpad)..... previous level (code + action 0). $0E : RDAR : Help........... radar on / off (action 9). Note: depending on the rule, only an action 0 may be associated with some signals. For instance, the previous level or the pause mode may be forbidden... 6.4. Game Phases ¯¯¯¯¯¯¯¯¯¯¯ The game is composed of 7 phases, each phase corresponding to a subroutine written in RUL: _ Phase 0: initialization phase, called at the very beginning of the game. _ Phase A: the next piece is determined by storing values into some of the variables V[0] to V[8] (cf subsection "Special Variables"). This phase may be called while there is already a moving piece on the board, due to the activation of the radar; in this case, variables V[0] to V[8] are saved by TETRHEX before the call, and restored after the call (for they may still be useful): the programmer of the rule file don't need to worry about that. _ Phase B: signals are converted into actions. The internal signal identifier is in V[9]. The subroutine must return the action identifier. Note: data about the current piece can be known with command $7C (cf subsection "RUL Language"). _ Phase C: in this phase, some hexagons can be destroyed; the score is generally updated. V[9] contains the identifier of the last action: useful if some actions (among the negative ones) yield points... V[18] may contain an additional integer (cf subsection "Actions"). _ Phase P (Pause): beginning of the window pause mode (cf subsection "Pause Modes"). _ Phase Q (Quit pause): end of the window pause mode (cf subsection "Pause Modes"). _ Phase S (Score): termination phase. The final score must be returned. 6.5. Special Variables ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯ V[0] contains the identifier of the current shape (from 1 to 255). Let h be the number of hexagons of this shape. For 1 ≤ k ≤ h, V[k] contains the color of the k-th hexagon (cf subsection "Color Codes"), and V[k+4] contains the pattern identifier of the k-th hexagon (from 1 to 255). For h < k ≤ 4, V[k] and V[k+4] may be freely used, but they may be altered in phase A by TETRHEX. The variables defining the piece must be assigned in phase A, and mustn't be modified in phases B, C, P and Q. V[9] contains the internal signal identifier (from 1 to 255) in phase B, and the action identifier in phase C. This variable may be modified by the routines RUL. Let n be the number of displayed numbers to the right of the board. For 1 ≤ k ≤ n, V[k+9] contains the k-th displayed value. If the value is negative, then 0 is displayed; if it is higher than M(k) = 10^d(k) - 1, where d(k) is the maximum number of displayed digits of the k-th number, then M(k) is displayed. For n < k ≤ 8, V[k] may be freely used. V[18] may contain an additonal integer in phase C. For k > 18, V[k] may be freely used. 6.6. Color Codes ¯¯¯¯¯¯¯¯¯¯¯ The hexagons that compose the pieces can have one of the 6 different colors, coded from 1 to 6: _ 1 (001): blue. _ 2 (010): green. _ 3 (011): cyan = green + blue. _ 4 (100): red. _ 5 (101): magenta = red + blue. _ 6 (110): yellow = red + green. 6.7. Pause Modes ¯¯¯¯¯¯¯¯¯¯¯ There are 2 kinds of pauses: the game pause mode and the window pause mode. Game pause mode: this pause mode is activated by the action +8 (normally when a PAUS signal is sent), and it is desactivated by the action +8 again. The other actions may be activated, but except the action +8 (end of pause) and the action -1 (abort), they have no effect. Warning! even in game pause mode, any signal may be received; the programmer must test whether he's in pause mode or not before performing operations, like a variable modification. Window pause mode: this pause mode is activated when the window is in the background (in GEM window mode). Contrary to the game pause mode, here this pause mode is forced: one can't avoid it. At this moment, phase P is called; in this phase, the possible variable branched to the timer may be unbranched (not compulsory). Then the game is totally stopped (no signal can be received), but the timer is still active. When the window comes back to the foreground, this pause mode is quitted, except in some particular cases (e.g. insufficient memory); if there's any problem, an alert message is displayed. Phase Q is called; if a variable had been unbranched from the timer, it may be branched again. Then the PAUS signal is sent if it exists, so that the game doesn't go on immediately. Warning! the window pause mode may be activated at any moment. 6.8. Rule File Structure ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯ Note: the order of definition of the patterns, the shapes, the signals and the numbers is important, the identifier associated with the considered element is automatically assigned by the position in the list. _ Header. Addresses are relative to the beginning of the file. Colors have the format (0, R, G, B): the first byte is zero, and the next 3 bytes contain the values of the red, green and blue components between 0 and 255. . 1 long word: $52554C33 ("RUL3"). This long word indicates that it is a rule file, version 3. . 1 long word: color of "-- PAUSE --", in the game pause mode. . 1 long word: color of "game over". . 1 long word: color of "Your name:" and the name (when the player is asked to enter his name). . 1 long word: color of the rule name. . 1 word: default height of the rule name. . 24 bytes: rule name followed by a zero byte. . 1 word: identifier of the outline font used to display the rule name, or 0 if the font is chosen by the user (i.e. determined by the option -fn). . 1 word: identifier of the outline font used to display the names of the displayed numbers during the game, or 0 if the font is chosen by the user (i.e. determined by the option -fg). . 1 byte: number of patterns (between 1 and 255). . 1 byte: number of shapes (between 1 and 255). . 1 byte: number of signals (between 1 and 255). . 1 byte: number n of cells in an edge of the hexagonal board (between 6 and 9), or 0 if it is variable. . 1 byte: number of scores (between 0 and 255) for n = 6. . 1 byte: number of scores (between 0 and 255) for n = 7. . 1 byte: number of scores (between 0 and 255) for n = 8. . 1 byte: number of scores (between 0 and 255) for n = 9. . 1 byte: maximum number of scores (between 0 and 255) for n = 6. . 1 byte: maximum number of scores (between 0 and 255) for n = 7. . 1 byte: maximum number of scores (between 0 and 255) for n = 8. . 1 byte: maximum number of scores (between 0 and 255) for n = 9. . 1 long word: size of the stack. . 1 long word: address of the definition of the signals. . 1 long word: address of the definition of the displayed numbers. . 1 long word: address of phase 0. . 1 long word: address of phase A. . 1 long word: address of phase B. . 1 long word: address of phase C. . 1 long word: address of phase P. . 1 long word: address of phase Q. . 1 long word: address of phase S. . 1 long word: address of the help text. 0 if there's no help text. . 1 long word: address of the highest scores (points to the end of the file if there's no score). _ Definition of the patterns. Each hexagon is composed of 288 pixels having an intensity between 0 and 7 (0: black, 4: background color, 7: highest intensity). An array of 288 3-bit numbers is associated with each pattern, which takes 108 bytes. The patterns are stored the one after the other. _ Definition of the shapes. This definition doesn't depend on the one of the patterns. The pieces must be connected. A configuration of the shape is defined so that it is relative to a reference hexagon (which doesn't necessarily belong to the piece), whose absolute position will be given in the game. Such a configuration is identified by a 4-byte array (long word), so that the k-th byte represents the relative position of the k-th hexagon to the reference hexagon; if the shape has fewer than 4 hexagons, the other bytes must be zero. The byte identifying the relative position of a hexagon is defined as follows: the byte is 0 if it's the reference hexagon; its value is between 1 and 6 if it is adjacent to the reference hexagon: 1 if it is below, then one turns counterclock- wise; its value is between 7 and 18 if its distance to the reference hexagon is 2: 7 if it is below, then one turns counterclockwise. . For each shape: . 1 byte: number n of hexagons (between 1 and 4). . 1 byte: 0 if the shape can't turn, negative if the shape turns around the reference hexagon, positive if the shape turns in another way. In the last case, this byte contains the number of different positions, between 1 and 6 (note: normally different from 1). . 1 word: offset of the list of the positions for this shape if the previous byte is positive (nonzero); otherwise, 0. . 4 bytes: initial relative positions of the hexagons. . Possible list of the relative positions (cf above), in any order, a list of positions being an array of arrays of 4 bytes. _ Definition of the signals (standard signals included). For each signal: . 1 long word: external signal identifier, generally 4 letters. This long word must be strictly positive. . 1 word: scancode of the default key corresponding to the signal (the most significant byte contains the state of the special keys). . 1 word: 0 (reserved). _ Definition of the displayed numbers. Colors have the format (0, R, G, B). For each number, a text ("Score", "Level", etc...) and a value are displayed. If the value is negative, 0 is displayed. There is a minimum number of displayed digits; some non-significant 0's are possibly displayed. There is also a maximum number of displayed digits; if the value is too high, then the highest value that can be displayed is displayed (digits = 9). Note: the numbers are vertically displayed, in the same order they have been defined. . 1 word: number n (between 0 and 8) of displayed numbers. . Array of n words: addresses of the definitions of the displayed numbers, relative to the address of the array. . For each number: . 1 byte: maximum number of displayed digits (between 1 and 8). . 1 byte: minimum number of displayed digits (between 1 and 8). . 1 byte: text height in pixels (between 16 and 127). . 1 byte: number height in pixels (between 16 and 127). . 1 long word: color of the text. . 1 long word: color of the non-significant 0's. . 1 long word: color of the significant digits. . 1 byte: position of the text, relative to the position of the number: 0 if the text must be displayed above the number, 1 if it must be displayed to the left, -1 if it must be displayed to the right. . For each language (there must be at least one language): . 1 byte: length n (between 1 and 127) of the text. . 1 byte: language code. . n bytes: text. . 1 byte: 0, indicating there's no language any more. _ Rule: RUL subroutines. The 7 phases may be interlaced. Cf subsection "RUL Language". _ Help text (optional). . For each language: . 1 long word: offset of the next language (or the long word that indicates the end of this part). . 1 byte: language code. . 1 byte: underline character (0 if there's no such character). Cf below. . 1 byte (reserved). Its value isn't important in this version; but for the compatibility of the rule file with a later version of TETRHEX, its value must be 0. A nonzero value could indicate additional data. . Text in the language given above, followed by a zero byte. The characters must have an ASCII code ≥ 32, except the ends of line (CR/LF). The text can be directly sent to the standard output; thus it must already be formatted. It can also be displayed in TETRHEX window (item "Help about TETRHEX" in the main menu; in this case, the text width (i.e. the maximum width of a line of text) will be seeked, and the lines having this width will be justified. The advised width is 76 characters. Due to this justification, the lines won't be displayed without a modification: there exist 2 characters that have a special behavior: the space and the underline character (defined before the text). A sequence of spaces at the beginning of a line yields an indentation: the proportion of the number of spaces to the text width in characters is equal to the proportion of the indentation width to the text width in pixels; idem for a sequence of spaces at the end of a justified line. A sequence of spaces inside a line is replaced with a unique space. The lines composed of only spaces and underline characters, called underline lines, are not displayed: they are taken into account for the display of the previous line; a sequence of underline characters in an underline line underlines the above sequence of characters except the extreme spaces. If the line doesn't end with an underline character, then an empty line is displayed below (it's the case of the underline lines ending with a space, the lines only composed of spaces and the empty lines). N.B.: each line must end with a CR/LF, included the last one. One mustn't have several consecutive true underline lines ("true" means that the line contains at least an underline character), otherwise the computer may bombs. . 1 long word: 0. _ Array of the highest scores (possibly empty). First one has the scores for 6 hexagons, then for 7, 8 and 9 hexagons. Each score takes 32 bytes: . 24 bytes: player name + zero byte. . 1 long word: score (in hexadecimal). . 1 long word: date and time (XBIOS format). 6.9. RUL Langage ¯¯¯¯¯¯¯¯¯¯¯ RUL is a language of 8-bit codes composing expressions in prefix notation. An expression always represents a 32-bit signed integer. There are also transparent control instructions (branches), i.e. they only modify the program counter: they don't modify the result of the last expression (in particular for a return from function, cf below), moreover they don't form an expression, i.e. they don't modify the expression stack. The expressions are evaluated as soon as they are read. As a consequence, when an operation has several operands, the first operands are evaluated before the last ones. The first expression is denoted "x", the second one is denoted "y", and the third one is denoted "z" (character enclosed with angle brackets), except when there's an opposite indication. Some expressions return a boolean, encoded by a 32-bit integer as follows: "false" is encoded by 0, and "true" is encoded by -1. This encoding has been chosen so that the bitwise instructions AND, OR and NOT are equivalent to the boolean instructions. Each cell of the hexagonal board is identified by a nonzero 32-bit integer. The integer 0 identifies the non-existing cells. The other integers mustn't be used in commands having a cell identifier as an argument. There's another means of identifying a cell: with a couple (column, height). Let n be the number of cells in an edge of the board, the columns are numbered from -(n-1) to (n-1); the height is the number of cells that are below (in the same column). An array of 8 bits called marks, initialized to 0 at the beginning of the game, is associated with each cell of the board; when the bit b has the value 1, one says that the cell has the mark b. The offsets (for the branches) are 16-bit words, except for the 8-bit conditional branch. The branch address is relative to the address of the offset. Warning! when a command whose operands have bad values is performed (like a division by 0), the result is undetermined or the computer bombs. When this means something, the operations are performed modulo 2^32 (for instance the addition). Here is the meaning of the codes: _ $80 to $FF: constant x - $C0 (from -64 to 63). _ $00 to $3F: variable V[x]. _ $40 <expr> <expr>: addition x + y. _ $41 <expr> <expr>: subtraction x - y. _ $42 <expr> <expr>: multiplication x * y. _ $43 <expr> <expr>: integer division x / y. The quotient is defined as follows: the absolute value of the quotient is the floor of the absolute value of the real quotient. _ $44 <expr> <expr>: left shift x << y. The number of shifts must be between 0 and 63. _ $45 <expr> <expr>: right shift x << y. The number of shifts must be between 0 and 63. _ $46 <expr> <byte>: 8-bit relative branch if the result of the expression is different from zero (transparent instruction). _ $47 <expr> <expr>: modulo. One must have y > 0. The returned value is the integer congruent to x modulo y, between 0 and y-1. Warning! this operation is different from the C modulo (%) for x < 0. _ $48 <word>: 16-bit signed constant. _ $49 <long word>: 32-bit signed constant. _ $4A <expr> <expr>: x == y. _ $4B <expr> <expr>: x != y. _ $4C <expr> <expr>: x < y. _ $4D <expr> <expr>: x > y. _ $4E <expr> <expr>: x <= y. _ $4F <expr> <expr>: x >= y. _ $50 <offset>: function call, i.e. branch to a subroutine that returns a value. _ $51: return from function. The value of the function is the value of the last expression. _ $52 <offset>: relative branch (transparent instruction). _ $53 <expr> <offset>: branch if the result of the expression is different from zero (transparent instruction). _ $54 <expr>: bitwise NOT. _ $55 <expr> <expr>: bitwise AND. _ $56 <expr> <expr>: bitwise OR. _ $57 <expr> <expr>: bitwise XOR. _ $58: 16-bit signed random value. _ $59: 32-bit signed random value. _ $5A <expr>: V[x] (x must be between 0 and 63). _ $5B <expr> <expr>: affectation. The concerned variable and the operation that will be performed are given by the value of the first expression: if 0 ≤ x ≤ 63, then V[x] = y; if -64 ≤ x ≤ -1, then V[x+64] += y; if 64 ≤ x ≤ 127, then V[x-64] -= y. The returned value is the new value of the variable. _ $5C <expr>: data about the next piece. If the radar isn't active, 0 is always returned. In the opposite case, if 0 ≤ x ≤ 8, the returned value is the value of the variable V[x] after the last call of phase A, i.e. V[x] when the next piece appears, and if x < 0 or x > 8, the returned value is -1. Thus an operand like -1 allows to test whether the radar is active or not. _ $5D: true iff the game mode pause is active. _ $5E <expr>: if x ≥ 0, the variable V[x] is branched to the timer if it is not already branched (the variable will be decreased at each second); if another variable was branched to the timer, it is automatically unbranched. If x < 0, the variable branched to the timer (if there is one) is unbranched. The returned value is x. _ $5F <expr>: approximate time between two successive descents of the piece, in milliseconds, between 1 and 8191. The returned value is x. _ $60 <expr> <byte n> <word>^n: value of an element in an array of 16-bit constants. This instruction evaluates the expression, reads the byte n, takes the value modulo n, and returns the corresponding element of the array extended to 32 bits, the indices being between 0 and n-1. _ $61 <expr> <byte n> <long word>^n: idem, but for an array of 32-bit constants. _ $62 <expr> <byte n> <offset>^n: kind of CASE; relative branch depending on the value of the expression. _ $63 <expr>: push the value of the expression, which is returned. _ $64: top of stack (the value isn't pulled). _ $65: pull a value, which is returned. _ $66 <expr>: absolute value. _ $67 <expr>: square. The argument must be a 16-bit word. _ $68: 15-bit random value (positive or zero integer). _ $69: 31-bit random value (positive or zero integer). _ $6A <expr> <expr>: min(x,y). _ $6B <expr> <expr>: max(x,y). _ $6C <expr> <expr> <expr>: double comparision. If y ≤ x ≤ z, then 0 is returned; if x < y ≤ z, then -1 is returned; if y ≤ z < x, then 1 is returned. If y > z, the result is undetermined. _ $6D: send a message (cf section "Messages", message $0207). If data need to be transmitted, the stack has to be used, and the data will have to be pulled. The result is the value returned by the message file. _ $6E <x> <m>: destruction of the hexagons in the cells having the mark m. If m < 0, all the hexagons are destroyed. One must always have m ≤ 7. Note: the first expression is useless; it's here just to have the same format as the command $6F. _ $6F <x> <m>: destruction with loop of the hexagons in the cells having the mark m, where 0 ≤ m ≤ 7, i.e. if at least a hexagon is destroyed, then this instruction is evaluated again. The result of the first expression is ignored, but this expression is to set the marks m. _ $70: number of cells in an edge of the hexagonal board (between 6 and 9). _ $71 <c> <h>: identifier of the cell being in column c and having height h. If the cell isn't in the board (non-existing cell), then 0 is returned. _ $72 <x>: height of the cell x (undetermined if x = 0). _ $73 <x>: column of the cell x (undetermined if x = 0). Note: the next 4 commands allow to perform operations on sets of cells (recursivity is allowed, what is useful for instance to search for connected componants or for other kinds of route). These operations always return the value of the expression for the last element, that is always the non-existing cell (0). For each cell of the set (the non-existing cell included), the current cell is stored into V[n], and the expression e is evaluated. For each case below, the set is given without the non-existing cell. _ $74 <n> <x> <e>: set = all cells adjacent to cell x and containing a hexagon. _ $75 <n> <x> <e>: set = all existing cells adjacent to cell x. _ $76 <n> <e>: set = all cells containing a hexagon. _ $77 <n> <e>: set = all existing cells. _ $78 <x> <m>: true iff cell x has the mark m (m must be between 0 and 7). _ $79 <x> <m>: if 0 ≤ m ≤ 15, the mark (m modulo 8) of cell x is inverted; if m < 0, all the marks of cell x are inverted. If m ≤ 7, the value x is returned; if 8 ≤ m ≤ 15, a boolean indicating the state of the mark m - 8 is returned. _ $7A <x> <m>: idem, but the mark is cleared instead of being inverted (bit = 0). _ $7B <x> <m>: idem, but the mark is set instead of being inverted (bit = 1). _ $7C <n>: if n < 0, number of hexagons (between 1 and 4) in the last (or current) piece; if n = 0, identifier of the cell containing the reference hexagon of the last (or current) piece; if n > 0, identifier of the cell containing the n-th hexagon of the last (or current) piece; warning! n mustn't be higher than the number of hexagons of the piece. _ $7D <x>: identifier of the pattern on the hexagon in cell x if there is any, 0 if the cell is empty, -1 if the cell doesn't exist (0). The test "> 0" allows to know whether there is a hexagon in the cell, the test "!= 0" allows to know whether the cell exists and is empty. _ $7E <x>: idem, for the color of the hexagon instead of the pattern. _ $7F <x> <d>: identifier of a cell adjacent to cell x if x exists, non-existing cell if x is the non-existing cell; d indicates the direction. One considers the value of d modulo 6 (for there are 6 possible directions). $7F <x> 0: adjacent cell downwards, $7F <x> 1: downwards to the right, $7F <x> 2: upwards to the right, $7F <x> 3: upwards, $7F <x> 4: upwards to the left, $7F <x> 5: downwards to the left. 7. Messages ¯¯¯¯¯¯¯¯ N.B.: this section is useful only to those who have a registered version, since in the unregistered version one can't send messages. The system of messages allows TETRHEX to communicate with external routines, which can communicate with other processes. Originally messages aimed to send and receive AES messages; but one can do much more. At the start, TETRHEX is given external routines, grouped in files called "message files". A message file consists of a routine composed of several subroutines. TETRHEX may be given several message files; they form a chain, the last loaded file (i.e. the last file in the option string) has the highest priority (cf below). At some moments, TETRHEX sends a message (type + data), which corresponds to a routine call, a subroutine is chosen according to the message type, and a result is returned; the send/transmit protocol is described below. Since there must be at least one routine, in particular when the user don't give any message file, TETRHEX contains an internal message file called terminal file, which always has the least priority. Send/transmit protocol (in assembly 680x0): TETRHEX or a routine of a message file may send a message as follows: D0.W contains the message type, and A0 is a pointer to a structure, composed of a long word that is the address of the routine of the message file that has the highest priority (address of the file + 4) and other possible data depending on the message type. The routine returns a result in D0.L, whose meaning depends on the message type; the other registers aren't altered. When a routine of a message file receives a message, it processes the message if possible (according to the message type), otherwise it transmits the message to the next message file; even if the message has been processed, it may be transmitted to the next message file (this depends on the process). N.B.: the processing routine mustn't modify registers D1 to D7 and A0 to A7; hence the modified registers must be saved at the beginning and restored at the end. The transmission is performed as follows: D0.W, A0 and (A0).L must have the values given at the call; the address of the routine of the next file is stored at the address of the current file, i.e. at the address of the current routine - 4; the address of the routine to call being known, either a branch or a call to a subroutine (to be able to modify the result) is performed. The terminal file always returns 0 and doesn't do anything else; thus the process of a message should return 0 if and only if nothing has been done. Types of the currently defined messages: _ $0000: unspecified (depends on the message file). _ $0001: initialization. This message is sent just after appl_init. 4(A0).W contains the identifier of application TETRHEX (used to send AES messages to TETRHEX). 6(A0).B: error display flag (0 if the "-e" option isn't active, -1 if it is active); the message file may send characters to the standard output file only if this flag is active. If no error occurs, this message must be transmitted to the next message file (a zero value will be returned by the terminal file). Otherwise the initialization must be interrupted and a nonzero value must be returned; TETRHEX ends and returns the less significant word as the return code. _ $0002: end of program. Message sent just before appl_exit. It must always be transmitted to the next message file. _ $0003: beginning of the presentation. This message is never sent if there is no presentation, i.e. in GEM window mode. _ $0004: menu display; the background image isn't displayed yet. If a nonzero number is returned, the background image is immediately freed, which allows to change it (cf message $0006). _ $0005: menu displayed (wait for an event). _ $0006: request for the computation of the background image. If the result is 0, the image will be computed by TETRHEX. In the opposite case, the image is computed by the message file and the result is the address of the image. The image, on which the hexagonal board will be displayed (by TETRHEX), is composed of 7 non-interlaced planes (VDI format) 624 * 416, the pixel values being between 0 and 95, i.e. the most significant two bits aren't both 1. The palette (96 long words) is stored just after the image. N.B.: the memory block containing the new background image must be reserved by the routine of the message file, but it will be freed only by TETRHEX, either automatically (if there isn't much memory left), or due to the user request (Ctrl-F or right click), or with a message (cf message $0004). _ $0007: new loaded rule file. 4(A0).L contains the address of the rule file. This message is sent by TETRHEX just after a rule file has been loaded. It is the case for the first loaded rule file, and the message is sent between $0001/$0003 and $0004. _ $0008: help about TETRHEX. This message is sent only if the help actually exists. _ $0009: help about the rule file. This message is sent only if the help actually exists. _ $000A: entry of the player name. _ $000B: beginning of the game. Message sent before phase 0 of the rule has been evaluated. _ $000C: display of the highest scores. _ $0100: window pause mode. Message sent after the possible evaluation of phase P of the rule. _ $0101: end of window pause mode. Message sent before the possible evaluation of phase Q of the rule. _ $0200: unspecified (depends on the message file). Message linked to the game. _ $0201: beginning of the game. 4(A0).L: game stack pointer. 8(A0).L: pointer to the game variables. 12(A0).L: pointer to the rule file. Message sent after the evaluation of phase 0 of the rule. _ $0202: game over. 4(A0).L: score. Message sent after the evaluation of phase S of the rule and before the memory reserved for the game (variables, stack, ...) has been freed. _ $0203: next piece. The data about this piece aren't stored into the structure (A0) because they can be read through the game variables. This message is sent before the piece has been displayed. _ $0204: a piece has just been displayed. _ $0205: action. 4(A0).L: action identifier. This message is sent just after phase B of the rule has been evaluated and the numbers have been updated (display), and before the action is executed. _ $0206: message sent by the action +10. 4(A0).L: game stack pointer. The data have been stored into the game stack. The top of the stack contains the number of pushed data (N.B.: this long word isn't included in the data); these data will be pulled by TETRHEX after the call. _ $0207: message sent by the RUL interpreter (cf command $6D). 4(A0).L contains the game stack pointer. _ $0208: message sent just before phase A of the game. If the result isn't 0, phase A won't be executed and message $0209 won't be sent. _ $0209: message sent just after phase A of the game. _ $0300: read a signal. 4(A0).L: code of the key (state of the special keys + scancode + ASCII code) if a key has been hit, otherwise 0. If no signal is detected and if the key isn't taken into account by the message file, 0 must be returned (TETRHEX will take the key into account and will transmit the possible signal to phase B of the rule file). If no signal is detected and if the key doesn't correspond to any signal or mustn't be taken into account, a negative value must be returned. If a signal is detected (last case), due to the key or for any other reason, the external identifier of the signal must be returned. _ $0301: emulation of a function key. A value between 1 and 20 is returned to emulate the corresponding function key. Otherwise 0 must be returned. _ $0302: emulation of an event in the main menu. The returned value n has the following meaning: 0: no event, 1: help about TETRHEX, 2: help about the rule, 3: load a rule, 4: player name, 5: play, 6: highest scores, 7: background, 8: quit, 16 to 19: board with n-10 cells in an edge, -1 to -20: highest scores (function key F(-n)). _ $0303: emulation of an event while the player enters his name. Meaning of the returned value n: 0: no event, 1 to 255: character, which can be displayed or not (3: ctrl-C, 8: backspace, 13: return, 27: escape), -1: right arrow, -2: up arrow. _ $0304: emulation of the Esc key at the end of the game. The returned value must be nonzero to come back to the main menu. _ $0400: AES message of type ≥ 128 received by TETRHEX. 4(A0).L: pointer to the message buffer (cf evnt_mesag). _ $0401: hit key that isn't taken into account by TETRHEX, in the main menu. 4(A0).W: state of the special keys (cf evnt_button). 6(A0).W: code of the key, i.e. scancode of the key in the most significant byte and ASCII code in the least significant byte (cf evnt_keybd). Note 1: in the game, the stack is descending, i.e. when one pushes an integer, 4 is subtracted from the stack pointer (for the elements have 32 bits). The stack pointer points to the top of the stack, i.e. to the last pushed integer when the stack isn't empty. The initial stack pointer is given by message $0201; at this moment, the stack is empty. Note 2: the messages of type $03xx allow to perform background computations (with a non-preemptive operating system). 8. Technical Notes ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯ This section is aimed at those who know the TOS/GEM quite well, in particular the programmers. 8.1. Program Flags ¯¯¯¯¯¯¯¯¯¯¯¯¯ Note: since the assembler I use can't set the program flags (PRGFLAGS) as I want, I may forget to modify them in some versions of TETRHEX. These flags are stored at the offset 0x16 of the program TETRHEX.GTP/PRG. You can modify the bits 0 to 2 with Dieter Fiebelkorn's CPX FileInfo. _ Bit 0 (fastload): you'd better set it to speed up the loading. _ Bit 1 (TT-RAM prg) and 2 (TT-RAM mem): you'd better set them. _ Bit 3: unused (clear it). _ Bits 4 and 5: you'd better clear them. _ Bits 6 to 15: unused (clear them). 8.2. Error Codes ¯¯¯¯¯¯¯¯¯¯¯ The list of the values that can be returned by TETRHEX is given below. When an error occurs, it is indicated by an alert box in addition to the returned code, if the AES has been initialized. _ 0: no error. _ 1: insufficient memory. _ 2: the resolution can't be changed. _ 3: bad processor (a 68020 at least is necessary). _ 4: a workstation can't be opened. _ 5: a window can't be created. _ 6: font problem. _ 7: rule file not found. _ 8: bad rule file format. _ 9: internal error. _ 10: bad option string. _ 11: bad language file format. _ 12: help file not found. _ 13: bad help format. _ 14: stack overflow. _ -1: system error. 8.3. Moving the Window ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯ With TOS 4, if one of the 2 lines at the bottom or one of the 2 columns at the right of a window (used for the 3D effect) is out of the screen and if the window is moved to the inside of the screen, then a redraw message is always sent (GEM bug). In order to avoid this redraw, it is forbidden to these 2 lines and 2 columns to get out of the screen; but as they aren't a part of the window for the AES, one must take them into account in the computations. 8.4. Palette Modification ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯ In whole screen mode, the palette is modified many times by TETRHEX, but it is restored at the end. But in GEM window mode, a problem arises, since several applications (or accessories) may use different palettes. The best would be to select the palette of the application that has the foreground window, i.e. when a window gets to the foreground, the palette is changed at the same time; but the AES can't do that. Thus it's TETRHEX that changes the palette when the window gets to the foreground; when TETRHEX's window is untopped, the palette isn't modified by TETRHEX, since it can't know the new palette: it's the application having the topped window that must change the palette. If all the applications using a 256-color palette behave like this, problems shouldn't arise in general (but the window mustn't be untopped before the palette is changed). Note: the first 16 colors are never modified by TETRHEX (in GEM window mode) and mustn't be modified by any other application. Obviously, when TETRHEX is quitted, the old palette isn't restored. 9. Limitations of the Unregistered Version ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯ The unregistered version has the following limitations: _ The rule can't be changed (the Undo key is disabled). _ The board size can't be changed. _ The scores are not saved. _ A game ends after about 5 minutes. _ After 10 games, TETRHEX automatically ends. _ Message files can't be used. The rule and the board size must be chosen at the start (cf section "Starting and Configuring TETRHEX"). If you get registered, you'll receive a version without any limitation, but also some message files with the sources, the source of a mini-compiler allowing to create rule files much more easily, and the documentation about the format (ASCII). You'll also receive the source of the rule files that are provided with TETRHEX, so that you can modify them and that they are used as examples. Vincent Lefèvre