                          ___      __  ____
                         / _ \____/  |/  (_)__  ___ ____
                        / // /___/ /|_/ / / _ \/ -_) __/
                       /____/   /_/  /_/_/_//_/\__/_/
                       ____________________________
                      /___/___/___/___/___/___/___/


                 A Minesweeper clone for advanced QL systems

                               pjwitte 2oo4..2o23+


Contents:
        System requirements
        Disclaimer
        Manifest
        Getting started
        Configuration
        Troubleshooting
        Limitations
        Acknowledgements
        Conditions
        Contact details


System requirements:
--------------------

Requires SMSQ/E 3.3x or better, with GD2 (colour drivers), QMenu by JMS,
and the ptrmen V4.10+ runtime toolkit from AHS/MK. (See below for details.)
Mouse. Sampled sound system optional. Hard disk recommended.


Disclaimer:
-----------

The program is supplied 'as is'. I make no claims as to the suitability of
this program for any purpose. It is guaranteed NOT to be bug free, so it
could potentially harm your system.

Repetitive Strain Injury [RSI] risk!! Please make sure you know what this
means and take adequate precautions to protect yourself and your
dependents!

                             Use at own risk!
                             ================


Manifest:
---------

        dmr ->
            D-MinerX_obj    Game with line numbers and toolkits included
            D-Miner_obj     Game with only indigenous toolkits
            Readme_txt      This document
            colsq24_spr     Dynamic run-time extension
            dminer_thm      Palette data
            Choice_obj      A utility program
            Help_obj        Another utility program
            QLib_run        QLiberator runtime toolkit

            hlp -> ...      Help file sub-directory
            snd -> ...      Sound sample sub-directory
          * src ->          Some basic development files (no asm!)
                D-Miner.htm SBasic source code (Best viewed on your PC!)
                MINES_BIN   M/c toolkit, sprites and menus
                TIMER_BIN   The TIMER Thing

* Not included with some demo distros due to space restrictions.


Getting started:
----------------

Unzip the distribution file into your normal games directory, eg (Info-ZIP
syntax):

        EW 'unzip'; 'ram1_DMinerXXX_zip -d win1_game_'

where DMinerXXX_zip is the distribution file. This will create a new sub-
directory, 'dmr', eg 'win1_game_dmr_', and the required sub-directories
under that, and copy the files to their respective locations.

NB! This will overwrite any existing files in folder dmr_, so if you wish
to keep an existing theme or config file, take the necessary steps to keep
them safe and restore them.

If your system sports the Home Directory Thing, the program will use that
to find its own location. Otherwise see the Configuration section below.

If you normally load the following toolkits/utilities at boot up:

        ptrmen_cde      or equivalent (also available as part of Qwirc on
        my web site (see Contact Details, below), and
        sound_bin       Soundfile extensions by Wolfgang Lenerz (see
        contact details, below)

then use D-Miner_obj. In all other cases use D-MinerX_obj. The QLiberator
runtime toolkit or equivalent, and Qmenu must always be loaded, as they
are also required by the auxiliary programs:

        qlib_run        or equivalent
        menu_rext       included with most PE programs from JMS (see
        contact details, below) and


To run the program:

        EX 'win1_games_dmr_D-Miner_obj'
or
        EX 'win1_games_dmr_D-MinerX_obj'

D-Miner comes pre-configured to run from ram1_ so if you unzip it and run
it from there, and you have the required extensions loaded, you should
easily be able to try it out.

Most menus have help files (press F1 or click the ? icon) to get you
started.

Note: Some system palettes (including the standard defaults!) render the
help text invisible! This is a feature of QMenu (IMHO) so there is little
I can do about it. However, D-Miner now comes with its own palette set as
default, so use that. Or get the excellent QCoco (see contact details,
below) and create your own.


Configuration:
--------------

The program relies heavily on various external utility files and needs to
know where to find them. SMSQ/E versions above 3.12 implement the
Home directory Thing. Other file management programs are catching up, eg
FI2, but not all, eg Qascade (at v 1.13). If you use Qascade, and perhaps
other program launchers, they may not be Home directory aware. In these
cases you must configure the binary using Config or Menuconfig to set the
Home directory. These programs are not included here but may be found
on-line. See contact detais below.

It is possible to specify different names and locations for some of the
resource files, eg the Help_obj and Choice_obj utility programs, as these
may be used by other programs also. The sound file directory may also be
relocated if so desired. At present these changes can only be made by editing
the configuration file with a text editor. The File location section could
look like this:

* - File locations

Help              : *
Message           : *
ColourSquare      : ram1_dmr_colsq24_spr
SoundDir          : ram1_dmr_snd_

Here the Help and Choice message programs are marked '*', which means 'use
default name and default location'. Here this means "Help_obj" and
"Choice_obj", and they are expected to be found in the D-Miner home directory
(as configured or Home Directory proper). Had you wanted to specify a different
utility or location youd have to include the complete file name, eg

                    win1_util_menu_HelpUtil_obj
                    win1_util_menu_ChoiceUtil_obj


Troubleshooting:
----------------

If you try D-Miner_obj and any of the required toolkits are missing
the program will probably unceremoniously crash! Either load the missing
toolkit and try again, or see if using D-MinerX_obj helps.

After that, most startup and runtime error conditons are likely due to
D-Miner failing to locate its external utility and resource files. See
the section on configuring D-Miner, above.


Limitations:
------------

This demo doesnt do scores and statistics

Some functions are not yet implemented

Sound quality on the Q60 has not been properly tested yet

If you dont have a hard disk, you could copy the sound files onto ram disk
and configure the program to read the sound files from there instead.

Many inconsistencies and idiosyncrasies!

The program may be under development, but probably not by me.

D-Miner is only co-incidentally a game: It is first of all a fun GD2
programming project!


Acknowledgements:
-----------------

All code is original and my own, with the following exceptions:

A public domain sub-routine or two by Tony Tebby is included in the
toolkit.

Wolfgang Lenerz' sound extensions, LED display and Native colour
conversion routines (N2RGB) are included.

Marcel Kilgus'es system palette is included as D-Miner's default palette.

Please note: QMenu is a commercial product and is not included in this
distribution! It can be obtained via JMS or Quo Vadis Design. See contact
details, below.

The program was written in SBasic with QD, on QPC2 with SMSQ/E. I also
used Albin Hessler's excellent EasyPTR II menu development suit (now re-
released, maintained and much improved by Marcel Kilgus). It was compiled
with QLiberator. The inclusion of the run-time toolkit, QLib_run v3.35,
1991 Liberation Software, and the ptrmen V3.50E runtime extensions,
1991-1997 Albin Hessler Software, and WolfSoft's Soundfile toolkit, is
gratefully acknowledged. (The latter two toolkits are compiled into D-
MinerX_obj while D-Miner_obj excludes these for you to provide your own at
boot time.)

Thanks to Marcel Kilgus, Wolfgang Lenerz, Franois Van Emelen and others
for testing, advice and input!

Some sprites and sound samples from unacknowledged sources may also have
been included..


Conditions:
-----------

Versions < 1.00 may be used, copied and distributed free of charge. It,
and the whole package are copyright pjwitte 2oo4..2ol6.

This distribution may be freely copied and distributed, provided that:

1) suitable acknowledgement is made of the original authors,

2) this distribution is disseminated intact *,

3) this distribution is not altered in any way without being clearly
marked,

4) these conditions are not altered or removed,

5) any money, goods or services charged over and above legitimate
distribution costs are sent directly to me, unless otherwise agreed.

* Any source code may be omitted in demo distros where the main purpose is
  to have an unzipped playable game demo. The main program source code must
  be included in any zipped download version.

The complete source code may be made available on request to those who
wish to add facilities, etc. For the source code distribution additional
rules apply.

Important! Please report any bugs, unclarities etc, in the program,
manual, or other files, to me!


Contact details:
----------------

If you want to report a bug, please ensure you're reporting on the latest
version! Get it where you got this version!

Include the version number, your platform details (eg QPC V4.00), a brief
description of the problem, any files required to produce the symptoms,
and your contact details.

Suggestions for improvements are gratefully accepted. If you wish to
improve the program yourself you will require your own copy of EasyPTR and
QLiberator and perhaps additional source file from me. The Sbasic main
program source file included, used together with the indigenous toolkits,
makes some developments and corrections possible. The main licensing rule
is: Dont pass my work off as your own, for shame, glory, or profit,
otherwise you may do pretty much with it as you please.

  A final word: If you like it, tell the world! If you dont, tell me!


V0.25, pjw, 2026 Jan 15


Jochen Merz Software: http://smsq.j-m-s.com/  and
Quo Vadis Design:     http://www.ql-qvd.com

                      QMenu and MenuConfig are normally included with many
                      commercial programs using the Pointer Environment,
                      or sold as a fully documented package for using them
                      in your own programs.

Marcel Kilgus:        http://www.kilgus.net/

                      Want your QL to be the best QL it can be? QPC is the
                      world's most sophisticated QL environment, run from
                      the comfort of a modern PC. This is where you can
                      get it. Best of all it is now free!

                      Marcel has some great colour themes and system
                      sprites on his web site for downloading. Gives
                      D-Miner - and everything else - that polished look.

Bob Spelten/          http://members.upc.nl/b.spelten/ql/
Wolfgang Uhlich:
                      QCoco, the palette configurator, and other
                      GD2-related programs can be found here

Dilwyn Jones:         http://www.dilwyn.me.uk/

                      The largest repository of QL software and
                      information on the planet. If its legal, youll
                      almost certainly find it here! My link to Wolfgang
                      Lenerz' site for downloading soundfile, the sound
                      extensions toolkit, is broken. However you can find
                      it here.
