Documentation file for !Hextris version 0.20



Hextris is public domain. It is dedicated to all those, who deliver true
quality public domain software.

This file describes the desktop game Hextris for the Acorn RISCOS range of
personal computers. The game is quite simply a variation of the grand
classic 'Tetris' game of the 1980s, though much harder. It is not necessary
to read this file in order to play the game, so if you don't care about
learning all the esoteric features of the game, just stop reading by the end
of this paragraph and get playing!

If you reached this paragraph anyway, you will probably want to know a
little more about the game of Hextris, so below is the table of contents of
this file, each line is the name of a section describing some feature of
Hextris.



Contents
______________________________________________________________________

Features
Gameplay
The Hextris Menu
Scoring
Extras
Technical
Disclaimer and Addresses



Features
______________________________________________________________________

Hextris is a desktop game, handwritten in assembler for smallness and fast
execution. Below is listed the main features of Hextris.

Fully multitasking game in RISCOS desktop.
Handwritten in ARM assembler, taking very little processor time.
Compact program (approximately 16KB).
User customisable. Settings can be saved.
Control by keyboard or mouse.
Adaptive to mode changes.
Optimised redrawing.
Permanent highscore table.


Gameplay
______________________________________________________________________

Open the Hextris game window by clicking on its icon on the iconbar. The
game is started by clicking the mouse select button within the game window.

Hextris can be controlled by either keyboard or mouse. The mode of control
is selected by clicking the corresponding item within the menu
'Hextris.Options.Control'.


Keyboard control
----------------
The control keys can be altered in the submenu of
'Hextris.Option.Control.Keys'. The default keys are as follows:

Z - left
X - right
' - rotate counter clockwise
/ - rotate clockwise
<space> - drop
H - toggle help
P - pause (click in game window to resume game)

The game can also be paused by clicking the mouse select button within the
game window. Note that Hextris will be paused if another application claims
the input focus of the Wimp.


Mouse Control
-------------
When Hextris is controlled by mouse, the brick is moved horizontally by the
movement of the mouse. The left mouse button rotate the brick
counterclockwise, while the right mousebutton rotates the brick clockwise.
The middle button drops the brick.

Pausing the game under mouse control is obtained by either closing the game
window or clicking the mouse adjust button in the Score/Help window. The
game is started/resumed by clicking the mouse select button within the game
window.

If Hextris is played with mouse, it does not claim the input focus of the
Wimp. This means that you can use an editor, while your girlfriend play
Hextris with the mouse.


Hextris can be customised in its appearance in a variety of ways. The
customisation is accessed in the submenu 'Hextris.Options'. The next section
will describe most of the other features of Hextris.



The Hextris Menu
______________________________________________________________

Below is a description of each item in the Hextris menu, ordered top-down,
as they appear on-screen.


Hextris.Info
The submenu of this item is the standard info box.

Hextris.Options
The submenu of this item provides access to the various options of Hextris.

Hextris.Options.Control
The submenu of this item is for selecting which control to use, either keys
or mouse. Clicking this item toggles between the two modes of control.

Hextris.Options.Control.Keys
Click this to select the keyboard for playing. The submenu of this item is
used for selecting new control keys. See the section 'Gameplay' for details.

Hextris.Options.Control.Mouse
Click this to select the mouse for playing. See the section 'Gameplay' for
details of how to control Hextris with the mouse.

Hextris.Options.Sprites
Clicking any of the four items in the submenu of this item, will change the
appearance of Hextris, by loading a new set of sprites. If you have designed
your own sprites, you can write the name of the spritefile into one of the
icons (See the 'Technical' section for further details). The four menu items
described below are the default names. 	 Hextris.Options.Sprites.medium
Click this to select medium size, multicoloured appearance of the bricks.

Hextris.Options.Sprites.large
Click this to select extra small size, multicoloured appearance of the
bricks.

Hextris.Options.Sprites.small
Click this to select small size, multicoloured appearance of the bricks.

Hextris.Options.Sprites.lhomo
Click this to select the large size, homegeneous coloured appearance of the
bricks. Note that this is a special variant and only applicable in 256
colour modes. There are also small and medium size versions of this, called
'shomo' and 'mhomo' respectively.

Hextris.Options.Size
The extent of the playarea can be controlled in the submenu of this item.

Hextris.Options.Colour
Click within the submenu of this item to change the background colour of the
playarea. Note that some bricks may be invisible, if the background colour
is the same as the brick.

Hextris.Options.Adapt mode
Click this item to toggle Hextris's automatic adaptation to mode changes.
When this option is set, Hextris will try its best to adapt to a mode
change, in effect ensuring a continuous fast update of the playarea. Note
that disc access will occur on modechanges, when this option is enabled. See
the section 'Technical' for further details.

Hextris.Options.Help
Click this item to toggle the help feature. You can also toggle the help
feature by clicking select within the Score/Help window.

Hextris.Options.Save
Clicking this item will save all the current settings of the options on
disc, such that Hextris will appear the same, next time it's loaded. All
options, which can be set within the 'Hextris.Options', menu are saved.

Hextris.Show
The submenu of this item controls opening of various information windows.
Clicking directly on this item, opens the Help/Score window.

Hextris.Show.Help
Click this item to open the Score/Help window. This window will display your
current score and the number of lines you have cleared. If the help feature
is enabled, the window will also show you the next brick to appear.

Hextris.Show.Statistics
Click this item to open the statistics window. This window displays how many
times each brick has occurred since you loaded Hextris.

Hextris.Show.Highscores
Click this item to open the highscores window.

Hextris.Quit
Click this to quit Hextris. Note that this item is only present on the
iconbar menu.



Scoring
_______________________________________________________________________

Scoring is awarded according to a rather complex scheme. All scoring is
proportional to the level of play, ie. how many lines have been cleared. For
each ten lines cleared, the level is advanced and the speed is increased.

The more lines you clear in one go, the more points you get per line
cleared. That is, clearing two lines in one go will yield a higher scoring
than clearing one line in two goes.

A small bonus is awarded for dropping the brick. The bonus is proportional
to the number of lines the brick was dropped.

When the help feature is enabled all scoring will be reduced by 25%, due to
the easier play.

If you have obtained a highscore, it will only be recorded, if the size of
the game area is such that the number of lines is less than or equal to two
times the number of columns.



Extras
________________________________________________________________________

Hextris has a number of shortcuts available, as described below.

Clicking the adjust mouse button on the iconbar will open both the game
window and the Score/Help window. Note that the Score/Help window is also
automatically opened, if the help feature is enabled.

Closing the game window with the adjust button will close all the windows of
Hextris.

Clicking the select button in the Score/Help window will toggle the help
feature.

If you have attained a highscore and Hextris is waiting for you to type it
in, you are free to close the Hexscores window or start a new game by
clicking in the game window. Hextris will then automatically insert the name
of the last highscorer into the list of highscores.



Technical
_____________________________________________________________________

This section describes the more esoteric features of Hextris. Reading this
section will, among other things, enable you to customise the appearance of
Hextris, by defining your own sprites!

Hextris includes a collection of spritefiles within the directory
'!Hextris.Sprites'. Each brick consists of four sprites, where each sprite
has the shape of a hexagon. A spritefile must contain at least three
sprites. Spritefiles are named according to the mode the sprites within the
file are defined in.

A spritefile is named 'BXY_abcdef'. We call 'BXY' the modeprefix. The
elements of the filename are as described below:

'B' is one of the digits '0', '1', '2' or '3'. The digit represents the base
two logarithm of the number of bits per pixel (BPP) of the mode the sprites
are defined in. That is, for modes with 16 colours, B equals '2', while for
256 colour modes, B equals '3' etc.

'X' is a digit '0', '1', '2' etc. The digit represents the XEigFactor for
the mode the sprites are defined in. The XEigFactor is the ratio between the
external horizontal resolution and the internal horizontal resolution. F.ex
in mode 12, the XEigFactor is one, while in mode 13, the XEigFactor is two.

'Y' is similar to 'X', though 'Y' represents the YEigFactor.

'abcdef' is a unique string, that is, a filename of at most six characters.


When the 'Adapt mode' feature is disabled, Hextris will scale sprites and
translate colours according to the current screen mode. Hextris will *not*
try to adapt to the current mode. This can effect slow update of the game
window. Hextris will only attempt loading of a new spritefile, if the
current spritefile is incompatible with the current screen mode. This is the
case when Hextris uses 256 colour sprites and the mode is changed to a 16
colour mode.

Otherwise, when the 'Adapt mode' feature has been enabled from the menu
'Hextris.Options', Hextris will, upon a mode change or a change of sprites
(from the menu 'Hextris.Options.Sprites'), try its best to adapt to the
mode. Hextris will try each of the following actions, in the order they
appear below.

1 Load the spritefile, whose name is ticked in the submenu
'Hextris.Option.Sprites', prefixed by the modeprefix of the current Wimp
screen mode.

2 Load the spritefile with the same name as above, but with with an optimal
mix of the default modeprefix and the modeprefix of the current screenmode.

3 Load the spritefile with the same name as above, but using the default
modeprefix.

4 Load the default spritefile.

5 Load the spritefile named '212_small'

When Hextris has succeeded in one of the above actions, the name of the file
loaded, is stored in the default spritefile name.

See the file '!Hextris.Sprites.!ReadMe' for further details of how to design
your own sprites.



Disclaimer and Addresses
______________________________________________________

First the utterly boring stuff...

Hextris is the exclusive copyright of Mads Meisner-Jensen. Hextris is Public
Domain and may be freely copied, provided that all files are retained, and
no changes made. No charge whatsoever for this software should be made under
any circumstances, including charging for public domain discs!

Hextris is used at your own risk. I, The author Mads Meisner-Jensen, cannot
accept any liability for any loss or damage arising from the use of Hextris

Any commercial use with the aim of profit of any part of this software and
documentation, in part or whole is illegal without my written permission.

The files included in release 0.20 are, in alphabetic order:

!Boot
!Help
!Hiscores
!Options
!Run
!RunImage
!Sprites
Sprites.!ReadMe
Sprites.112_large
Sprites.112_medium
Sprites.112_small
Sprites.211_large
Sprites.211_medium
Sprites.211_small
Sprites.212_large
Sprites.212_medium
Sprites.212_small
Sprites.312_large
Sprites.312_lhomo
Sprites.312_medium
Sprites.312_mhomo
Sprites.312_shomo
Sprites.312_small
Templates



Now some not so boring stuff...

If you have *any* comments, bug reports etc., please don't hesitate to
contact me. You can contact me via electronic mail or human mail. Please -
no phone calls. I read my e-mail almost every working day.

Mads Meisner-Jensen
Valdemarsgade 6, st.tv.
DK-9000 Aalborg
Denmark

e-mail: mmj@vlsi-gw.vlsi.auc.dk
