Help file for Angband (and Variants), port version 1.25 and later
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
RISC OS front-end by Musus Umbra, 1998-9.

This file last modified: 27.06.99

Please read this file, and any other ReadMe files supplied.  This file
documents things specific to this port, the others will concern the actual
game itself.

If you need help once the game is running, use the '?' command to access the
online help system.

Please note that this file describes both standard Angband and the various
variants compiled with my front-end.  If you've got one of the variants,
please substitute the obvious things in this text (eg. !Zangband for
!Angband, etc) as you read it :)



>> Contents
```````````
   Main Features
   Starting the Game
   Windows & Terms
   Fonts
   Full Screen Mode
   Panic Saves & Gruesome software bugs
   ! Menu
   Alarm
   File Cacheing
   Command line options
   Sound
   Using savefiles from earlier versions
   Upgrading from earlier versions
   Filetype clashes
   How Keypresses are Encoded
   Differences to K.Bracey's port
   Credits
   Disclaimer
   Contact details



>> Main Features
````````````````
Uses ZapRedraw for a fast but flexible screen display.

Supports 8 Terms, each of which may use a different font.

Full Screen mode (especially good for slower machines).

Will automatically use Zap's fonts if they are available,
otherwise the system font and a small selection of Zapfonts
is provided (including a special version of my 'Moogle' font).

Some helpful macros predefined.

Sound effect support (you'll also need Rick Hudson's PlayIt module, which
is supplied along with some sample sounds in the AngSound archive
available from my web-pages).

The code itself is RISC OS 2 compatible but the distributed executables
aren't (they need a newer SharedCLibrary than RISC OS 2 can support).  If
you need a RO2 version please contact me. (Yes: there are still machines
in use using RO2...)



>> Starting the Game
````````````````````
The game can be run by either double-clicking on a saved game in a filer
window, or double-clicking on !Angband itself.

If the game is run without a saved game (eg. just by doubleclicking on
!Angband, etc). then a window will appear asking you to specify where you
want to keep your saved game.  (The '!Angband.Lib.Save' directory will also
be opened - this is the 'default' place to store games, but there's no reason
you have to use it).

If you've already got a saved game, you can drag it to this window (or double-
click on it) to use it.

If you're starting a new game (ie. about to roll-up a new character), then
ammend the name and drag the file icon to where you want to keep the saved
game.

The starter will refuse to allow you to overwrite an existing file and will
check that it's possible to create a file with the specified name in the
specified location - this is simply a safety check to help avoid losing
saved games.

!Angband will then be run using the saved game specified (if it's a new
character, you'll be prompted 'Savefile does not exist' by Angband;  Don't
worry, Angband will save your character in the right place when you quit or
save).

Of course, if you double-clicked on a saved game directly then Angband will
start straight up.

If you hold down either Ctrl key whilst starting the game then the game's
Lib.user directory will be opened instead.  This is where Macros, pref files,
character and screen dumps are saved and so it's handy to be able to get to
it without "digging".




>> Windows & Terms
``````````````````
This port supports the standard eight 'Terms'.

You can open any Term window using the 'Windows>' submenu of the menu that
appears if you click Menu over a Term window.  This menu also allows you to
close Terms if they are already open.

The 'default' Terms are opened when you click Select on the iconbar icon.
The main Angband window is always open by default.

If the main Term (whose title is the name of the game being played) is closed
by clicking Select on its close icon then all the other Term windows will be
closed too.  Closing the main window from the Windows menu, or by using Adjust
won't close the other Term windows.

When a Term is closed, its position (and scroll offsets, etc) are
remembered.  If the Term is reopened it will reappear in the same place, etc.
that it was last open.

You can save your preferred window layout (and font choices) with the 'Save
Choices' entry in the iconbar menu.

To actually get Angband to use the Terms you need to tell it to do so using
the (W)indow Choices section of the options (press '=' to get to the options).





>> Fonts
````````
By default, all Terms use the system font.  You can select a different font
for use in a Term by using the 'Font>' submenu from the main Term menu.

If !Zap (or !ZapFonts) has been run (or seen by the filer) then this menu
will contain all the fonts installed in !Zap(Fonts).  If not then only the
limited selection supplied with the port itself will be offered.

It's worth remembering that large fonts not only redraw more slowly than
smaller ones, but also take much more memory (especially in 32,000 or more
colours).  Fonts that are 8 pixels wide should redraw quickest (and are
suitable for full-screen use... more later).

If the system font changes (eg. due to using my !IMBgfx thingy, etc.) whilst
the game is using it, the windows won't reflect this.  To make the game
notice the changes, simply re-select the system font from the menu.

I'm afraid that there is very little I can do about 'missing characters' in
fonts, etc.  If you want to use one of the PC style graphics characters, for
example, then unless the font you're using defines those characters the display
will be a mess.  Either change your visual preferences (the % menu in the
game) to use characters that are defined, or choose a more suitable font :)

Whilst you're free to use a different font in every Term if you want, this
will eat memory so it probably isn't a good idea unless you have memory
to spare.





>> Full Screen Mode
```````````````````
In full screen mode, the game completely takes over the machine and screen.
This allows the game to run a lot faster and is particularly useful on older
machines.

To enter full screen mode, either select it from the iconbar menu, or Adjust
click on the iconbar icon.

It's possible to make the game start up in full screen mode automatically;
the user options menu (press '!') allows fullscreen/desktop play to be
selected (and saved) as an option.

In full screen mode you can only use the main Term (ie. the game window).
The other Terms will be ignored until you return to the desktop.

NB: No multitasking occurs in Full Screen mode.

To return to the desktop, press f12.  (A little reminder of this, and the
current date/time are shown in dark-grey at the bottom of the screen).

The screen mode used will be either 27 (VGA, 640x480 or some higher
refresh-rate equivalent on RiscPCs) or 12 (TV, 640x256) if your
monitor/system can't support mode 27.

If the main Term's font is 8 pixels wide by 16 (or fewer) pixels deep then it
will be used for the full screen display.  If using mode 12, then the font
must be 8 pixels wide by 9 (or fewer) deep.

If the main Term's font is unsuitable then the system font will be used
instead.

If mode 27 is being used and the System font would be used then an attempt
is made to use a Zapfont called "FullScreen" in !Angband.Lib.xtra.  If this
font is found and is a suitable size then it will be used instead of the
system font (my "MooglePC" font is supplied installed in this position).

In high-res full screen mode (ie. screen mode 27), the font will be scaled to
double height if it is 8 (or fewer) pixels tall.

In fullscreen mode, the screen palette is explicitly set to the first 16
colours in Angband's colour table.  Colours>15 are displayed as the best
match from the first 16 colours.

NB: a recent version of IClear can interfere with the action of the
cursor keys whilst Angband is running in fullscreen mode.
If you find that this happens and can't cope with it you can add a -E to
the !Options file (see later) to enable an Evil Workaround for this problem.
The workaround is VERY nasty (IMO) though so don't use it unless you find
you absolutely have to.



>> Panic saves & Gruesome software bugs
```````````````````````````````````````
If Angband crashes it will attempt to save your game before exiting.
This is called a 'panic save' (the 'Gruesome software bug' is a reference
to the message the game displays before attempting the panic save).

Normally this panic save would overwrite your savefile.  This can be
disadvantageous, however, since it's possible that things have gone
badly enough wrong to make the savefile unusable.

My ports will automatically substitute the name "!!PANIC!!" for the name
of your savefile should a panic save occur.  This should help to prevent
losing promising games due to bugs and/or crashes.

Note that you shouldn't use the !!PANIC!! savefile without first renaming
it (just in case another panic save takes place).  You should also keep
the original savefile until you are completely satisfied that the panic
saved one isn't broken in any way.



>> ! Menu
`````````
The 'user' menu (ie. specific to the RISC OS port) is accessed by typing
a ! at any time a normal command would be acceptable.  Some of the options
available in this menu are also accessible via the game's iconbar menu.
Adjusting the options with the ! screen and iconbar menu options at the
same time is not big or clever, although it shouldn't break anything.

Simple instructions are given on the screen itself.

"Gamma correction" allows you to correct the display colours if they look
too bright or dark on your monitor.  Note that you must use the game's
own colour modification system (the & command) to adjust the actual colours.

"Force Monochrome" is a quick workaround for running the game on a monochrome
monitor - it prevents any colours other than 0 and 1 (ie. black and white)
from being used.  This can be handy since not all variants
support a "use_colour" option themselves (eg. Angband 2.8.3 doesn't).

"Sound effects" enables/disables sound effect support.  Note that for
sound effects to work you should install !AngSound (or set things up
as detailed in the !AngSound documentation).

"Sound Volume" only applies to sound effects;  the game's own 'beeping'
is always done at the normal system volume.  Note that volume levels
below 127 make the sound quieter whilst values above 127 actually amplify
(and probably distort) the sound.

The "Start fullscreen" option can be set to enter full-screen mode and
request that Angband enters full-screen mode automatically when run (as
long as you don't forget to save the options...)

If "Use hourglass" is on then the game will turn the hourglass on when
a delay of more than about half a second occurs.

If "Hard flushing" is on then the game will wait until any pressed keys are
released when told to flush its input buffers.  If you often hold keys
down (eg. movement keys) and find that when you are 'disturbed' you can't
stop yourself in time this option may help you.



>> Alarm
````````
The user menu also provides a *very* simple alarm system...  It's far too
easy to miss important events (bed time, TV programs, weddings, etc.) due
to being engrossed in Angband.

Normally I'd use !Alarm to remind me of these things but in full-screen
mode this won't work since the game has exclusive use of the machine so
!Alarm doesn't get the chance to 'go off' until I return to the desktop.

Now, if /you/ were married to the delectable Charis (see her webpages
at http://www.argonet.co.uk/users/musus/doulos/) you wouldn't want to
stay up until 3am, wasting three valuable hours of snuggle-time, just
because you were too engrossed in the game, would you?

Anyway, there are two types of alarm available: one-shot alarms (which
only go off once) and repeating alarms which go off at the specified time
every day.

Note that the alarm system is *very* crude: if the game isn't running when
the alarm is due to go off then nothing happens.


>> File Cacheing
```````````````
Some Variants (notably Zangband and its derivatives) make use of some
files on disc to generate 'random' messages and names.  Unfortunately
they typically do it in a fashion which can be very slow under RISC OS.

To help with this my front-end implements its own file cacheing (if
appropriate to the variant) which can eliminate almost all disc accesses
when the game tries to look these messages up.

Because one or two of the files used like this are typically quite
large (eg. Zangband's rumours.txt file is about 40Kb) the cache
normally compresses their contents when loading them.  Since this
compression is moderately slow (unless you have a StrongARM, of
course...) the system will also then save the compressed data so that
when it next needs that file it can just load the ready-compressed
version.  By default these compressed files will be deleted when you
quit the game although you can override this - see below.

The actual compression used isn't terribly good, but it is enough
to make a difference and (most importantly) uses very little memory.

Also, since Zangband 2.2.5+ uses these files in a slightly more
complex way than other games it's possible to make the file cache
a bit 'smarter' about what it actually stores.  By taking advantage
of the format of the files the system can save a little more memory
and time.

If for some reason you want to disable any of these aspects of the system
the -c command line option (see below) allows this.

Note that these options have no effect on variants that do not
support them.



>> Command line options
```````````````````````
It's possible to specify some command line options to the game.  This is
done by creating an Obey file in the game's directory (eg. !Angband) called
!Options.  The file should read:

     set amhd__flags ...

Where the '...' represents the options you want to specify.

The (useful) available options are:

    -F (for -fullscreen)
        Start the game in full-screen mode.  This overrides any setting
        in the 'normal' options (ie. those set from the user menu).

    -%%2
        Saves a file in the Lib directory that shows sound mappings, etc.
        This can be useful if you're having trouble getting sound working.

    -c
        Controls the file-cacheing system (if present).
        After the -c you may specify any or all of the following
        modifiers:

            S    Enable 'smart' file cacheing.
            s    Disable 'smart' file cacheing.

            A    Enable compressed file cacheing if possible.
            a    Disable compressed file cacheing.

            F    Make compressed file cacheing faster by storing
                 the compressed data on disc.
            f    Don't create/use compressed files.

            P    Scrap files are persistent (ie. not deleted).
            p    Scrap files are deleted when quitting.

           <n>   (ie. some decimal number) Specify the maximum
                 amount of memory to use when cacheing files (in Kb).
                 Note that the system uses as much as required but will
                 /try/ not to use more than this.
                 Specifiying a size of 0 disables file cacheing.

        See the section on File Cacheing (above) for more details.
        Note that not all games/variants support, or even need, this
        feature and will ignore all these options except P/p, although
        that isn't likely to be very useful... 


NB: The !Options file (if present) can override *all* the command line
arguments to the game so do be careful, please...




>> Sound
````````
This port supports sound.  In order to use it you'll need to use !AngSound
(available from my web pages).

Actually, you don't /need/ to use it, but there's a lot I'd have to
explain here in order to give instructions on how to set sound up.  !AngSound
contains the necessary information (and also serves as an example) if you're
dead set on doing it your own way :)

You can turn sound effects on/off and adjust the volume level at any time
by using the iconbar menu or the in-game ! menu screen (see above).

The volume setting can range from very quiet through to /amplification/
of the sound effects.  A volume setting of 127 is full volume; any higher
will amplify (and probably distort) the sounds, any lower will make them
quieter.

In the sound options window available from the iconbar menu you can tell when
the slider is representing a volume of more than 127 because it will turn red.




>> Using savefiles from earlier versions
````````````````````````````````````````
I suggest you take a backup of your current version (and savefiles) - if you
don't like this version (or have problems) you'll be glad that you did.

Sometimes the game itself has bugs that can cost you your savefile, and
sometimes there's a lingering feature in my front-end that could do the same.

*Always* take a backup of your savefile(s) before upgrading, please.
There's often very little that can be done to recover a savefile that
gets broken.

Savefiles should normally have the following filetypes:

           Filetype     Game
                118     Angband
                119     Sangband
           [1]  009     Quangband (*)
                010     Yin-YAngband (*)
           [1]  011     Goingband (*)
           [3]  012     Cathband (*)
           [3]  013     Ang/64 (*)
           [1]  014     Ingband (*)
           [3]  015     Drangband (*)
           [1]  016     GSNAngband (*)
           [1]  017     Rangband
           [1]  018     GW-Angband (*)
                019     Zangband (*)
                01A     Kamband (*)
                01B     Cthangband (*)
                01C     Oangband (*)
                01D     Pziband (*)
           [2]  01E     PernBand (*)
                01F     Kangband (*)


Notes: the types marked with an asterisk are in no way official.
       They just seemed to be logical choices and didn't seem to
       clash with anything.

       [1] Ported by Thomas (t.harris@iname.com, or hotseat@argonet.co.uk),
           available from http://www.argonet.co.uk/users/harris/angband/

       [2] Latest port by Henry Helliwell (Henry@stohelit.demon.co.uk),
           available from http://www.stohelit.demon.co.uk/angband/

       [3] Currently being ported by Thomas...  hopefully they'll be
           available soon from the address in [1].


       All others ported by me (musus@argonet.co.uk),
       available from http://www.argonet.co.uk/users/musus/angband/



You can use savedgames created by DOS/Windoze/UNIX/whatever versions of
the game by giving the file the appropriate filetype.  Please note that
not all games will load savefiles from older versions (AFAIK, only
Sangband 0.9.5 and some newer versions of Cthangband are particularly
affected by this).


Angband:
        If you're currently using 2.7.8, then your saved game(s) will be in
        !Angband.Lib.Save and be data files.  Copy them to a better place and
        set their filetype to &118.

        If you're using Archimedes Angband 1.2 (PC Angband 1.40, or
        2.4.frog-knows) then your saved game will be in !Angband.Files.
        You'll need to copy it out of there and set its type to &118.

Sangband:
        Version 0.9.5 of Sangband is incapable of loading savefiles from
        earlier versions.  Apparently this is due to the nature of the
        changes to the game - sorry :-/

Cthangband
        You may find that loading an old savefile (ie. from before 3.1.0)
        into a newer Cthangband gives an error.  If so, it's possible that
        going back to the town (using the older version) and killing
        all the inhabitants and then resaving will allow the newer
        version to load your savefile.
        NB: Keep a backup!

Kamband / Zangband:
        AFAIK, any saved games you have will work OK.  You may need to
        change their filetypes though.

Oangband:
        As I understand it, Oangband can convert standard (vanilla) Angband
        savefiles into Oangband savefiles in order to allow you to
        move an Angband character over to Oangband.  To do this, make
        a *copy* of your Angband savefile and change its filetype to
        &01C.


>> Upgrading from earlier versions
``````````````````````````````````
        It's probably best to install a completely fresh copy of the
        game when upgrading.  This can help to avoid some potentially
        nasty problems caused by having a mixture of files from the
        old and new versions.

        You can then copy the relevant files from your old installation
        of the game into the new one if need be.

        Files you may wish to do this with (if they exist) are:

                !Angband.!Options

                        See the command line options section for details
                        of what this file is for.  Most people don't
                        need to worry about this file.

                !Angband.Lib.Xtra.Choices  and
                !Angband.Lib.Xtra.Alarm

                        These are your choices files (they specify such
                        things as the window positions and font selections).

                        Note that for machines using a RiscPC style !Boot
                        you shouldn't have to worry about these files
                        since they will be kept in !Boot.Choices rather
                        than inside Angband itself.

                Any .prf files you have created or modified in
                !Angband.Lib.User.

                Any savefiles you keep in !Angband.Lib.Save.



>> Filetype Clashes
```````````````````
        As the number of Angband variants ported to RISC OS increases, so
        too does the number of filetypes required for their savefiles.

        To the best of my knowledge, only the original Vanilla Angband
        filetype (&118) is official, although Zangband's &119 may also be.

        We've assigned filetypes to the other variants in a fairly logical
        manner and trying to avoid filetypes that we know other applications
        use.  We've also deliberately made the front-end code in such a
        way that it's trivial for the user (ie. you) to change the filetype
        the game uses if you do find that you have a clash.

        To make the game use a different filetype you'll need to do
        the following:

                1.  If you don't already have a !Options file for
                    the game, create one (see the secion on command
                    line options).

                2.  Add a line to the end of the !Options file which reads:

                        set amhd__filetype XXX

                    where 'XXX' is the 3 digit hexadecimal filetype you
                    want to use.

                3.  Edit the game's !Sprites and !Sprites22 files to
                    reflect the filetype you've chosen.




>> How Keypresses are Encoded
`````````````````````````````
(this section is only relevant to you if you write/modify .prf files
by hand)

When a key is pressed, its Wimp key-code is sent to Angband.  For 'simple'
keys, this is all that is required.

Keys whose code is >255 must be sent encoded, however.  This is achieved by
sending 31 (^_) followed by the three hex digit keycode (in upper case) and a
carriage return (13).

Code 31 is also sent in this way (ie. as ^_01F\r)

Eg. code &18a (tab) is sent to Angband as: ^_18A\r so to map this onto the
action \e\eAf\r (which is handy if you have the Phial of Galadriel) you could
use the macro definintion:

A:\e\eAf\r
P:^_18A\r

(the \e(scapes) are there to allow the macro to work at a 'more' prompt, for
instance).

The numeric keypad is treated specially too...

If a number is typed then the front-end looks at the state of the shift and
ctrl keys.  If shift is down then &800 is added to the code.  If ctrl is down
then &400 is added (so &C00 is added if both are down).

The pref-acn/prf file supplied uses this to map shift-keypad onto 'run',
IYSWIM.







>> Differences to K.Bracey's port
`````````````````````````````````
If you've previously used Kevin's port, there are some significant
differences you need to be aware of when using mine:

   There is no 'File>New' menu in my port.  Instead there is the 'savefile
   location' thing used if the game is started without a savefile.

   There is no support for dithered colours.  This might make your game
   colours look slightly different in 256 (or fewer) colour modes.
   In full-screen mode the colours will be exact (on RPCs) or as close
   as possible (on pre-RPCs).

   (Desktop) screen handling can be slower in my port - this is
   unavoidable:  Kevin used well optimised routines to redraw the window(s)
   in his port.  Sadly (due to using ZapRedraw) I can't get away with
   quite such clever tricks :-/

   Some macros are predefined.  You can, of course, override these in your
   own .prf files.  Specifically:

       Shift-keypad is mapped onto .<direction> (ie. run in the given
       direction).

       Ctrl-keypad is mapped onto +<direction> (ie. open/close/tunnel/attack
       in the given direction as appropriate).

       Shift-Ctrl-keypad is mapped in the same way as ctrl-keypad.

   The format of the Choices used by my version is very different to the
   format used by Kevin's.  My port will ignore a choices file saved by
   Kevin's.  I'm not sure if his port will ignore one of my choices files or
   not.

There are some deliberate similarities too:

   Key presses are handled in the same way; specifically: function keys
   and shift/ctrl/keypad key presses are treated in the same way.  This
   means that your macros (in .prf files) should still work the same.

   Quitting using the 'Quit' entry in the iconbar menu will save your game
   before exiting (just as ^X does).



>> Credits
``````````
Ben Harrison and the variant authors/maintainers (for obvious reasons).

Dominic Symes for the ZapRedraw module (used with permission).
ZapRedraw is (c) Dominic Symes and really rather nice.

The authors and editors of DeskLib (the freeware C library for RISC OS
machines) which this port uses [highly recomended].

The beta testers and those who've given me useful feedback, especially:
Thomas Harris, Matthew Somerville, Richard Greenwood, Lady Charis,
and Andrew Hill.

R. Fred Williams and Michael Rozdoba (for a spot of timely help concerning
an omission from the PRM :)

Toby Haynes (for the excellent Angband icons - I recoloured the Variant icons
so if you don't like the colour it's my fault).

The other porters, particularly Thomas Harris and Henry Helliwell.

Kevin Bracey (for originally porting 2.7.8, etc.  I used his port as
a 'springboard' to get my original prototype working before writing this
version from scratch).  Oh, and for releasing the full Zip2000 so I don't
have to implement V6 stuff in my Frotz port in order to play Zork Zero :)

Lady Charis (for putting up with me and making me countless cups of tea :)

Copyright information concerning the fonts is contained in the file
!<game>.Lib.xtra.Copyright.



>> Disclaimer
`````````````
There is no warranty of any kind.  The authors cannot and will not be held
responsible for any loss/damage arising from the use of, or inability to use
this software.

It is the user's responsibility to determine the fitness of this software
for any purpose they put it to.

Please read the copyright notices, etc. in the other ReadMe files supplied.

If you do have problems with these ports, please drop me a mail and let
me know and I'll do what I can to sort things out.



>> Contact details
``````````````````
  Musus Umbra: (main-acn.c, etc. author)

                  e-mail: angband@umbrarum.freeserve.co.uk
                          musus@argonet.co.uk

                   snail: Adny H.
                          c/o 23 Baronsway
                          Whitkirk
                          Leeds
                          LS15 7AW

There is a web page at http://www.argonet.co.uk/users/musus/angband/ from
which the latest version(s) should always be available, along with some other
information and links to other ports and/or information.

Acorn Arcade also now has some RISC OS specific Angband support pages written
by me.
