How to write Hang Fire  modules.

Its actually very easy; easy enough in fact to be able to work out what
to do from simply looking at the existing modules.

The two main things to note are the layout of the program and the calls
and variables you can use from the main program.

If we look at the program we can see the correct way to lay out a
module, but the wrong way to actauuly make it work nicley.

REM ><Current$Dir>.Simple
REM
REM Hang Fire Module "Simple" - To show how to write a module

DEF FNSimple_Install(ScratchArea)
=0

DEF FNSimple_Option(Opt,OptArea)
=0

DEF FNSimple_Start
=0

DEF FNSimple_Poll
GCOL RND(63)
CIRCLE FILL RND(1280),RND(1024),RND(64)
=0

DEF FNSimple_Finish
=0

DEF FNSimple_Deinstall
=0

To get your code called properly all you have to do is save your module
in the Modules Directory and have the same calls as above but instaed
of prefixing them with 'simple' you prefix them with the same name as
you module (useing the same case.)

The Install code gets called when your module gets loaded--this is if
it was the saved module option when Hang Fire startsup, or when someone
changes to it by clicking on its name in the scoller window in the
options window.
The parameter that gets passed to you is ScratchArea. Now there is
no way you can DIM memory or arrays at the moment since they do
not get deleted when you code is deinstalled. This means if you
did, memory would soon fill up and the programwould fall over.
My solution (and one that may change in the future although
in such a way as to not affect the modules already written) is
to give the module a chunk of memory that it can use for anything
it likes. This can be Machine code, Lookup tables, Sprites,
Data or whatever.
The only constrint you have is that it is only 32K long (which
has been plenty big enough for all the code so far.)

The Option code get called when a user chooses a option specific for
your module (which is never at the moment--see the ThingsToDo file)

The Start code gets called whenever a screen save starts and your the
current save module. Usually you clear the screen to black and init
any varibles you need in this code.

The Poll code gets called every update of the screen save (ie this
is the code that gets repeatedly called for each 'frame' of the
save.) This is where you put all your main graphics code.

The Finish code gets called when a screen save finishes, ie when
someone moves the mouse or presses a key. You donthave to do anything
to restore the screen in this, Hang Fire does all that for you.

The Deinstall code gets called when your module is deinstalled (simple
really...)


Now Hang Fire has a few built-in 'commands' and variables.
These are to help you write modules, and to help them work in
all screen modes (which is very important.)

The 'command' are basic procedures to make writing modules simpler
(andsmalle, since you dont have to include the same code in all
your modules.)

There are tow commands for clearing the screen to black (something
that is common to many modules.)

PROCClearScreen

This simply clears the screen to black (ala CLS or CLG.) Use this
instead of your own code as it will clear the screento black in any
mode.

The other one is

PROCFadeScreen(<var>)

This also clears the screen to black but uses a number of random
effects (or 'fades or 'wipes') to do so. You should use this
if you just want the screen black and it dosn't have to do it
immediatly (it can take several seconds.)

You should pass it one of two variables:
 RandomFade
or
 FadeSequential

The first chooses a random fade and the second goes through all the
fades one by one.


Many modules will want to use colour in their effects, but the
code has to work in all screen modes so you have to use
ColourTrans calls to do stuff. Now I have put in a procedure
that simplifies this. Just call

PROCSetColour(r,g,b)

where the r g & b are values for the amount of red green and blue
(from 0 - 255 : 0 being off and 255 being full on)


There are also variables you can use (but not change.)

HF_ScreenMaxX : The maximum X size of the screen in OS units
HF_ScreenMaxY : The maximum Y size of the screen in OS units
HF_ScreenMinX : The minimum X            ''                  (usually 0)
HF_ScreenMinY : The    ''   Y            ''                      ''
HF_XEigFactor : The X Eig factor of the screen (its easier to use HF_XSize)
HF_YEigFactor : The Y          ''                      ''         HF_YSize)
HF_XSize      : The size of a pixel in the X direction in OS units
HF_YSize      : The          ''            Y          ''
HF_Wait       : Whether you shouldhavewaits in your code or not.
		Many screen effects are a bit smoother when you call
		WAIT but they may go a lot faster if you do not. The
		decision should be up to the user. You should put
		IF HF_Wait THEN WAIT
		in your code atany place you might want to call WAIT
		normally.

