```                             ____  ____  __  ______  ____
/ __ \/ __ \/  |/  / _ )/  _/
/ /_/ / /_/ / /|_/ / _  |/ /
\___\_\____/_/  /_/____/___/
_____ ____ ______ ____ ___
____/ ___/ _____/ ___/ __/
```

## Introduction

The rules of QOMBI are learnt in a few minutes. However, some people will find QOMBI hard to master, while others will not feel much challenged. I believe there are three main approaches to playing this game well:

1. Intuitively - ie know how to, or quickly learn, to recognise the patterns without any "verbal" calculation, or
2. Calculating the possibilities using logic.
3. A combination of both of the above

Either way is fine, but you may want to consider: If you are good at (1) or (2), perhaps rather try to practise the other!

## Game rules

There are 81 cards. Each card has four attributes: Shape, Number, Colour, and Fill. Each attribute has three different "states": The shapes are Ovals, Diamonds, and Rectangles. Numbers are One, Two and Three. Colours are Red, Green, and Blue. The fills are Full, Shaded, and Empty.

Initially, 12 cards are laid out on the table. If you can make up one or more tricks, you can remove those cards. After one or more tricks have been removed, You can replenish the table repeatedly, until the deck is exhausted.

A TRICK IS ANY THREE CARDS THAT HAVE FROM ZERO TO THREE ATTRIBUTES IN COMMON, WITH ALL THE REMAINING ATTRIBUTES BEING DIFFERENT.

Points are given for each trick removed: one for each difference, two for each similarity. The trick score increases for each extra trick removed without replenishing. Replenishing costs three points, unless you remove all the cards from the table in one turn. This represents a Super Bonus as the trick increment is not reset! (The bad news is that, in the unlikely event that your score exceeds 32767, the program will crash and your game will be counted as a loss! No compensation is offered in the event of such a calamity.)

If you get stuck and cannot remove any tricks from a full table, you can select one or more cards and have them replaced. Each card replaced costs three points.

You can choose to play a timed game, it which case you start off with 20 extra points. However, each minute used, costs one point.

## Using the program

### Requirements

The program is designed for GD2 colours only. All current GD2 modes, from 16 to 33 should be fine. This means SMSQ/E only, though! I cant guarantee it will run on the slowest, least well endowed computers. (I have, however, had one report of someone regularly playing QOMBI on a Q68!) QOMBI needs just under 1 MB of fast disk space, and more than one Mb of RAM. Minimum screen resolution required is 512x384.

The program requires SMSQ/E 3.26+. It also requires Liberation Software's QLib_run (or QLib_sys) V3.36+ and ptrmen_cde (V4.09+) from Albin Hessler/ Marcel Kilgus. These toolkits must be loaded by the system before the game starts. For your convenience, both toolkits can be found in the _bin directory if required.

### Installation

If you simply unzip the QOMBI container into your games directory, no further installation or configuration is necessary. Dont specify the qmb_ directory; this is already taken care of in the zip file.

Note: The program has several sub directories. This limits the length of the directory name under which it can be installed to 11 characters! Something like

win1_games_

is fine.

The boot program included is merely to check whether your system is capable of running QOMBI, and to load any missing extensions. It must be run in the main system console (Job #0). If all checks out, it will offer to run the program. No further configuration is required at this time.

### Starting QOMBI

The program may be started with EXEC, or attached to one of the many front-ends, Docks, buttons and/or hotkeys. Some of these do not cater for the Home Directory, ie a program's ability to know its own directory. In that case it will fall back on the configured location. Alternatively, you can give that information on the command line, eg:

`ERT HOT_CHP1("Q", 'win1_games_qmb_QOMBI_obj'; 'win1_games_qmb_')`

The parameter after the semi-colon tells QOMBI where to find its files.

To permanently configure a default location to fall back on, use Config or MenuConfig - available from the usual suspects!

Finding the root:

1. If a location is given on the command line, use that, otherwise
2. If there is a home_dir: use that, else,
3. Use the configured location. If that doesnt make sense, fail.

To (optionally) alter certain vital locations, see the Locations section, below.

### Display and Controls

When you start QOMBI, you are faced with a blank table, and a deck of 81 cards on the side board to the right. Above the deck is the timer. Below the deck is the score counter. Bottom right are controls to control the sound and to configure various other game settings.

The title bar has some controls too. From left to right are: Change size, About, and Sleep, and Quit.

Click and Drag anywhere on the title bar to move the window.

Click the change size button to cycle through the available sizes for your display.

Click the sleep button to buttonise the window. This also pauses a timed game.

Click the exit button to quit the game. If a game is in progress, you are prompted for whether you want to save the game <Y> (or DO), quit without saving <N>, or cancel quit <ESC>. If you quit without saving, the games goes into your statistics as a loss! If you choose to save a game in progress, you may resume it later, where you left off.

Clicking the timer before starting a game, toggles between a timed and an untimed game.

Clicking the timer while a game is in progress, pauses the timer (and hides the cards, so there is no cheating!)

Clicking the score counter displays your statistics

The bottom row controls operate as follows:

Click the sound icon to toggle through: BEEP, SSS sound, or No sound.

Click the gear icon to configure various aspects of the program or to save the current settings. (More of this, below.)

### Playing the game

Click the deck to start playing the game; timed or untimed as the case may be.

Following the rules described, select a trick by HITting three appropriate cards. You can un-select a card by HITing it again. Once three cards are selected, providing they constitute a valid trick, DOing one of them causes the trick to be removed from the table (and hidden away somewhere in cyberspace). Your score is incremented accordingly. If the trick was not valid a rude noise is emitted, and you are further brutally punished by loosing three points.

You can continue removing tricks from the table until no more are found. Each additional trick returns an ever better score, so it will pay to keep going, provided you dont take too long in a timed game.

When no more tricks can be found, click the deck for more cards. Keep going until the deck is exhausted. When there are no more cards, clicking the empty deck a last time tells the program that the game is over, and the final score is processed with your statistics. This is also necessary to stop the timer in a timed game. If you click once again after that, a new game is started.

If, with a compliment of 12 cards - a full table, you cannot find any tricks, you may select one or more cards to exchange. These cards are then lost to you, and in addition, each card exchanged costs three points: Select the number of cards you wish to exchange (1..3) and click the deck to be dealt new replacements. (Note that the chances are that, with a full table, most of the time there is at least one valid trick on the table!)

Should you be so unfortunate as to end up with a score of zero or less, the game terminates automatically with a loss. Ditto if the timer should reach 100 minutes.

A game started, if not completed (even if thats due to a power outage!) is considered a lost game.

### Scoring

[Scoring is still experimental. Suggestions are welcome and will be considered (and possibly even followed)!]

Timed game: Initial score 120. Each minute used costs one point.

Untimed game: Initial score 100.

For both timed and untimed games the following apply:

Valid trick:

`( <same features> X 2 + <different features> ) X trick number`

if all four features are different:

`8 X trick number`

Non-trick fault: -3 points (ie declaring a trick that isnt one)

Exchange cards: 3 points per card

Replenish table: 3 points

Replenish completely empty table: 0 points (the trick number continues to increment!)

To take a sneak peek at the score for the currently selected trick, press <H> or <h>! (Short for Hint). Free!

A sneak peek at the next card to be dealt costs 1 point. (See the Hint note, below, for details.)

Best Time: See note under Troubleshooting, below.

### Shortcut keys

Some shortcut keys are defined:
<ESC>- Quit
CF1- Sleep
CF2- Wake
F3- Change configuration
CF3- Change window size
CF4- Move window
S/s- Toggle sound settings
H/h- In-game hint (see below)
<SPACE>- Toggle card selection
<ENTER>- Commit card selection

Cursor keys move the pointer (if system settings permit)

### Hint

When a trick has been selected but not yet effectuated, pressing h or H shows the score the trick would generate, so you can accurately compare the value of various available tricks and choose the best. Or while youre still learning, check whether the trick is valid. This service is free!

However, pressing h/H while the board is full and no card selected, shows the next card to be dealt, in the form of a minature representation of the card (unless you have created your own symbol shapes!)

Previewing the next card is a "cheat", because it provides foreknowledge of a hidden card, allowing you to evaluate which is the best card to swap out. (And swapping out a card costs three points and has other incidental penalties attached). So this service costs you one point a pop.

### Tips and Tricks

To reset your statistics: While the game is NOT running, delete the statistics file, stats_dat, in QOMBI's home directory.

If you dont need all the different sizes, you can remove the card sets you dont need, thus saving some disk space: If you only ever use the smallest size, delete the files and directories one through three. If you find you only use sizes s2 and s3, then overwrite the contents of directories s0 and s1 with the contents of s2 and s3, and then delete s2 and s3. Dont leave empty directories, or gaps in the numbers. And numbers must start from s0.

## Configuring the game

Setting the home directory has already been covered in the Starting QOMBI chapter.

Click the gear icon for the Config menu. The following items can be configured inside the game. (Some of these items cannot be configured while a game is in progress):

Colours Most colours can be changed. (The suit colours are configured separately - see Patterns, under) A colour picker, Qolour, pops up when you select this menu. DO the item you wish to change (table, side bar, message text colour, etc). Select the colour you like by DOing one of the colours in Qolour. You can do this repeatedly, until you are satisfied. Then go back and DO the next item you wish to re-colour. When you are done, press ESC, or, if in Qolour, press ESC or DO its title bar to exit the configuration. DOing the QOMBI title bar is different, as this is part of the Window Manager program interface: Each click on the title bar cycles to the next palette number. If you have a user palette loaded, this will be the fifth palette (ie #4). To terminate the selection, press ESC, or DO the Qolour title bar. Remember to save your settings if you wish to keep them! The suit colours of the cards themselves may be altered. The procedure is similar to the above: Click on a card of a given colour to change the colour via Qolour. Here you can choose the highlight colours to use. These are pre-defined and their colours cant be changed. A small selection are provided, and you can make your own, if you like (see below). Select the face of the face-side of the cards from the selection displayed. You can make more, if you like (see below). As above: Choose the back of the cards from the selection shown. Here you can set the speed of animation. At present only On or Off are available: If the Animation item is selected, it implies animation is On. HIT to toggle its state. DO to fix the state to whatever state is displaying. This also exits the menu. I assume that on slow machines, it is best to switch animation off. Reset all settings to their original (factory) state. (Or simply delete the config_dat file.) Save the changes you made.

Note: Save saves the current size, position, sound settings, and timer settings (on/off) too. However, changing any of these during a session, does not automatically trigger a prompt to save these changes when you quit. Only changes made via the Change menu will do that. However, if you wish to keep a changed size, position, or other setting, you can use the Change/Save menu to save those settings at any time.

### Locations

The home directory function provides for programs to know their own locations. However, QOMBI also needs to know the location of other data and programs. These need to be supplied in the locations_cfg file. This is a text file that must be edited in a text editor (or PRINTed from BASIC). No need to change anything until you know you need to, though!

The main reason for a separate locations file is to easily allow different configurations for different computers. For example, I mirror all my hard disks across the various platforms I use. But that would mean that when I backup my hard disk to another computer, I also overwrite the QOMBI settings and statistics that Ive built up on that platform. (This applies to other programs too, obviously.) This is not desirable! So, in my boot program I determine which computer Im using, and set a DEV device to point to a specific directory for each platform.

I wont do the full Monty here, as some of you will have found your own solutions, and for others, the matter may be from irrelevant to too esoteric. Briefly, then: Say I have two machines, IOTA and THETA, dev2_ will point to either win1_iota_ or win1_theta_, depending on which machine it is running on. So, I specify that my configurations files will be in dev2_qmb_ (while the QOMBI program and data files will be in the same location for both). That means I can have two different game histories (stats) and configurations, depending on which computer Im playing on.

The locations_cfg file must be in QOMBI's root/home directory. If none is found, a default locations file is created without complaint. It has the following format:

```QMBL01                        File ID - must be first thing in the file

udata  = dev2_qmb_            QOMBI user data @ win1_theta_qmb_
theme  = *etc_greenie_thb     Theme to use ( * => Qombi root dir )
qolor  = *etc_Qolour_obj      Colour configurator goes here
```

Lines starting on * and blank lines are ignored, as are anything following (and including) the first space after the specification. A leading * in the directory name implies root/home directory. Thus

```udata = *                     => default location = QOMBI root/home
..
```

Theme may be specified either as a directory or as a number between 0 and 3, thus:

```..
theme = 0                       => system theme #0
..
```

Only the = sign, and the order of appearance are significant, beyond what has been described.

Note: Only the binary theme format, _thb, is supported! If you mistakenly load a _thm file, it wont crash the program, but the display will look distinctly strange and will in all likelihood be unreadable.

You can find suitable themes at Bob Spelten's site (contact details below), or use his excellent QCoCo to create your own.

## Qolour

Qolour is the pop-up colour configurator. This program is not finished! Some of the features described below may not (yet) work. But the program should work well enough for the simple task of changing the colours here:

DO on the colour square to transfer that colour to the selected element on the game board. You can also DO any of the palettes to transfer that colour.

HITing the colour square "freezes" the colour so it can be modified by number.

With the colour "frozen" DOing one of the bottom row of user palettes, transfers that colour to that palette box. This also unfreezes the colour.

A frozen colour from the colour square, or any of the colours from the various palettes, can be "painted", ie modified, by manipulating the various colour component numbers:

HIT the R, G, B or \$ buttons to increment that component; DO the buttons to decrement. Or you can enter an RGB number via the keyboard.

There is a small demo program in the ..qmb_etc_ directory, Demo_bas that demonstrates how the Qolour program may be used. Just EXecute it to test.

## Troubleshooting

If you have just installed the game and it keeps crashing:

1. In your main system console, try running the included boot file from the home directory:
`LRUN <QOMBI_path>boot`
2. Try replacing your version of ptrmen with the one included in the home directory _bin subdirectory. If that doent help,
3. Replace your Qlib_sys or Qlib_run with the one provided in the _bin sub directory.
4. Make sure youve checked the relevant chapter in this manual!
5. If the problem relates to FDEL, see this note
6. Contact me. Details below.

Q Best Time is not updated although last time was better than Best Time

A Best Time is only updated if the score is among the Top Ten, otherwise you could have a lousy score, due to not playing properly, in a very short time! The Average and Total times, as well as the Score are, however, all maintained. So it doesnt pay to hurry to get good timings if the score is sub par.

## Design Changes

The card shapes and colours may not be very pretty! But at least you can change the them to (almost) anything you like quite easily. Its not hard to make new cards either. Here's how you set about doing that:

### Designing new cards

A set of cards consists of a number of sprites that all have the same dimensions. Each set is located in its own directory, named _s0.._sN. For the resizing scheme to work, the cards with the smallest dimensions must be located in the lowest numbered directory, the next largest in directory _dat_sN + 1, etc.

Each set consists of the following cards:

_f_Face_spr this is the basic card in the set. It can be used as the card face and as a card back. This card must exist in _dat_sN_. Since the cards are used "lying down", references to face card dimensions are width = longest dimension height = shortest. I have used the convention that the card width is about 1.5X the card height, ie Y = X / 1.5. The card is a mode 16 sprite, with rounded edges, which requires an alpha channel. RLE compression is ok too. The colour could be white or off-white for easy legibility, although this is not a strict requirement. Borders, etc are up to the designer. All cards are expected to have shading. 4 pix on the width and 3 pix on the height (ditto for the vertical cards). The shading is subtracted from most calculations involving the card size, eg for pattern placement. Only the first 12 face cards can be displayed for selection in the configuration screen. PlainV is the same card as above with a vertical orientation, ie it is rotated clockwise 90 degrees from PlainH, and must reside in the _sN_b_ directory together with any other backs for that size. Each vertical back is labelled with a V suffix, and must have a corresponding horizontal version, labelled with an H suffix. PlainV and PlainH must always exist. Theyre also used as the fallback backs, in case the configured backs dont exist for a particular size. Backs need to be pre-designed sprites of any mode. They must be of the same size as their respective face cards and, preferably, have rounded corners not significantly different to that of the corresponding face cards. Each back must come in two orientations: Horizontal and vertical. While the designs dont strictly have to be the same, they must have the same name with an H or V suffix. Thus the naming convention is _spr being the suffix V or H. Whatever the orientation, the shadow is always x4, y3 pixels. They must reside in the directory _sN_b_ Only the first 12 backs found in that directory can be displayed for selection in the configuration screen. This is a sprite of the same dimensions as the other cards in the set. It consists of a rounded border, one or two pixels wide. All the rest of the card sprite must be more or less transparent, so as to show the face of the card it is to highlight. The orientation is as for PlainH_spr. Two different kinds of highlights are supported: A full any-GD2-mode sprite with an alpha channel. This must then be called _spr and be located in the _sN_h_ directory. The first 12 such highlights found there may be viewed for selection in the config screen. A mode 16 blob, more or less as above. The colour is unimportant. This must be located in the _sN folder and be called HiLite_spr. This sprite must always exist for each size, as it is the fallback highlight. Its display colour will always be the same as the Timer and Score borders. ((2) above: Discontinued for now.)

Each card set also requires a set of patterns (or blobs, in QL parlance). These must be of a suitable size for the card on which they are to be projected. As a starting point I use the following relationships:

`Pattern height = 75% of the card height (approx)`

The pattern widths are little more complicated. Provided the standard patterns are used, ie Diamond, Oval and Rectangle, the following rules apply for esthetical reasons:

```        Diamond width   = X / 4
Oval width      = X / 4.5
Rectangle width = X / 5
```

The rules I use to space the patterns on the card are:

 One shape centred Two shapes pos of next shape wrt previous: card width / 3 - 4 pix Three shapes pos of next shape wrt previous: card width / 4 + 4 pix

For each card size, then, the following nine patterns (or some equivalent) must be prepared:

For each of Diamonds, Ovals and Rectangles: one of Empty, Shaded, and Full.

The features of each shape may be rendered in black, with the remaining areas transparent. It may be converted to a mode 16 sprite with a bit mask (not an alpha mask).

Although they neednt be diamond-, oval- or rectangle-shaped, they must be called:

DE_blb, DS_blb, DF_blb; OE_blb, OS_blb, OF_blb; RE_blb, RS_blb, RF_blb, and reside in the _sN_ directory.

You can use the SplitAll_bas utility, found in _cmb_uti_, to convert these sprites into blobs, thus saving some space. Or you can leave them as sprites: But they must still be labelled <name>_blb!

Card sizes and relative dimensions are irrelevant as far as the display mechanism is concerned: The display should be able to adjust accordingly, limited only by screen size.

In each size directory, you need to add a text file called _inf, ie _sN__inf. It must contain two numbers on separate lines, namely the CSIZE parameters to use for the deck counter and for the statistics display. (Look at an existing _inf_txt file for an example, if in doubt!) The CSIZE is a matter of taste, depending on the size of the cards, and therefore is not calculated.

### Making new cards

I used Windoze Paint to create the basic shapes, and then the versatile, free, Open Source graphics program, GIMP, to deal with transparency and convert them to PNG files, which Marcel Kilgus'es PNGconv could process into mode 16 sprites. (Paint doesnt do antialiasing of shapes, which is why they look somewhat crude. A better graphics program should give better results!)

However, other pathways may be possible too, even using only QL programs.

To make more fundamental changes to the program, you will need the source code. This is available by request. Contact details below.

## Acknowledgements

The inspiration for the game came from watching two of my grandchildren playing a game one of them was given on his birthday. I have no idea what the game is called, or what its rules are. It took me a few minutes to cotton on and when I got home, I wrote the first draft of this program. And that same evening, I had a playable version running.

Packaging it for general consumption took more than twenty times as long! However, I took it as an exercise in exploring colour, sprites and blobs under SMSQ/E. And what a revelation that was!

Thanks are due to a lot of people for the platform this whole thing runs on. While I have pilfered the odd bits and bobs here and there, the bulk of the code and design - and all of the bugs! - are of my own making.

QOMBI was written under QPC2 running SMSQ/E 3.34, using the QD text editor. It was compiled with the Q_Liberator compiler. The menus were designed and realised with the Easy Pointer toolkit and utilities. The toolkits were assembled with Qmac, with the aid of QMake. Soundfile, a toolkit used to access the QL Sampled Sound System (SSS) was written by W Lenerz. He also wrote the LED-drawing routine used in QOMBI. His SMSQmulator running under Windows was also used to test the program. QCoCo was used to design the palette. I used Windows Paint and GNU GIMP (under Windows) to draw the various graphic objects, and Marcel's PNGconv (a Windows program) to convert those objects to sprites. SOX, a utility to convert sound samples was used to produce the SSS-compatible sound files.

## Program Status

This program is Freeware, ©pjwitte 2oi8++ Source code available by request to those who wish to improve, repair or update the program.

## Contacts:

QPC2, EasyPointer, QD, and PNGcovert are freely available from www.kilgus.net Check out this site for the very latest in QL technology!

The latest incarnation of SMSQ/E can be freely had from the Official SMSQ/E Site: www.wlenerz.com/smsqe, and SMSQmulator from here: www.wlenerz.com/SMSQmulator

SOX can still be found at www.zen35309.zen.co.uk/qdos

QCoCo from Bob Spelten's site: http://members.upc.nl/b.spelten/ql/index.html

Q-Liberator, it seems, can be had from Dilwyn's comprehensive site: www.dilwyn.me.uk

pjw, December 28th 2018