                                SHeretic
                                ========
Version 1.05 (31 Oct 1998)

Introduction
------------

Serial Heretic allows you to play Heretic on two machines connected with a null
modem lead, or a modem.


Usage
-----

Run SHeretic.

Negotiate (via other means - ttylink, IRC, phone, yelling down the corridor,
etc) who is going to be the controller. Select the correct radio icon in the
window.

If you are intending to use dialup networking (modem connection, rather than
a null modem connection) tick the 'Dialup' icon and enter the correct phone
number. The number is only used on the server machine, but it is best to enter
it into both machines correctly in case you change your minds. If you are using
a serial line to connect, you should both set the 'Speed' to the same value.

When complete, press Ok. Now start Heretic.

The controller should select the network options he/she requires and then
press 'Heretic' to start the game.

That was the overview. Lets go through this a step at a time, for each of the
ways, and for each of the people. If you are playing against a PC, you should
still follow these instructions.


Null-Modem, controlling player:

  1. Plug serial lead into computer.
  2. Run SHeretic.
  3. Select 'We are controller'
  4. Ensure 'Dial-up' not selected, and the correct speed selected.
  5. Press Ok
  6. Load Heretic.
  7. Select the network choices you want for the game, using the Network
     window.
  8. Ensure that 'PC game' is selected appropriately.
  9. Select a level to play from the main window.
     [1]
 10. Press 'Heretic'.
 11. Await negotiation, and then the game will start.
 12. Once the game has started, there may be a few seconds delay whilst the
     two machines catch up with one another.
 13. Fire lots of times, usually aiming at moving people :-)


Null-Modem, non-controlling player:

  1. Plug serial lead into computer.
  2. Run SHeretic.
  3. Select 'They are controller'
  4. Ensure 'Dial-up' not selected, and the correct speed selected.
  5. Press Ok
  6. Load Heretic.
  7. Open the network choices window and ensure that 'PC game' is selected
     appropriately.
     [1]
  8. Press 'Heretic'.
  9. Await negotiation, and then the game will start to show a black screen.
 10. Once the controller has started up properly, the game will be entered.
 11. There may be a few seconds delay whilst the two machines catch up with
     one another.
 12. Fire lots of times, usually aiming at moving people :-)


Modem-To-Modem, controlling player:

  1. Plug modem into computer
  2. Run SHeretic.
  3. Select 'We are controller'
  4. Ensure 'Dial-up' selected, and the other players phone number is in the
     box.
  5. Press Ok
  6. Load Heretic.
  7. Select the network choices you want for the game, using the Network
     window.
  8. Ensure that 'PC game' is selected appropriately.
  9. Select a level to play from the main window.
     [1]
 10. Press 'Heretic'.
 11. Whilst the network game is initialising, the modem will dial the other
     player. This may take a few seconds, so listen to the tunes that it
     plays.
 12. Await player negotiation, and then the game will start.
 13. Once the game has started, there may be a few seconds delay whilst the
     two machines catch up with one another.
 14. Fire lots of times, usually aiming at moving people :-)

Note: You will be the one making the call and on most telephone networks this
      means you are paying for it.


Modem-To-Modem, non-controlling player:

  1. Plug modem into computer
  2. Run SHeretic.
  3. Select 'They are controller'
  4. Ensure 'Dial-up' selected. You need not enter a number because you are
     answering the call.
  5. Press Ok.
  6. Load Heretic.
  7. Open the network choices window and ensure that 'PC game' is selected
     appropriately.
     [1]
  8. Press 'Heretic'.
  9. Whilst the network game is initialising, the modem will await the
     other players phone call. This may take a few seconds but when it rings,
     DON'T pick it up!
 10. Await player negotiation, and then the game will start.
 11. Once the game has started, there may be a few seconds delay whilst the
     two machines catch up with one another.
 12. Fire lots of times, usually aiming at moving people :-)

Note: You won't be paying for the call.


Using PWADs:

  To use PWADs in the game, you must BOTH have the same PWADs. You must BOTH
  drag the PWADs to the Heretic window at the point marked [1] in the notes
  above. Failure to do so will result in the anihilation of the entire
  universe, and the possible creation of a sherbet lemon and a catcus.


PC users
--------
To run the PC version of Heretic, the following method was found to be
successful :
  
  1. Change to the directory containing Heretic.
  2. Type 'sersetup -19200', followed by any command line parameters you
     like.
  3. Watch Heretic start up.

This may seem a little primitive, but was found to be successful. Using other
front ends may be successful, but due to the proliferation of them, they
cannot all be tested.


Network options
---------------

On some slower lines it may be necessary to increase the number of packets
sent at a time. This can be done from the options window, available from the
'Options...' menu option.

Increasing the number of 'tics' will make games less jerky but may not be
possible if the network does not allow large packets. Backup packets mean
that duplicate copies of the data is sent. Because a serial line is not
inherently lossy, this usually degrades the performance and should be turned
off under almost all circumstances.

You will need to experiment with these before a suitable setting for your
network can be found.

It has been found on the test system (StrongARM RISC PC and A5000) that
the default was sufficient.


Problems
--------

During initialisation I hear the modem try to connect, but it doesn't get any
further.
  It is possible that the line is busy, or that there is some other problem.
  Press Escape and start again.

'NetUpdate: netbuffer->numtics > BACKUPTICS'
  The network speed is too slow (or two fast)
  Change the number of tics sent and backup tics
  Computers of vastly differing speeds may have this problem (or those on slow
  lossy networks.

'consistency failure (# should be #)'
  The options specified exceed the network capabilities.
  Try reducing the number of tics or removing the backup tics.

'bad packet checksum'
  The network driver is faulty - consult your supplier

'bad packet length %i'
  The network driver is faulty - consult your supplier

'Different Heretic versions cannot play a net game!'
  Different Heretic versions cannot play a net game.

The game is 'lumpy', or becomes 'lumpy' after a period
  You are probably trying to use differing computers with a lossy
  connections. The 'lumps' of data are the points at which the slower
  computer manages to catch up.
  The speed of the game is determined by the slower of the frame rate and the
  incoming/outgoing packet processing speed. Where the latter exceeds the
  former, the game will appear to run slower.
  You will experience this kind of behaviour if you are playing against an
  underpowered machine either by memory or processor because it is either
  loading things or processing lots of data more slowly than your machine.
  Their machine seems more regular in its movement. There is little that
  can be done than to change the number of ticsbackups.

I get 'Module HereticSupport not found' when loading the network driver
  You probably broken the copy of Heretic you have.

I get a black screen which stays on both machines.
  Something has gone wrong in synchronisation. Try F10, Y. That should quit
  and the other machines should be released.

I'm trying it on three (or four) machines and ...
  The serial driver doesn't work on anything other than two machines. You
  should read the right !Help file (look at !HerNet).

Can I get two copies of Heretic running networked on the same machine ?
  Do you want the short answer or the long one ?
  Short answer: No.
  Long answer:  Noooooooooooooooooooooooooooooooooooo.

Can we get drones to work ?
  Probably not.
  Drones are a kind of hang over from an early beta of the game. It is
  possible that they may be implemented in future, but it all depends on
  what else needs doing. They will, of course, need a seperate configuration
  utility.

Does disabling the StrongARM optimisations speed up the game ?
  By about 1-2 fps on non-SA machines. Not at all on SA machines.


Advanced use
------------

You need not read this section if you wish only to play the game; it is
intended for front-end authors and people setting up automated start
sequences.

To initialise SHeretic, /without/ running the front-end, you should run
!SHeretic with the command line parameter '-quit', eg '*Run
<SHeretic$Dir>.!Run -quit'. Once initialised, the HereticSupport and
HereticNetwork modules will have been safely loaded.

There are a number of *Commands you may use to initialise the system :
  
*HereticAddNode <node> <name>|<dotted ip>
   Add a node to the network.
   <node> is the node number to set (0-3)
   <name> is the host name to use
   <dotted ip> is a dotted IP address
   [This is not supported for this driver]

*HereticConsole <node>
   Declares who is on the 'console' - ie the controller.
   [Use only 1 or 0]

*HereticNodes
   List the current nodes set.

*HereticNoPolling <flag>
   Specifies that we should not poll the Wimp during the setup stage.
   <flag> may be 0 or 1

*HereticDial [<number>]
   Specifies a telephone number to dial during the initialisation. The number
   is only used if you are the controller. Giving no parameter will reset to
   null modem operation. Use :
     *HereticDial <number>
       If you are the controller for a modem game
     *HereticDial answer
       If you are not the controller for a modem game
     *HereticDial
       For any sort of null modem game.

In addition, there are a number of SWI calls you may use to control the system.


HereticNetwork_SetNode (&51440)
=> R0 = node number
   R1 = pointer to node name, or 0 to unset

Sets up a node (as *HereticAddNode).
[This is not supported for this driver]


HereticNetwork_ReadNodes (&51441)
<= R0 = pointer to nodes block
        +0  Pointer to node 0 name, or 0 if unset
        +8  Pointer to node 1 name, or 0 if unset
        +16 Pointer to node 2 name, or 0 if unset
        +24 Pointer to node 3 name, or 0 if unset

Read the nodes table. You should only read from this table, not alter it
directly.
[This is not supported for this driver]

HereticNetwork_SetConsole (&51442)
=> R0 = console node

Sets the console node (as *HereticConsole).


HereticNetwork_ReadConsole (&51443)
<= R0 = console node

Reads the console node.


HereticNetwork_SetNetOptions (&51444)
=> R0 = number of tics
   R1 = backup tics (flag)

Sets up particular network options.


HereticNetwork_SetFlags (&51445)
=> R0 = new flags
<= R0 = old flags
   R1 = mask of flags recognised

Modifies some generic flags. Note that some flags may not be recognised by
some drivers. Currently the available flags are :
  Bit     Meaning if set
  -------------------
  others  Reserved for future expansion (ie no flags current defined)

NOTE: These SWIs and commands should not be relied on, and may change without
notice. The SWI block is registered.


Contact
-------

Network Drivers:

E-Mail : Heretic@thevillage.ndirect.co.uk
IRC    : On #Acorn as Gerph
Tel    : (01842) 813979

Snail Mail :
    Justin Fletcher
    Galadriel
    17b Cromwell Road,
    Weeting,
    Brandon,
    Suffolk.
    IP27 0QT


Acorn Heretic:
  
E-Mail : Heretic@rcomp.co.uk
Tel    : (+44) (0)1925 755043

Snail Mail :
  R-Comp Interactive
  22 Robert Moffat
  High Legh
  Knutsford
  Cheshire
  WA16 6PS
  England


History
-------
Version 1.00 : 04 Oct 1998
               First version written
               Some people... are very scrummy.
               There's nothing more to say really. I haven't had time for a
               hidden message in this version, so you'll just have to suffer
               in the knowledge that this only does what it says on the tin.
               Sorry :-)

Version 1.01 : 04 Oct 1998
               Ooops. Thoroughly check your code before releasing it. 1.00
               had a minor memory allocation bug that would (sometimes) cause
               RMA corruption.

Version 1.02 : 04 Oct 1998
               Added simple dialup facilities. Quite rudimentary but has
               worked in tests.
               No worries.
               DoomNodes now tells you about the dialup status.

Version 1.03 : 11 Oct 1998
               Now supports auto-sensing of the remote driver, and will switch
               to its format automatically.
               Uses new network specification. This driver will not work with
               versions of DoomSupport prior to 1.03.
               This should make the driver more reliable when restarting
               games.

Version 1.04 : 21 Oct 1998
               Added PC byte order switch to front end. How long have I been
               putting off this and why ? ! It was easy!
               Help file updated with what /should/ be the simplest
               instructions possible.

Version 1.05 : 31 Oct 1998
               Fixed PC byte order bug (never let you deselect it).

Version 1.06 : 01 Nov 1998
               Removed PC byte order code. Why ? I'm not even going to answer
               that out of sheer embarassment. Ok ?

Version 1.07 :15 Feb 1999
               Updated for Heretic.
