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


               A game to engage the other side of your brain
               ---------------------------------------------


        Introduction
        Game rules
        Using the program
                Requirements
                Installation
                Starting QOMBI
                Display and Controls
                Playing the game
                Scoring
                Shortcut keys
                Hint
                Tips and Tricks
        Configuring the game
                Locations
        Qolour - the colour configurator
        Troubleshooting
        Design Changes
                Designing new cards
                Making new cards
        Acknowledgements
        Contacts
        Program Status


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 home directory:
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
game 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 timed 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.)

Click the Query icon: Same as Hint (see below). (New as of V0.99)


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

If the table you are given doesnt look promising, provided no moves have
been made, you can click the deck again for a new layout. (New as of V0.99)

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
losing 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! - until the next replenishment.)

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
F1      - About
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 or ? 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.

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.

Note: If you have created your own symbol shapes the miniature may not be
representative anymore (you'd have to modify the miniature fount for that).
Also, if you have changed the card face colour the pattern may become
invisible due to lack of contrast.


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.
              If the game board fills most of the display you may not see
              it! Press CTRL+C to bring it into view!
              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!

Patterns    - 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.

Highlights - 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).

Face        - Select the face of the face-side of the cards from the
              selection displayed. You can make more, if you like (see
              below).

Back        - As above: Choose the back of the cards from the selection
              shown.

Animation   - 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       - Reset all settings to their original (factory) state. (Or
              simply delete the config_dat file.)

Save        - 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 irrelevant or 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 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 home 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 home directory. Thus

udata = *                     => default location = QOMBI 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. Contact me. (See Contacts page.)

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.

If you have a negative Lost Count, this was due to a bug now hopefully
fixed. If you wish to remove the stain from your score file, you could
try running the _uti_ResetLost_bas program. Make a copy of your original
_stats_dat file in the same directory, eg

        copy_o <path>'_stats_dat' to <path>'_stats0_dat'

then LRUN the ResetLost utility on stats_dat. If all went well, fire up
QOMBI and check the stats. If all looks well, quit QOMBI again (resaving
any previously saved game!). If your scores have been messeed up somehow,
restore stats0_dat to stats_dat and let me know what went wrong!


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.

_b_PlainV_spr   - PlainV is the same card as above with a vertical
_b_PlainH_spr     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           - 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 <back name><S>_spr
                  <S> 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.

_h_HiLite_spr   - 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:

                  1. A full any-GD2-mode sprite with an alpha channel.
                  This must then be called <name>_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.

                  2. 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.

Of course, if you make new symbol shapes, you may also wish to change the
minature representations of those shapes (as used in the Hint feature).
Look at the fntDRO_asm file for details on how to do this.


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.


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 be found at Dilwyn's: https://sinclairql.net/djw/sound/index.html
as can Q_Liberator: https://sinclairql.net/djw/qlib/index.html

QCoCo from Bob Spelten's site: https://home.hccnet.nl/b.spelten/ql/


Program Status
==============

V0.90, pjw, 2018 Dec 28, first release into the wild
V1.00, pjw, 2026 Apr 06, better error trapping

          Conditions of use and DISCLAIMER as per Knoware.no
