Sample program files
--------------------

This directory contains a few sample programs for
use with the 'Vertical Twist' joystick interface..


VTwistJS -

This is a relocatable module that can be used to
read the status of each joystick. It has been put
into the public domain by 'Vertical Twist' so you
can build it into your own applications. The
module provides one SWI for reading the joystick
status :

  SYS "Joystick_Read" (SYS &43F40)

The module conforms to Acorn guidelines on the
subject of joystick devices, so you can write
your applications to work with any kind of
joystick providing the manufacturer provides a
similar module.

If you do build the VTwistJS module into an
application then please follow the guidelines
listed at the bottom of this file.


VTwistTest -

This BASIC program shows how to use the VTwistJS
module to read the status of the joysticks.


!VTwist -

Run this script to load the VTwistJS module and
then run the AcornTest program.

SerPortJS -

This is another relocatable module for use in
reading the status of each joystick. It has also
been put into the public domain by 'Vertical
Twist'. It works exactly like the VTwistJS module
above except that it's SWI conforms to the
standard set by 'The Serial Port' joystick
interface back in 1990 (except that it does not
detect "stirring" actions) :

  SYS "Joystick_Status" (SYS &81540)

This module can be distributed with applications
that have already been written to use this
particular SWI. However, if you are writing new
applications then you should use the VTwistJS
module above; this can make your application
independent of the type of joystick interface
( eg. internal, printer port... ) and the type
of joystick ( eg. digital, analogue ).

If you do build the VTwistJS module into an
application then please follow the guidelines
listed at the bottom of this file.


SerPortTst -

This BASIC program shows how to use the SerPortJS
module to read the status of the joysticks.


!SerPrtTst -

Run this script to load the SerPortJS module and
then run the SerPortTst program.


MeasRapid -

This BASIC program measures how fast you can bash
the 'return' key, and it shows how fast the
rapid-fire examples of 'JoyStick' files operate.


DispMod -

This BASIC program displays the internal
structure of a 'JoyStick' file, it shows how to
extract the comment from such a file.

----------------------------------------------------

If you build one of the public domain modules
into an application then please follow these
guidelines...

a) Please credit us, 'Vertical Twist', and state
   that the application should work with interfaces
   sold by either 'Vertical Twist' or by 'The
   Serial Port'.

b) Please instruct the users to switch on the
   interface before loading the game, otherwise
   the joystick will not appear to work.
           
c) Try and write your game so that it is easily
   playable with one joystick. This not only refers
   to the gameplay itself but also to options
   screens, highscore tables etc...

d) Assume that a joystick will only have one
   fire button. The Acorn standard provides for
   more fire buttons but their functions must
   be duplicated on the keyboard.

e) Your application could include a range of
   joystick modules from different manufacturers
   providing they are all written to the Acorn
   standard. The application should try and
   load each module in turn, unless there is
   already a module named 'Joystick' loaded,
   and it should be able to cope with a module
   refusing to load.

f) Try and make it possible for the module to
   be upgraded. Don't rename it or hide it deep
   within your application and if the disc is
   copy protected then make sure that overwriting
   the module with a new (possibly larger) one
   does not stop it from working.
