@database "MahjonggTiles.guide" @author "Geoffrey Whaite & Przemyslaw 'SENSEI' Gruchala" @remark $VER: MahjonggTiles Guide 1.2 (22.08.2001) @remark "Created with GoldED 4.7.3 (23.6.97) and CygnusED 3.5" @wordwrap @index INDEX @node MAIN "MahjonggTiles" @{u}MahjonggTiles V1.2 @{uu} @{u}27 August 2001 @{uu} @{" Introduction " link INTRODUCTION} @{" Requirements " link REQUIREMENTS} @{" Copyright and Distribution " link COPYRIGHT} @{" ToolTypes " link TOOLTYPES} @{u}Playing MahjonggTiles @{uu} @{" Starting a Game " link STARTING} @{" Making Moves " link MOVING} @{" Undoing and Redoing Moves " link UNDOING} @{" Getting Help and Hints " link GETTINGHELP} @{" Timed Games " link TIMEDGAMES} @{u}Layouts@{uu} @{" About Layouts " link LAYOUTS} @{" Selecting a Layout " link SELECTINGLAYOUTS} @{" Showing the Best Times for a Layout " link BESTTIMES} @{" Creating and Editing Layouts " link LAYOUTEDIT} @{u}Tilesets@{uu} @{" About Tilesets " link TILESETS} @{" Selecting a Tileset " link SELECTINGTILESETS} @{" Showing the Current Tileset " link SHOWINGTILESETS} @{" Creating Custom Tilesets " link CREATINGTILESETS} * @{" Tileset Descriptor File " link DESCRIPTORFILE} * @{" The Main Image File " link MAINIMAGEFILE} * @{" Extension Image Files " link EXTIMAGEFILE} @{u}Configuring MahjonggTiles @{uu} @{" The Settings Window " link SETTINGSWIN} * @{" Tileset Visuals Page " link TSVISUALPAGE} * @{" Backgrounds Page " link BACKGROUNDSPAGE} * @{" Game Play Page " link GAMEPLAYPAGE} * @{" GUI Images Page " link GUIIMAGESPAGE} * @{" Command Keys Page " link CMDKEYSPAGE} @{u}Etc. @{uu} @{" Credits " link CREDITS} * @{" MUI " link MUI} @{" Revision History " link HISTORY} @endnode @node INDEX "Index" INDEX @endnode @node INTRODUCTION "Introduction to MahjonggTiles" @{u}Introduction to MahjonggTiles@{uu} MahjonggTiles is a solitaire game in which the aim is to remove all the Mahjongg tiles from a layout by matching pairs of free tiles. A Mahjongg tileset consists of 144 tiles grouped into 36 tile quartets. In general each tile of a quartet has the same tile face imagery, however there are exceptions such as the four seasons or the four flowers in Mahjongg tileset. You can view the entire tileset at any time by selecting the "Show Current Tileset" menu item, this is in the "Tileset" submenu of the "Game" menu. Viewing the tileset like this allows you to see which tile face imagery matches which others. A MahjonggTiles layout is made up of a number of layers of tiles stacked on top of each other. Each layer is a rectangular grid in which tiles are placed, the width/height of the grid cells is half the width/height of the tiles. Tiles placed on a layer cannot overlap. A tile in a layout is considered to be free if there are no tile on the layer above it that cover any part of it and there are no tiles immediately adjacent to either its left or right side. MahjonggTiles is played by selecting pairs of matching free tiles for removal. When a tile pair is removed it will possibly expose more tiles making them free and available for removal. The player continues to remove free tile pairs until all the tiles are removed from the layout and wins the game or until there are no more free matching tile pairs in which case the player looses the game. The player can undo/redo moves to make corrections, the undo scope covers all the moves made in the game. MahjonggTiles is highly configurable and includes options that affect the visual appearance of the game as well as game play. It also supports multiple tilesets and layouts and comes with a companion layout editor for creating and modifying your own layouts. MahjonggTiles is more fun than a frog in a blender (well almost) and if you play it regularly then Supermodels will want to have sex with you (well hopefully). @endnode @node REQUIREMENTS "Requirements for MahjonggTiles" @{u}Requirements@{uu} MahjongTiles requires: - AmigaDOS v3.0 or later. - MUI v3.8 or later. Recommended: - Fast CPU 68030 or better. - AGA or CyberGraphics. - Picture Datatype V43 or better. - Mango and Banana Nectar if you are thirsty. @endnode @node COPYRIGHT "Once Upon a Time ..." MahjonggTiles is copyright by the authors, Geoffrey Whaite and Przemyslaw Gruchala, and is distributed as FreeWare. MahjonggTiles cannot be sold or distributed as part of a commercial product without the permission of the author. It is allowable to distribute MahjonggTiles on magazine cover disks and Aminet CDs. The main author can be contacted at: Postal mail: Geoffrey Whaite 84 / 19A Tusculum Street Potts Point, NSW, 2011 Australia E-mail: gwhaite@accsoft.com.au The fixes author can be contacted at: Postal mail: Przemyslaw Gruchala os. Sportowe 19/4 31-966 Krakow Poland E-mail: sensei@box43.gnet.pl WWW: http://www.amiga.pl/redgroup The new versions of the latest R.E.D.Group products can be found on this site so please visit us from time to time (or subscribe mailing lists) ;). @endnode @node TOOLTYPES "ToolTypes" @{u}ToolTypes@{uu} The following ToolTypes can be entered in the program's icon :- SETTINGSFILE = name of initial settings file to use RECENTLAYOUTS = the number of recent layout entries in the 'Layout' menu RECENTTILESETS = the number of recent tilesets in the 'Tileset' menu These ToolTypes can be specified in project icons as well. When MahjonggTiles is launched with a project icon argument then the ToolTypes are read from the program's icon first then read from any argument's icon, this gives the project icon's ToolTypes preference over any ToolTypes set in the program's icon. See also @{" The Settings Window " link SETTINGSWIN}, @{" Selecting a Layout " link SELECTINGLAYOUTS}, @{" Selecting a Tileset " link SELECTINGTILESETS} @endnode @node STARTING "Playing MahjonggTiles" @{u}Starting a Game@{uu} You can start a new game by selecting the "New" item in the "Game" menu, this will shuffle the tiles and place them all back in the layout. There are two ways in which the tiles can be shuffled, the first way is just a random shuffle while the second way shuffles the tiles so that there will always be a solution. The suffle method is controlled by the 'Difficulty Level' option in the 'Game Play' page of the settings window, easy games are solveable while normal, hard and very hard games are random. Note that selecting easy games does not guarantee that the game will be solvable as some layouts may not be solveable or finding a solution for them could be difficult. Such layouts would be unusual, most layouts you will encounter should be able to produce solveable shuffles without any problem. You can restart the current game at any time by selecting the "Restart" item in the "Game" menu. See also @{" Making Moves " link MOVING} @endnode @node MOVING "Playing MahjonggTiles" @{u}Making Moves@{uu} A move in MahjonggTiles involves selecting a pair of free tiles and removing them from the layout. A free tile is selected by clicking on it with the left mouse button, tiles that are not free cannot be selected. When a tile is selected its face imagery is rendered using the selected background instead of the normal background, the selected background is usually highlighted in yellow although it could be different depending on the tileset in use. Clicking on a selected tile with the left mouse button will deselect it. As tile pairs are removed from the layout the 'Tiles' status display in the bar at the top of the window will be updated to reflect the number of tiles remining in play. This status display shows the number of tiles remaining in the layout and the total number of tiles in the layout. Usually a tile pair is removed as soon as the second tile of the pair is selected. However, if you select the 'Double Click Remove' option in the 'Game Play' page of the settings window then it will be necessary to double click on a tile to remove the pair. It does not matter whether the tile you double click on is already selected or not so long as it matches another selected tile. Nor is it required that the tile double clicked on be the second tile selected, you can select a tile then select a second matching tile then go back and double click on the first tile to remove the pair. If you have the 'Double Click Remove' option enabled and have two selected tiles then clicking on a third free tile matching the selected tiles will deselect the least recently selected tile and select the tile clicked on in its place. Unless you have the 'No Auto Deselect' option in the 'Game Play' page of the settings window selected then clicking on a free tile that does not match an already selected tile will deselect the currently selected tile(s) and select the new tile instead. If the 'No Auto Deselect' option is enabled then the currently selected tile(s) must be deselected before another non-matching tile can be selected. If you have not disable mouse tracking by selecting the 'No Mouse Tracking' option in the 'Game Play' page of the settings window then moving the mouse pointer over a free tile will highlight it by rendering its face imagery using the first highlight background, this is usually highlighted in green but the exact appearance depends on the tileset in use. If there are any selected tiles then moving the mouse pointer over a free tile that matches the selected tile(s) will highlight the tile with the selected background instead of the first highlight background to indicate that it matches the selected tile(s). There is also a second highlight background which is usually highlighted in red but, like the seleced and first highlight backgrounds, its exact appearance depends on the tileset. More on this later. See also @{" Undoing and Redoing Moves " link UNDOING}, @{" Getting Help and Hints " link GETTINGHELP} @endnode @node UNDOING "Playing MahjonggTiles" @{u}Undoing and Redoing Moves@{uu} MahjonggTiles maintains a list of all moves made in a game, this list can be used to undo moves made to correct mistakes. To undo the last move made select the "Undo" item in the "Move" menu or press its shortcut key, this shortcut key can be set in the 'Command Keys' page of the settings window and its current setting is displayed to the right of the "Undo" menu item. Further selecting the "Undo" item will progressivley undo moves towards the beginning of the game. If there have been no moves made since undoing some moves then it is possible to redo those moves one at a time by selecting the "Redo" item in the "Move" menu or its shortcut key. Like the "Undo" item the "Redo" item's shortcut key is user settable and its current setting is displayed at the right of the menu item. Once any move is made then all subsequent redo data is discarded as it can no longer be regarded as relevent once the chain of moves leading to it has been broken. There are also "Undo" and "Redo" buttons at the right of the bar at top of the main window that perform the same actions as the "Undo" and "Redo" menu items. When undo or redo data is not available then the appropriate menu items and buttons are disabled. Next to the Undo/Redo buttons on the top bar in the window is a popup button for a history/undo list. This list shows the tile pairs removed from the game so far, the first pair at the top of the list is the first pair removed from the game and the last pair in the list is the last pair removed from the game. Not only does this list allow the player to view which tile pairs have been removed from the game but allows them to undo/redo to any point in the list by clicking on a tile of a pair in the list. Clicking on the list will undo/redo up to and including the pair clicked on. Double clicking on a tile of a pair in the list is the same as clicking on the tile and will close the popup list as well. The popup list can be closed without taking any action by clicking the right mouse button on the list, pressing the Escape key or by clicking on the popup button (if it is not obscured by the popup list). Tile pairs in the list that have been undone are rendered using the second (red) highlight. See also @{" Making Moves " link MOVING} @endnode @node GETTINGHELP "Playing MahjonggTiles" @{u}Getting Help and Hints@{uu} There are two ways in which a player can get help with moves while playing the game, showing available moves and showing tiles that match the selected tile(s). Showing available moves is achieved by selecting the "Show Moves" item in the "Move" menu or by pressing its shortcut key. The shortcut key is user settable in the 'Command Keys' page of the settings window and its current setting is displayed at the right of the menu item. When this item is selected the next set of matching free tiles (there must be at least two) are highlighted using the second (red) highlight background. Each subsequent selection of the item will show the next set of available tiles until all free moves have been shown in which case all highlighting is removed. If there are no moves available then selecting this item will display a requester informing the player that no more moves are available. Showing matching tiles is achieved by selecting the "Show Matching" item in the "Move" menu or by pressing its shortcut key. Like the "Show Moves" menu item the shortcut key is user settable and displayed at the right of the menu item. This menu item only has an affect when there are selected tiles in which case it will highlight all tiles that match the selected tile(s). If the matching tile is free then it will be highlighted using the first (green) highlight, if the matching tile is not free it will be highlighted using the second (red) highlight. If the 'Auto Show Matching Tiles' option in the 'Game Play' page of the settings window is set then a Show Matching Tiles is automatically performed whenever the player selects a tile. Both of these help highlighting methods are mutually exclusive, selecting any highlighting will first clear any existing highlighting of any type. Both types of highlighting will time out and revert to normal after 10 seconds. See also @{" Making Moves " link MOVING} @endnode @node TIMEDGAMES "Playing MahjonggTiles" @{u}Timed Games@{uu} Selecting the 'Timed Games' option in the 'Game Play' page of the settings window enables the game timer. When enabled the time spent playing the game is displayed in the bar at the top of the window. The game timer is halted reset to zero when a new game is started (or restarted) and starts when the player firsts clicks on a tile in the layout or first performs a Show Available Moves. The timer stops when all tiles are removed from the layout. MahjonggTiles maintains a list of the five best times for each layout. When a player complete a game with the 'Timed Games' option set the time that the game took is compared to the best time list entries and if it is better than the time of any of the entries then then a requester is displayed informing the player of their position in the best time list and prompting them for their name. This name and time are then inserted into the best time list for that layout and the new best times list is displayed with the new entry highlighted. The best time list for a layout can be displayed at any time by selecting the "Best Times" menu item in the "Layout" submenu of the "Game" menu. See also @{" Showing the Best Times for a Layout " link BESTTIMES} @endnode @node LAYOUTS "MahjonggTiles Layouts" @{u}About MahjonggTiles Layouts@{uu} MahjonggTiles supports multiple layouts, although you can only play one layout at a time. A MahjonggTiles layout is composed of several layers stacked on top of each other. Each of these layers is a grid of layout cells. The width and height of each of these cells is half the width and height of a tile. Tiles are placed on this grid occupying a 2x2 block of grid cells, tiles can be placed anywhere on the layer providing they do not overlap, i.e. occupy a common grid cell. The number of tiles in a layout is a multiple of four so the layout can be occupied by an exact number of tileset quartets. A Mahjongg tileset has 144 tiles (36 tile quartets) but a layout is not restricted to using 144 tiles. There can be up to 256 tiles (64 quartets) in a layout. A layout also has a name which is used to identify the layout, a comment which is displayed in the 'About MahjonggTiles' requester and a list of up to five best times for when the 'Timed Games' option is enabled. See also @{" Selecting a Layout " link SELECTINGLAYOUTS}, @{" Showing the Best Times for a Layout " link BESTTIMES}, @{" Creating and Editing Layouts " link LAYOUTEDIT} @endnode @node SELECTINGLAYOUTS "MahjonggTiles Layouts" @{u}Selecting a Layout@{uu} A player selects the layout to play by choosing the "Select Layout" menu item in the "Layout" menu. Selecting this item opens the Select Layout Window. The Select Layout Window has a list of available layouts, a sting gadget with an asl popup button for specifying the layout directory and 'OK' and 'Cancel' buttons. The entries in the layout list show the name of the layout, the number of tiles in the layout and the size of the layout grid. A player selects a layout by selecting its entry in the list and clicking on the 'OK' button or by double clicking of the layout's entry in the list. Selecting a layout automatically starts a new game. At the bottom of the "Layout" menu is a list of the most recent layouts selected to play. The most recently selected layout is at the top of the list and is shown selected with a checkmark. When a new layout is selected to play it is entered at the top of the list and all the other entries are moved down one place. If the new layout is already in the list then it is moved to the top. Choosing one of the recent layout menu items moves that entry to the top of the list and selects that layout to play. The number of entries in the recent layouts list can be set with the RECENTLAYOUTS tooltype in the program's icon. This can have a value of 4 to 16 and defaults to 8 if the tooltype is not specified. @endnode @node BESTTIMES "MahjonggTiles Layouts" @{u}Showing the Best Times for a Layout@{uu} Each layout maintains a list of the five best (quickest) times taken to complete the layout, this list contains the time taken and the player's name for each of the five entries. This Best Times list can be shown at any time by choosing the "Best Times" menu item in the "Layout" menu. It is not necessary to enable the 'Timed Games' option to display the Best Times for a layout. See also @{" Timed Games " link TIMEDGAMES} @endnode @node LAYOUTEDIT "MahjonggTiles Layouts" @{u}Creating and Editing Layouts@{uu} MahjonggTiles comes with a companion layout editor application called 'MTLayoutEditor'. The layout editor may be launched independantly of the game by double clicking its icon which is in the same draw as the game or it may be launched from within the game by choosing the "Run Layout Editor" menu item in the "Layout" menu. When launched from within the game the layout editor is started up with the current game layout loaded for editing. See the MTLayoutEditor documentation for details on using the layout editor. @endnode @node TILESETS "MahjonggTiles Tilesets" @{u}About MahjonggTiles Tilesets@{uu} MahjonggTiles supports selectable tilesets. A MahjonggTiles tileset consists of a tileset descriptor file and one or more picture files that contain the tile imagery and drawing pen information. The @{"tileset descriptor file" link DESCRIPTORFILE} specifies the following information :- . the name of the tileset . a comment about the tileset . the height and width of the tile face imagery . the number of quartets in the tileset . the name and location of the main image file for the tileset . the name and location of any extension image files for the tileset . the name and location of a background image file to use with the tileset The width and height of the tile face image, the number of quartets and the main image file are required properties of a tileset, all the others are optional. Tilesets can have up to 64 tile quartets (256 tiles). If the layout has less quartets than the tileset then only the first number of quartets equal to the number quartets in the layout are used. If there are more quartets in the layout than the tileset then extra quartets will be generated whose face image is a spot with a number inside, the first extra quartet is numbered 1, the second 2 and so on. See also @{" Selecting a Tileset " link SELECTINGTILESETS}, @{" Showing the Current Tileset " link SHOWINGTILESETS}, @{" Creating Custom Tilesets " link CREATINGTILESETS} @endnode @node SELECTINGTILESETS "MahjonggTiles Tilesets" @{u}Selecting a Tileset@{uu} A player can select the tileset to play with by choosing the "Select Tileset" menu item in the "Tileset" menu. Choosing this menu item opens the 'Select Tileset' window. This window contains a list of available tilesets, a string gadget with an asl popup button to specify the directory that the tilesets are located in, 'OK' and 'Cancel' buttons and a 'Preview Tileset' button to allow the player to display the tileset for review before using it. The tileset list shows the name of each tileset as well as the size of the tile face imagery. A player selects a tileset to use by selecting its entry in the list and clicking the 'OK' button or by double clicking on the tileset's entry in the list. Clicking the 'Preview Tileset' button will load the selected tileset and display it in a tileset list window. Each entry in this list shows the tile face imagery of the four tiles of a tile quartet. Initially the four tiles in each tile quartet are rendered with the four possible backgrounds, normal, selected (yellow) and the two highlights (green and red). Clicking on any tile face image in the list will cycle the background of the tile through the four possible states. Note that the exact appearance of the of the background states depend on the tileset. At the bottom of the "Tileset" menu is a list of recent tilesets with the most recently selected tileset at the top of the list and shown selected with a checkmark. When a tileset is selected to be used it is entered at the top of this list and all the other entries are moved down one place. If the new tileset is already in the recent tileset list then it is moved to the top of the list. Choosing a recent tileset menu item moves that entry to the top of the list and selects that tileset to use for the game. The number of entries in the recent tilesets list can be set with the RECENTTILESETS tooltype in the program's icon. This can have a value of 4 to 16 and defaults to 8 if the tooltype is not specified. @endnode @node SHOWINGTILESETS "MahjonggTiles Tilesets" @{u}Showing the Current Tileset@{uu} Some Mahjongg tilesets can contain tile quartets in which the face image of each of the tiles in the quartet are different, for example the four seasons or the four flowers. This can be confusing to a player who is not yet familiar with the tileset so a means to display the tileset that shows these different, but matching, tile faces is desirable. Choosing the "Show Tileset" menu item in the "Tileset" menu will open a Tileset Display window to show the currently selected tileset. This window shows a list of the tile quartets in the tileset. This list is similar to the Preview Tileset window list that can be shown from the Select Tileset window except that the tile faces are all displayed in the normal background state for tiles that are being used in the game or in the second (red) highlight if the quartet is not being used because there are more tiles in the tileset than in the layout. The background state of the tile faces cannot be changed by clicking on them. @endnode @node CREATINGTILESETS "MahjonggTiles Tilesets" @{u}Creating Custom Tilesets@{uu} To create a custom tileset it is necessary to create the @{"main image file" link MAINIMAGEFILE}, any @{"extension image files" link EXTIMAGEFILE} and the @{"tileset descriptor" link DESCRIPTORFILE} file to tie all the bits together. It is recommended that the image files be stored in a subdirectory of the directory where the descriptor file is located. This allows the image files to be specified relative to the descriptor file making installing or moving the tileset easier. Once all these files have been created they are installed in the tileset directory which is PROGDIR:tiles/ by default. See also @{" Tileset Descriptor File " link DESCRIPTORFILE}, @{" The Main Image File " link MAINIMAGEFILE}, @{" Extension Image Files " link EXTIMAGEFILE} @endnode @node DESCRIPTORFILE "MahjonggTiles Tilesets" @{u}The Tileset Descriptor File@{uu} The tileset descriptor file is a text file that contains a number of entry/value pairs. Each entry/value pair is a line in the text file that begins with an entry name followd by an '=' character with the rest of the line being the value of the entry. Leading and trailing spaces at the beginning and end of the name and value are ignored. The descriptor file can also contain comment lines which start with a ';' character and blank lines which contain no text apart from spaces. Comment and blank lines are ignored by the program when loading tilesets. Tileset Descriptor files must have a '.tiles' extension so the Tileset Select Window can identify and list them. The valid entry names in the descriptor are as follows :- @{b}Name@{ub} The name of the tileset. This is the name shown in the Select Tileset Window list and in the About MahjonggTiles Window. If this entry is missing then the descriptor filname, without the '.tiles' extension, is used as a default name. @{b}Comment@{ub} A comment about the tileset. This is displayed in the About MahjonggTiles Window. @{b}Width@{ub} - This is a required entry. The width of the tile face image. The value of this entry is a decimal number. @{b}Height@{ub} - This is a required entry. The height of the tile face image. The value of this entry is a decimal number. @{b}Quartets@{ub} - This is a required entry. The number of tile quartets in the tileset. The value of this entry is a decimal number. @{b}ImageFile@{ub} - This is a required entry. The name of the main image file. This is usually relative to the directory where the descriptor file is located but can be an absolute path name. @{b}Extension%d@{ub} The name of any extension image files where the '%d' in the entry name is the decimal quartet number that the extension image is to be used for. Quartet numbers start at 0 for the first quartet in the tileset. This is usually relative to the directory where the descriptor file is located but can be an absolute path name. @{b}Background@{ub} The name of the background image file to use with the tileset. This is usually relative to the directory where the descriptor file is located but can be an absolute path name. See also @{" The Main Image File " link MAINIMAGEFILE}, @{" Extension Image Files " link EXTIMAGEFILE} @endnode @node MAINIMAGEFILE "MahjonggTiles Tilesets" @{u}The Main Image File@{uu} The main tileset image is composed of number of individual tile face sized sub-images. As such, the width of the main image is an exact multiple of the tile face width and its height is an exact multiple of the tile face height. The first six of these sub-images are special images used for rendering the tile face backgrounds and for defining the drawing pens used to render the tile face trimming and the tile edges. The remaining sub-images are the face images for the quartets of the tileset, one image per quartet of the tileset. The sub-images are counted from left to right and then from top to bottom, i.e. the first sub-image is at the top-left of the main image, the second is to the right of the first and so on until the top line of sub-images have been counted then the process continues from the left most sub-image of the second row of sub-images. The total number of sub-images in the main image must be at least six greater than the number of quartets in the tileset, any further sub-images are ignored. If the width of the main image is not an exact multiple of the tile face width or the height of the main image is not an exact multiple of the tile face height or the number of sub-images is less than the number of quartets in the tileset plus six then the main image is considered to be invalid and loading the tileset will fail. The first six special sub-images have the following purposes :- 1. The first sub-image is just a solid block in the background colour used for the tile face images. This is not the tile face background that is rendered but just specifies the background pen and is used for creating the background masks that are used for drawing the actual background of the tile faces, any pixel in a tile face image that is this colour is considered to be part of the background. 2. The second sub-image is the normal tile face background. This is the background that is rendered for a tile face and can be a solid colour or a pattern. If this pattern shows highlighting resulting from a 'light source' then it should be draw as if the 'light source' is above and to the left of the tile face. 3. The third sub-image is the selected tile face background. This is the background that is rendered for selected tiles and can be a solid colour or a pattern. If this pattern shows highlighting resulting from a 'light source' then it should be draw as if the 'light source' is above and to the left of the tile face. 4. The fourth sub-image is the first highlight tile face background. This is the background that is rendered for highlighted tiles and can be a solid colour or a pattern. For consistency, this background should be highlighted using a green shade. If this pattern shows highlighting resulting from a 'light source' then it should be draw as if the 'light source' is above and to the left of the tile face. 5. The fifth sub-image is the second highlight tile face background. This is the background that is rendered for highlighted tiles and can be a solid colour or a pattern. For consistency, this background should be highlighted using a red shade. If this pattern shows highlighting resulting from a 'light source' then it should be draw as if the 'light source' is above and to the left of the tile face. 6. The sixth sub-image is used to define the drawing pens used to render the tile face trimming and the tile edges. This image is composed of nine horizontal strips, the pixel height of each of these strips is the height of the tile face divided by nine, rounded down to the nearest integer. For example, if the tile face is 45 pixels heigh then each strip is 5 pixels high, if the tile face is 50 pixels high then each strip is 5 pixels high and the extra 5 pixels at the botton of the sub-image are ignored. The nine drawing pens defined by the sixth sub-image are as follows (starting with the top stripe and working down) :- 1. The vertical tile face trimming shine pen. The vertical tile face trimming nearest to the light source is drawn using this colour. 2. The vertical tile face trimming shadow pen. The vertical tile face trimming furthest from the light source is drawn using this colour. 3. The horizontal tile face trimming shine pen. The horizontal tile face trimming nearest to the light source is drawn using this colour. 4. The horizontal tile face trimming shadow pen. The horizontal tile face trimming furthest from the light source is drawn using this colour. 5. The vertical tile edge shine pen. The vertical tile edge nearest to the light source is drawn using this colour. 6. The vertical tile edge shadow pen. The vertical tile edge furthest from the light source is drawn using this colour. 7. The horizontal tile edge shine pen. The horizontal tile edge nearest to the light source is drawn using this colour. 8. The horizontal tile edge shadow pen. The horizontal tile edge furthest from the light source is drawn using this colour. 9. The tile edge outline pen. The tile edges are outlined with this colour to emphasise the boundary between adjacent tiles. @{b}Note@{ub} that if the four face trimming pens are the same as the background colour (the colour of the first sub-image) then the tileset does not use face trimming. This allows for tilesets in which the face trimming visuals are part of either the tile face images or the background images. @endnode @node EXTIMAGEFILE "MahjonggTiles Tilesets" @{u}Extension Image Files@{uu} Tileset extension image files define the extra tile face imagery used for tile quartets that have a different image for each tile in the quartet. The main image file will always provide the image of one tile face for the quartet so the extension image need only supply an extra three face images. Like the main image, the extension images are composed of a number of tile face sized sub-images. For extension images there are four sub-images, the first is a solid background colour that is used to generate the background masks for the face images, if a pixel in a face image is the same colour as the first sub-image then it is considered to be part of the background. The next three sub-images are the three extension face images for the quartet. If the width of the extension image is not an exact multiple of the tile face width or the height of the extension image is not an exact multiple of the tile face height or there are less than four sub-images then the extension image is considered to be invalid. When an extension image is found to be invalid it is ignored and the tiles of the quartet all have the same images from the main image file. See also @{" The Main Image File " link MAINIMAGEFILE} @endnode @node SETTINGSWIN "Configuring MahjonggTiles" @{u}The Settings Window@{uu} The Settings Window allows the user to adjust visual appearance and game play options for MahjonggTiles. The Settings Window is opened by choosing the 'Game Settings' menu item in the 'Settings' menu. The Settings Window is divided into several pages that control related groups of options. These pages are :- @{" Tileset Visuals " link TSVISUALPAGE} - options affecting the rendering of tiles. @{" Backgrounds " link BACKGROUNDSPAGE} - options affecting playfield background rendering. @{" Game Play " link GAMEPLAYPAGE} - options affecting how the game is played. @{" GUI Images " link GUIIMAGESPAGE} - selects graphics to display some GUI objects. @{" Command Keys " link CMDKEYSPAGE} - define shortcut keys for some commands. Below the settings pages is a button bank that is available no matter which settings page is currently selected. These buttons are :- @{b}Save@{ub} - accept any changes made, close the window and save the settings. @{b}Use@{ub} - accept any changes made and close the window. @{b}Cancel@{ub} - abandon any changes made and close the window. @{b}Undo@{ub} - restores the settings for all pages to their initial values. The settings can be saved at any time by choosing either the 'Save Settings' or the 'Save Settings As...' menu items in the 'Settings' menu. If the settings have been modified and not saved when the game is exited or when new settings are loaded the player will be given the opportunity to save the settings before continuing. The initial settings file can be specified with the SETTINGSFILE tooltype in the programs icon. @endnode @node TSVISUALPAGE "Configuring MahjonggTiles" @{u}The Tileset Visuals Page@{uu} This settings page has options that affect how the tiles are rendered including light source direction, view direction and tile face trimming options. The options on this page are as follows :- @{b}View From Right@{ub} - normally the tiles are rendered as if they are being viewed from the left, i.e. we can see the left and bottom tile edges. When this option is enabled (checked) then the tiles are rendered as if viewed from the right. In both cases the tiles are rendered as if viewed from below. @{b}Light From Right@{ub} and @{b}Light From Below@{ub} - these two options control the location of the light source that illuminates the tiles. Normally this light source is located above and to the left of the layout so that left/top trimming/edges are rendered using the shine pens and the bottom/right trimming/edges are rendered using the shadow pens. These options allow the light source to be located to the right instead of the left of the layout or below instead of above the layout. @{b}No Tile Face Trimming@{ub} - this option causes the tile faces to be rendered without edge trimming. @{b}Same Horizontal and Vertical Thickness@{ub} - normally the pixel thickness of the the horizontal and vertical trimmings can be adjusted independently, this option causes both the horizontal and vertical trimming thickness to be the same. @{b}Horizontal Trim Thickness@{ub} - this slider is used to adjust the pixel thickness of the horizontal tile face trimming. @{b}Vertical Trim Thickness@{ub} - this slider is used to adjust the pixel thickness of the vertical tile face trimming. When the 'Same Horizontal and Vertical Thickness' option is enabled then this slider is disabled and is slaved to the 'Horizontal Trim Thickness' slider. Note that some tilesets do not use tile face trimming and will not be affected by any of the tile face trimming options. @endnode @node BACKGROUNDSPAGE "Configuring MahjonggTiles" @{u}The Backgrounds Page@{uu} This settings page contains options that control how the background of the playfield is rendered. The playfield background can be a pattern derived from a picture file that is tiled across the playfield background or it can be rendered as a solid block in the default background colour. The options on this page are as follows :- @{b}Background Source@{ub} - this cycle gadget specifies where to get the background image to use for the background pattern. There are three values for this option :- No Background - the background is rendered using the background pen. Default Background - use the default background file for the background pattern. Tileset Background - use the background specified by the current tileset. @{b}Default Background@{ub} - this specifies a picture file to use for the defailt background pattern. There is an asl popup button to allow the user to select the background file from an asl file requester. If you select to use the tileset background and the tileset does not specifiy a background file or the specified background file is not a picture file then the default background file is used instead. If the default background file does not specify a valid picture file then the background is rendered with the default background pen instead. @endnode @node GAMEPLAYPAGE "Configuring MahjonggTiles" @{u}The Game Play Page@{uu} This settings page has options that affect how the game is played. The options on this page are as follows :- @{b}Double Click To Remove Tiles@{ub} - normally tile pairs are removed from the game as soon as the second tile of the pair is selected. When this option is selected then it is necessary to double click on one of the tiles of the pair to remove the pair. It does not matter if the tile double clicked upon was already selected or not so long as there is a matching selected tile. @{b}No Auto Deselect@{ub} - normally when the player clicks on a free tile that does not match an already selected tile then the selcted tile is deselected and the tile that was clicked on is selected in its place. With this option enabled it is necessary to deselect any currently selected tiles before a non-matching tile can be selected. Selected tiles can be deselected by clicking on them. @{b}Difficulty Level@{ub} - this cycle gadget selects one of four difficulty levels, easy, normal, hard or very hard. The difficulty level affects the game play as follows :- Easy - games are shuffled to be solveable. Normal - games are shuffled randomly. Hard - games are shuffled randomly with undo disabled. Very Hard - games are shuffled randomly with undo and game hints disabled. @{b}Timed Games@{ub} - selecting this option enables the game timer. The game timer starts when the player firsts clicks on a tile or firsts shows available moves. The timer stops when the last tile pair is removed from the layout. MahjonggTiles maintains three best time tables for each layout, one for each difficulty level. Each best time table holds the five quickest times taken to complete the game for that difficulty level and the names of the players who achieved those times. @{b}No Mouse Tracking@{ub} - normally when the mouse pointer is moved over a free tile in the layout that tile is highlighted using the first (green) highlight background to give a visual indication that the tile is free. When this option is enabled then this highlighting is disabled. This can be useful on systems with a low powered processor or slow graphics as mouse tracking can use a lot of processor time. It can also be used to disable the highlighting because the player just dosen't want to be distracted by tile faces flashing at them as they move the mouse across the playfield. @{b}Auto Show Matching Tiles@{ub} - when this option is selected a 'Show Matching Tiles' is automatically performed whenever the player selects a tile. This option is ignored when the difficulty level is set to very hard as 'Show Matching Tiles' is disabled for very hard games. @endnode @node GUIIMAGESPAGE "Configuring MahjonggTiles" @{u}The GUI Images Page@{uu} Some of the GUI objects in MahjonggTiles derive their appearance from external picture files. This settings page allows the user to select the picture files to use for these objects. Each of these GUI objects require a picture file in a format specific to the type of GUI object. Currently there are two types of GUI objects that can be customised in this way, digital status displays and three state buttons. The digital status displays require a picture file that is composed of 16 equal sized sub-images in a single horizontal strip. The sub-images are the characters rendered for the status displays including the decimal digits, a blank, a decimal point, sign characters ('+' and '-') and other special characters ('/' and ':'). The height of each character is the height of the picture file and the width of each character is one sixteenth of the picture file width. If the width of the picture file is not an exact multiple of 16 then it is considered to be invalid. The order of the characters in the picture file is as follows (from left to right) :- '0' '1' '2' '3' '4' '5' '6' '7' '8' '9' ' ' '.' '+' '-' ':' '/' A number of possible digital display image files are included with MahjonggTiles. These are located in the 'images' subdirectory in the program directory and have file names starting with 'MTDigit', the file 'images/MTDigit.def' is the default image file that is used if no other is specified. The three state button picture files are composed of three equal sized sub-images in a horizontal strip. These sub-images show the button appearence in the three states, normal, selected and disabled. The height of the button is the height of the picture file and its width is one third the width of the image file. If the width of the picture file is not an exact multiple of three then it is considered to be invalid. The order of the sub-images in the picture is as follows (from left to right) :- Normal, Selected and Disabled. Each GUI object that can be customised in this way has a string gadget with an associated asl popup button for specifing the picture file to use for the object. These objects are as follows :- @{b}Tiles Display@{ub} - this digital status display shows the tiles remaining in the game and the total number of tiles in the layout. This display resides in the bar across the top of the MahjonggTiles window. @{b}Time Display@{ub} - this digital status display shows the game time when the game timer is enabled. This display resides in the bar across the top of the MahjonggTiles window. @{b}Undo Button@{ub} - this button is used to undo a single game move. It resides in the bar across the top of the MahjonggTiles window. @{b}Redo Button@{ub} - this button is used to redo a single undo. It resides in the bar across the top of the MahjonggTiles window. @endnode @node CMDKEYSPAGE "Configuring MahjonggTiles" @{u}The Command Keys Page@{uu} This page allows the user to define the command shortcut keys to use for the move commands. There are three ways in which a command key may be specified :- 1. As a single displayable ASCII character, any single character that can be entered into a string gadget (except space) can be used for this, the command is executed when the player types the same key during game play. 2. A special name representing a non-displayable ASCII character (including space) that can be generated from the keyboard. Valid names are as follows :- space tab esc backspace delete enter return 3. A special name representing a non-ASCII key on the keyboard, these are the keys that do not generate ASCII codes when pressed. Valid non-ASCII key names are as follows :- f1 to f10 - the function keys help - the help key left, right, up and down - the cursor keys The non-ASCII key names may optionally be preceeded by one or more of the following qualifiers :- shift - either shift key alt - either alt key control - the control key A non-ASCII command key will only be recognised when its specified qualifiers and none of the others are active at the time that the key is pressed. Shortcut keys for the following command can be setup by the user :- Undo Redo Show Available Moves Show Matching Tiles @endnode @node CREDITS "Credits and Acknowledgements" @{u}Credits@{uu} Thanks to the following people for beta testing, suggestions and bug reports. Diana Mrkusick Christian Hattemer http://www.riednet.wh.tu-darmstadt.de/~chris Damir Arh http://damir.gajba.net/ Vit Sindlar http://ato.vapor.com/czech Richard Kapp http://narr.tsx.org Marcin 'Mr.Q' Kielesinski http://www.viper.pl/~reborn/ and http://www.martina.3d.pl Thanks to the following people for contibutions made. Lyle Zapato http://zpatopi.net for the use of his Archæologicons as a tileset. Jürgen Urbanek for the Glow Icons MahjongTiles and MTLayoutEditor use @{" MUI " link MUI} by Stefan Stuntz. @endnode @node MUI "MUI Credits" ------------------------------------------------------------------------ MUI - MagicUserInterface Version 3.8 (c) Copyright 1992-97, Stefan Stuntz ------------------------------------------------------------------------ MUI is an object oriented system to create and maintain graphical user interfaces. From a programmers point of view, using MUI saves a lot of time and makes life much easier. Thinking about complicated terms like window resizing or font sensitivity is simply not neccesary. On the other hand, users of MUI based applications have the ability to customize nearly every pixel of a programs interface according to their personal taste. Please click on the Install-MUI icon to install MUI on your system or to update from previous versions. Latest news and support can be found on Internet at www.sasg.com. *********** Attention If you're still not registered for MUI, check the new and unique shareware lottery and great discounts at www.sasg.com. Give it a try! @endnode @node HISTORY "Revision History" @{u}History@{uu} v0.1 (26 May 2000) First prerelease. Limited distribution by email only. v0.2 (13 June 2000) Second prerelease. Fixed bug with closing the tileset preview window when selecting a tileset. Bug reported by Christian Hattemer. Removed the 'Solveable Games' option from the 'Game Play' page of the settings window and replaced it with a 'Difficulty Level' option. The difficulty level combines the solveable games option and a suggestion by Christian Hattemer for a hard game option. The difficulty levels and their effects are as follows :- Easy - solveable games Normal - random shuffle Hard - random shuffle with no help ('Show Moves' and 'Show Matching') Very Hard - random shuffle, no help or undo Implemented best time scoring. Each layout maintains four lists of the five fastest game times and their players, one list for each of the four difficulty levels. Fixed bug where not all of the custom MUI classes were being freed when the game is exited. Changes to the code that allocates and frees BitMaps and masks for tilesets for better CyberGfx support. Other minor changes. v0.3 (2 July 2000) Third prerelease. Saving the settings now checks if the settings directory exists and tries to create it if it dosen't. Previously if the settings directory did not exist then saving the settings would silently fail. Settings are no longer saved automatically when the program exits. Instead there are three new menu items in the settings menu, "Load Settings...", "Save Settings" and "Save Settings As..." to allow the manual saving and loadings of settings. If the settings have been updated when the program is exited or when new settings are loaded the player is given the opportunity to save the settings before continuing. Layout and tileset file names are still automatically saved to the current settings file. Added a 'New Game' button to the 'No More Moves' requester. This is the requester that is displayed when a 'Show Moves' command is executed and there are no moves available. Each time a pair of tiles are removed from the layout, either by a move or by redoing an undone move, a check is made for available moves and the 'No More Moves' requester is displayed if there are no more moves available. Rearrange buttons on the 'Select Tileset Window' and the 'Settings Window' so that the 'Cancel' button is always rightmost. Improvements to tileset handling including : - Fixed problem with graphics corruption when playing on an interleaved planar screen. - Improved mask generation significantly speeding up the loading of tilesets. - Tile dace backgrounds are flipped to follow the light source direction so backgrounds that show light source highlighting effects will display correctly orientated for the 'Light Right' and 'Light Below' tileset settings, this requires that the initial backgrounds are drawn as if illuminated from above and to the left of the layout. Fixed enforcer hits when the layout editor is starting up. When performing a "Save Layout As ..." from the layout editor the initial drawer and filename are set to the current layout's drawer and filename. Changes to MahjonggTiles.cd : Added Strings : MSG_MENUITEM_SETTINGS_LOAD (510//) MSG_MENUITEM_SETTINGS_SAVE (511//) MSG_MENUITEM_SETTINGS_SAVEAS (512//) MSG_SAVECONTCANCEL_GADGETS (1028//) MSG_REQLOFILE_LOADTITLE (1170//) MSG_REQLOFILE_SAVETITLE (1171//) MSG_REQLOFILE_LOAD (1172//) MSG_REQLOFILE_SAVE (1173//) MSG_REQLOFILE_CANCEL (1174//) MSG_MTWINDOW_SAVE_SETTINGS_FMT (1265//) MSG_MTWINDOW_SAVE_SETTINGS_LOAD (1267//) MSG_MTWINDOW_SAVE_SETTINGS_EXIT (1268//) v1.0 (1 Aug 2000) First Public Release Implemented popup History/Undo list which shows the tile pairs that have been removed from the game, from the first pair removed at the top of the list to the latest pair removed at the bottom of the list. This list can be used not only to review which tiles have already been removed from the layout but can act as a quick multiple move undo/redo by clicking on a tile in the list to undo/redo upto and including the tile pair clicked on. Double clicking will undo/redo plus close the popup list. RMB, Esc key or clicking the popup button will close the popup list without taking any action. Added 'Undo Popup Button Image' item in the 'Game Play' page of the Settings Window to specify the imagery to use for the 'Undo/History' popup button. Supplied default image file for the 'Undo/History' popup button. Replaced the 'Ok' button in the Settings Window with 'Save' and 'Use' buttons. The 'Save' button accepts the settings and saves them to disk, the 'Use' button accepts the settings but does not save them. Moved the 'Tileset' submenu from the 'Game' menu to its own menu. Implemented recent layouts and recent tilesets list. These list are displayed at the bottom their respective menus. The most recently selected layout/tileset is at the top of the list and is checked to indicate its current status. Selecting a new layout/tileset places it at the top of its list, if it is already in the list then it is moved to the top. Selecting an item in a recent list selects that layout/tileset to use. The current layout and tileset are no longer saved with the game settings, the recent layout/tilesets save this information instead. Implemented the following ToolTypes :- SETTINGSFILE = name of settings file to use (default NULL) RECENTLAYOUTS = number of recent layout entries (4 to 16, def 8) RECENTTILESETS = number of recent tileset entries (4 to 16, def 8) Changes to MahjonggTiles.cd : Added Strings : MSG_SAVEBUTT_LABEL (1004//) MSG_USEBUTT_LABEL (1005//) MSG_MTSWIN_SAVE_HELP (1704//) MSG_MTSWIN_IM_UNDOPOP_LABEL (1778//) MSG_MTSWIN_IM_UNDOPOP_HELP (1779//) Changed shortcut character for : MSG_UNDOBUTT_LABEL (1003//) MSG_MTSWIN_TS_SAMEHV_LABEL (1728//) MSG_MTSWIN_BG_SRCE_LABEL (1740//) MSG_MTSWIN_KEY_SHOWMOVE_LABEL (1784//) Changed symbolic name MSG_MTSWIN_OK_HELP (1705//) to MSG_MTSWIN_USE_HELP (1705//) (the value is still the same but it is now used for the 'Use' button instead of the now departed 'Ok' button) v1.1 (22 Aug 2001) Second Public Release After couple days since reciving the source from Geoffrey Whaite I finally fixed graphics corruption on AGA screens. Geoffrey used invalid minterm for BltMaskBitMapRastPort() (everywhere 0xC0, which is simple copy D=A without the mask in native graphics.library) in TileSet.c/DrawTileFaceBGRP(). After changing it to 0xE2 (D=AB|bC) graphics looks fine. v1.2 (27 Aug 2001) Third Public Release Even before reciving the source I noticied that MahjonggTiles in some cases are crashing after changing the tile set or layout if MuGuardianAngel (and probably Mungwall too) is running on my system. After investigation I found that it's because MT uses pointer to screen that has been closed already (I'm opening MT on custom public screen created by PSI and automatically closed if there's no windows opened). Geoffrey's idea to lock public screen passed in TileSet.c/LoadTileSet() and unlock public screen in TileSet.c/FreeTileSet() seems to solve this bug finally, I hope so. @endnode