Reflection's State Machine...

I RECOMMEND YOU READ THROUGH THIS WHOLE DOCUMENT BEFORE PROCEEDING.

It contains info that will help in using and installing this script.

INTRO:
------

GNU License:  I would appreciate it if you use this code, that you thank me.
I would also appreciate it if you could build a shrine in any IGM's you make
to me with a statue and a sign reading 'Reflection: The God of IGM programming'.

Ok, maybe that's a little too much, but this code here is some of the most
powerful code you will ever see for LORD 2.  The LORD 2 state machine is the
only way I could effectivly combat the #1 problem I see with .ref files to
today; 'Lack of Communication'.  If 2 or more players are playing the same
ref at the same time LORD 2 would seperate them.  What I have done is opened
up a line of communication that can be used for transferring syncronized data
between multiple users.

I currently have a plan to use this in a big 'Total World Conversion', that's
the reason I built it.  But I am thinking of using it in the 'Brady Bunch' idf
to show off it's power.  Can you say orgy with the brady girls?

I am releasing the State Machine with 1 IDF to show what it does.  The idf is
far from complete, and is only an example.  Feel free to try out what you can
make it do.  It's power is almost infinite.  I have yet to try it with alot
of players, I just used 2 in my tests, but it shouldn't have any problems.

I believe the code is tight enough to handle 98% of the situations that are
thrown at it.  However, it only handles the data that is thrown at it, you
have to handle that data correctly with the users.  

If the user is sending a change in value to the state machine, it has to be
less than 16384.  That means if someone trys to take 16384 or more gold from
a treasure, you have to A) Split it up into multiple takes, B) Deny them and
tell them to enter a smaller value, or C) Use a seperate file to transfer
the data.  It is important to tell all the users to read that file by setting
up a state that tells all the users 'Hey, this user just took X amount of
gold'  Otherwise you will get data inconsistancies.  There is a 4th option
I forgot to mention..  D) Have default value for taking the gold that says
to everybody..  'He took it all' so a max value of 16383 can really be 'all'.
Hehe.  I keep on thinking of new options.  E) Have a couple of states for
ranges.  So a state if 50 can be 0-16383, and 51 can be 16384-32767 and so on.

Ahh, back to the main subject of this document..  Which isn't how to program
for the state machine (like I said, the possibilities are infinite) but what
to do with it.

There can be 511 states in any script.  Plenty to make the script it self too
large to work with.  I don't think that will be a limit.  Because of file
locking problems I had to combine all 3 fields of data into 1.  Because of 
this I had to limit each field to a value that would fit.  

There can be 511 players in any script.  Why so many?  For NPC's, lots of
NPC's.  I made this for a housing program, (the example is a part of it)
and I wanted players to marry and have kids.  Each of these I hope to make
as seperate entities (NPC's that can do stuff and effect the player).
I can't wait till I code into my house program a flu virus that passes to
all the family members, and guests.

So lets go over that 1 more time.
16384 Amount of an item.
  511 States.
  511 Players.

DON'T Exceed any of these values..  They are NOT checked.  For speed
purposes I don't check for a limit exceeding.  So if there is a chance
check it yourself.

Never do an @RUN or @ROUTINE from any of the states.  Unless you want
to leave the state machines control.  There is no way back unless you
re-run the state machine.  I say this because the states are all called
with @ROUTINE and routines cannot be nested (you can't call more than 1
at a time) and @RUN will break the last @ROUTINE.

USING THE SCRIPT:
-----------------

The state machine program will not run as it is.  Because of issues with
the 'ref' programming language I had to leave a few things in for the
user to change when they use the script.

Replace the following keywords before using statem.ref. (Include the {})
 {REF} : Replace this with the main ref file name and location that you
         will be using with this state machine.  You need a diffrent state
         machine for each ref file you use.
 {IDF} : Replace this with the filename and path of where you want to keep
         the state machine stack.  For simplicity if you want put it in the
         same location as your ref, with the same name and .idf instead of
         .ref for the extension.
 {NOS} : Replace this with a number between 20 and 200.  This is the number
         of states the machine will count up before it loops around and
         updates a data file. (if you are using one)  I keep this fairly
         small because all users entering the script will start at state 2
         (1 is reserved for the current write state #) and they will have 
         to process all the states from 2 to the current state.  So if the
         state machine is at 180 when the player enters the script they will
         have to process 180 events before they can do anything.

None of your variables need to be set before using this script but the
following variables are reserved for the script when running, and can't
be used.  If other .refs need values in these variables, save them on
entry and load them on exit.

Variables used:
  p94: Tells your main script to save the .ref's data.
  p95: Value.  Distributes a value to the players. (For gold and stuff)
  p96: Action.  Distributes the actions of the players in the script.
  p97: Player #.  Used to tell other who did the above action.
  p98: Player's State.  Used to tell the player what state he is on.
  p99: Last state written.  Tells the player what the last state number is.
   
  s08: Used by the keypress function.  Holds the last key pressed.
  s09: Holds the Current state.  This must be set to the entering state 
       before entering the script, or in my_data_init.

These are not used unless you uncomment the debugging section of code.
  s02: Only used if Debugging.
  s03: Only used if Debugging.
  s04: Only used if Debugging.

The following Headers are required in your .ref script, and an empty shell
is included for an example, and adding to.

@#my_data_init : Initalizes all the required data for the script.
@#my_data_save : Saves any data when the stack is full and loops around.
@#my_clear_window : Allows the user to define his own clearing commands.
@#{State}_display : User can put output for the state her.
@#{State}_keypress : User can process keypresses here.
@#{State}_update : User can process other players events here.
@#global_update : Users can process events that effect all the players in
                  the script here.
@#global_spawn : Used to cause events to happen spontaniously.  I decided
                 to add this and the previous header for improved
                 functionality.

When a player enters the script they will be automatically sent to the
first state in `s09.  On entry they will also process any events in the
que.  You want to be carefull and squelch text during this process.  If
you don't new users will see events that happend in the past print on
their screens.  I noticed this wasn't easy to do, so I added some more
functionallity to my script.  Use global_spawn for turning off squelching
on the second run through.

I also added global_spawn for added stuff like monster movement and stuff
unfortunaly it is run quite often, so it's first couple of lines should
have an @closescript if there is nothing happening.  If you make 
global_spawn process alot of data before exiting you can slow down player
input tremendously.  I may add a @#{State}_spawn later if needed, but as
far as I can tell now, 98% of spawns will be global anyways.  Also, 
@global_spawn should not do much.  It should primarily just fire off
states, and sometimes do things that a state can't.  When spawing off
a state, give a player number (Use 511 for No One) and a state number.
For my house example, I could have a wife (player number 201) and have
her use the washroom (state 32) every now and then.  I think something
that may be good to do is have a counter in @global_spawn, which will 
exit immediatly 1999 times out of 2000.  I will continue working on the
spawing part of this script, there are still alot of things that need
to be worked out.  For example..  The more players playing the script
the more often spawns will happen.

For a little more info here's how often each script segment gets run:
@#global_spawn : All the time.  Verrrry Often.
@#global_update : Once for every new state in the buffer that is not yours.
@#{State}_update : As often as global_update.
@#{State}_keypress : Every time the player presses a key.
@#{State}_display : Same as keypress
@#my_clear_window : Same as keypress
@#my_data_save : Only when the state buffer is full. 
                 (1/20 states to 1/200 states)
@#my_data_init : Only once.

I think that's about it.  If I missed anything, or something is confusing
just say so.  You can find more info on this and other projects, plus add
your comments at:

  http://www.reflections-server.com

FAQ:
----

Q: Why are there no questions in the faq.
A: Because I just stated it.
Q: Why is it V0.98 and not V1.00
A: I want to make sure that it is working to it's fullest.  I am pretty
sure it is, but it's good to get feedback before I make it a final.  Also
I wan't to improve on the documentation, and there is no better way then
user feedback.  Finally, I want to make 2 .ref's for added examples.
  Ref 1: Sex Swapper.  Swaps sexes of 2 players when they are both in the
         .ref, Only really good if 1 is M and the other is F.  But will
         show the power of my program.
  Ref 2: Brady Bunch Advanced.  Mike really does move around the rooms,
         not just a random thing.  And you can see other players in the
         rooms, and even have an orgy with the girls upstairs.  And
         convince the mother to come along for the ride.
Q: When is V1.00 comming out.
A: When I have recieved enough feedback to fix any problems, and to say
   'Ahh..  It's working correctly 99% of the time' instead of just 98%.

ADVERTISING:
------------

Comming soon to a BBS Near you...

  LORD 2: The Awakening.

    Choose from 1 of 10 diffrent races.
    Learn skills in 20 or more professions.
    Own a House, Get Married, Raise a family.
    Own Shops, Buy and Sell goods, Join the Army, or tend a bar.
    Become a Town Mayor and build your city up.
    Or Become a Dungeon Master and dig your dungeon deep.
    Build a Mighty Empire...
      Then destroy all who stand against you!*
 
    * Destructive Results may very.  I, me, my self, and I are not
      responsible for your destructive potental, and is not liable
      for someone elses wantonus destructive habits.


