                        The Gateway IGM Program Codes:
                       -- October 2002 Release Docs --
                        ==============================

This file lists the program codes for the new built in Random Happening
Program (RHP) system.  See GATEWAY.TXT under the section [EXTRA SETUP
INFO] for how to install your RHPs into The Gateway.  Remember that
if you distribute your programs, please give me credit for writing
The Gateway!
                                        
Look at SAMPLE.RHP to see how these can be used.

The RHP language uses codes that have a @ on both sides.
Unless otherwise notified, codes will work with previous versions.
of The Gateway.

Example: @PROGRAM@ GATEWAY
Example: @VERSION@ 1.0, or @VERSION@ 1.1

Example: @VERSION@ 1.0d     -- For July 2002 @DEFENSE@ code usage.
Example: @VERSION@ 1.0e     -- For October 2002 version's new RHP Codes.
-----------------------------------------------------------------

These are RHP properties, they tell the IGM various things about
the script.  Remember that these have a @;@ at the start!
   This first set is just normal commands with no parameters.

@;@@PROGRAM@ xxxxxxxxxxx  What program it's for, for this program
                          put GATEWAY
@;@@VERSION@ xxxx         Version of program the script is compatible
                          with
@;@@NAME@ xxxxxxxx        This is the name of the RHP to be displayed
                          in the menu.
@;@@LIMIT@ xxxx           Limits the number of times the RHP can be
                          accessed in a day.
-----------------------------------------------------------------

This set is just random commands.

@;@@VARIABLE1@ xxxxxxxxx  Gives a name to the given user variable
                          number.  If you define a name, it will show
                          up in the stats. Covers VARIABLE1 - VARIABLE5.
                          Max length is 13 characters. (v1.0a)
@;@                       Comment, everything on a line with this at the
                          front will be ignored (works in recording)
@CLEAR@                   Clear the screen (works in recording)
@STATS@                   Displays the player stats
@MORE@                    Pause for keypress with "<MoRE>"
@DELAY@                   Small delay (250 or so milliseconds)
@END@                     Stop program and pause
@KILL@                    Stop program, pause, and kill player (player
                          is notified)
@EXIT@                    Stop program, pause, and exit to LORD
@RUNRHP@ xxxxxxxx.xxx     Run an external RHP program.  Does not
                          return to the first program.
@KILLSAVE@                Same as KILL code, but factors in Fairy.
                          No fairy - player is killed, and notified.
                          Has fairy - (1) It saves them from death,
                          heals wounds, and leaves.  (2) It is on
                          "strike", so player is killed and notified.
                          The Fairy decision is made randomly by the
                          IGM:  "Save player" or "Go on Strike".
                          (RHPTest 1.2+, Gateway v1.1+)
-----------------------------------------------------------------

This set is for writing to a player's MAIL?.DAT and LORD's LOGNOW.TXT.

@MAIL@      Start writing to mail
@MAILEND@   Stop writing to mail
@NEWS@      Start writing to LOGNOW.TXT
@NEWSLINE@  Stop writing to LOGNOW.TXT and add
            a line "-=-=-=-" centered (on-screen).
@NEWSEND@   Stop writing to LOGNOW.TXT
-----------------------------------------------------------------

The following two sets can be used in Mail and News recordings.

  The next set is for designating sections to go to.
  @#xxxxxxxx              Section designation, no maximum length
  @GOTO@ @#xxxxxxxx       Go to section xxxxxxx after this command

  The one in this section is for writing lengths of spaces.

  @SPACE@ x               Write x spaces to screen/file
-----------------------------------------------------------------

This new set is for testing existing information and can be used in
Mail or News recording.

Example: @IF@ FEMALE @GOTO@ @#Help (if player is Female, goto section
                                  @#Help)
Example: @IF@ EXPERIENCE>0 @GOTO@ @#Help (if experience is greater than
                                  0, goto section @#Help)
Example @IF@ FIGHTER `9Good job! (if player is a Death Knight, write
                                  `9Good job! to file/screen)
Example @IFNOT@ MAGIC `9Good job! (if player is not a Magician, write
                                  `9Good job! to file/screen)

@IF@ condition command  Test condition, if True, do command.  Command
                   can be any RHP @ command or one line text.  Condition
                   can have math in it (see variables section).

@IFNOT@ condition command  Test condition, if False, do command.
                   Command can be any RHP @ command or one line text.
                   Condition can have math in it (see the Variables
                   section).

Usable conditions for @IF@ and @IFNOT@ statements:
--------------------------------------------------
 FEMALE     : returns if player is female
 MALE       : returns if player is male
 FIGHTER    : returns if player is currently a Death Knight
 MAGIC      : returns if player is currently a Magic User
 THIEF      : returns if player is currently a Thief
 HORSE      : returns if player has a Horse
 FAIRY      : returns if player has a Fairy
 MARRIED    : returns if player is married, works with Violet and Seth
              Able marriages as well as player to player.
 SPIRITS    : returns if player is in High Spirits
 WEIRDEVENT : returns if player will have a Weird Event in the forest
 HEALED     : returns if player is healed
 x<y        : returns if number x is less than a number y
 x>y        : returns if number x is greater than a number y
 x<>y       : returns if x is not equal to y
 x=y        : returns if x is equal to y
----------------------------------------

 BARDSONG   : Returns if player has heard Bard Sing in Inn.
              (Gateway v1.1++, RHPTest 1.2+)
 FLIRTED    : Returns if player has Flirted With another Player yet.
              (Gateway v1.1++, RHPTest 1.2+).
 SETHVIOLET : Returns if player has Flirted with Violet or Seth.
              (Gateway v1.1++, RHPTest 1.2+)
 SEENMASTER : Returns if player has Seen Master yet.
              If True, player LOST a master fight challenge.
              And is not allowed to do another challenge that day.
              (Gateway v1.1++, RHPTest 1.2+)
 SEENDRAGON : Returns if player has Seen the Red Dragon yet.
              (Gateway v1.1++, RHPTest 1.2+)
-----------------------------------------------------------------

Any number can be used as x or y or you can use player stats.

Player stats that can be used as x or y:

 VISITS     : Visits left
 FOREST     : Forest fights
 FIGHT      : Player fights
 KIDS       : Kids
 DEFENCE    : Defense
 DEFENSE    : Defense  -- Usable with Gateway v1.1+.
 STRENGTH   : Strength
 EXPERIENCE : Experience Points
 LAYS       : Lays
 SKILL      : Current Skill type points amount
 HITPOINTS  : Current HitPoints
 HITMAX     : Max HitPoints
 GEMS       : Gems
 GOLD       : Gold in hand
 BANK       : Gold in Bank
 CHARM      : Charm
 WEAPON     : Weapon number
 ARMOUR     : Armour number
 LEVEL      : Player's level
 KILLS      : Number of player kills
----------------------------------------
 SKILLUSE   : Skill Usage Points amount, for current Skill.
              (Gateway v1.1++, Rhptest v1.2+)
-----------------------------------------------------------------

ALLGOLD can only be displayed in a script, using @*@ALLGOLD@*@
in a text statement.  LEVEL, CLASS, and WINS are display-only
variables, which can't be set by the script writer.
==================================================================

The following set is for prompting for Input (from player).  The
single character section is used to act on the Input data.  The
program runner acts on the first matching section found, so don't
use the same selections nested.

Example: @PROMPT@ CD (prompts for C and D selections, must be an @##C and
                      @##D sections later.)
@YESNO@        Prompt for Y/n, Y and N sections
@PROMPT@ xx..  Prompt for selections xx.., selections must be
               capitalized.  The first selection will be the default one.
@RANDOM@ x     Random number between 1 and x, each number a section
@##x           Single character section, can be called with @GOTO@
-----------------------------------------------------------------

The following set has some special properties.  If you put a = before the
number x, it makes that attribute equal to x.  If you put %, it adds /
subtracts x% of the existing attribute to the attribute.  Ones marked with
a $ can be used in mail without the = option and may just increment the
attribute by 1.  Player is notified with a 'You LOSE/GAIN x <type>!' in
both mail and on screen, except not in mail for those that just increment.

You can also do one math operation (/,*,+,-) in a line.

Putting *LEVEL multiplies the number times the player's level.
     Works best if you include a +/-. Ex. @GOLD@ +500*LEVEL  - would
     add 6,000 Gold to Gold in Hand, for Level 12 player.

Example: @EXPERIENCE@ %-15     (Subtracts 15% of experience)
Example: @GOLD@ =0             (Sets gold in hand to 0)
Example: @EXPERIENCE@ 4*LEVEL  (Adds 4 times the player's level of
                                experience)
Example: @GOLD@ 6*GEMS         (adds 6 times the player's gems to
                                gold)
-------------------------
Example: @SKILLUSE@ +1   (Adds 1 to current Skill's Uses)
Example: @SKILL@ -1      (Deletes 1 skill point, of current class)

@VISITS@ x      RHP Visits left
                -- For Gateway IGM scripts usage only.
@FOREST@ x      Forest fights $
@FIGHT@ x       Player fights $
@KIDS@ x        Kids $(increments number by 1, ignores x)
@DEFENCE@ x     Defense $
@DEFENSE@ x     Defense points $       (Gateway v1.1+ only)
@STRENGTH@ x    Strength $
@EXPERIENCE@ x  Experience $
@LAYS@ x        Lays $(increments number by 1, ignores x)
@SKILL@ x       Current Skill type (if resulting number is above 40 the
                Skill value is set to 40, no uses are given)
                ($ increments number by 1, ignores x)  {See Note}
@HITPOINTS@ x   Current HitPoints
@HITMAX@ x      Max HitPoints $
@GEMS@ x        Gems
@GOLD@ x        Gold in Hand $
@BANK@ x        Gold in Bank $
@CHARM@ x       Charm $(increments number by 1, ignores x, = option can
                be used)
@KILLS@ x       Number of player kills
--------------------

@VARIABLE1@ x   RHP variable 1 for math, is forgotten after RHP is done
@VARIABLE2@ x   RHP variable 2 for math, is forgotten after RHP is done
@VARIABLE3@ x   RHP variable 3 for math, is forgotten after RHP is done
@VARIABLE4@ x   RHP variable 4 for math, is forgotten after RHP is done
@VARIABLE5@ x   RHP variable 5 for math, is forgotten after RHP is done
-------------

@SKILLUSE@ x    For current Skill's Use Points. x - Set field to
                what X is.  ($) - Increments field by 1.  {*SEE NOTE*}
                ($ increments number by 1, ignores x)
-------------

SKILL Points/Skill Use Points Note:  Through v4.00x, LORD limited the
Skill points, and Use Points, to 40 points maximum per Skill class.
v4.02+ allows IGMs to award Skill Points, or Skill Use Points, up to
100, but LORD itself still maintains the 40-point limit.

Since pre-v4.02 LORD versions only handled up to 40 Skill/Skill Use
points, usage of @SKILL@ and @SKILLUSE@ in mail*.dat files *WOULD*
result in either one being reset by LORD, when it re-assumed control
of the player, to 0-40 range values.  And if you are using post-v4.02
LORD versions, they handle skill info in Mail files the same way.

So it is best to AVOID using SKILL or SKILLUSE in a mail file,
unless you are prepared to be blamed by irate players who've lost
hard-earned skill points as a result of your mail message(s).

(Anyone who uses Sherwood Forest LORD IGM has seen this exact
situation occur to their characters that HAD skill/skill use values
above 40.  There are other LORD IGMs that will do likewise.)
=====================================================================

Other examples:
  @WEAPON@ - Weapon number.  Can be set between 1 and 15.
             Usage of Code, will probably not drop/raise Strength points.
  @ARMOUR@ - Armour number.  Can be set between 1 and 15.
             Usage of Code, will probably not drop/raise Defense points.

             You will have to do that work yourself.  See LORDSTRC.PAS
             file, distributed with each version of LORD, for details
             on Weapons/Armour.
----------------------------------------------------------------------

-- These variables are for Gateway IGM scripts usage only:
----------------------------------------------------------
@USER1@ x       User variable 1, is stored in Gateway's player file
@USER2@ x       User variable 2, is stored in Gateway's player file
@USER3@ x       User variable 3, is stored in Gateway's player file
@USER4@ x       User variable 4, is stored in Gateway's player file
@USER5@ x       User variable 5, is stored in Gateway's player file

Example usage:  Use an @USER code to keep track of whether an user
had done something in your RHP IGM earlier that day.
-----------------------------------------------------------------

These codes are special player value changers that don't act like the
earlier ones.  They cannot be used in mail.  Player is NOT notified.

@FAIRY@       Changes if user has a Fairy.  Takes no parameters.  If user
              has a Fairy, it's taken, else one is given.
@HORSE@       Changes if user has a Horse.  Takes no parameters.  If user
              has a Horse, it's taken, else one is given.
@SEX@         Changes user's sex.  Takes no parameters.
@ARMOUR@      Changed!  Changes armour name to built in name (same as in
              The Skeleton Happening)
@WEAPON@      Changed!  Changes weapon name to built in name (same as in
              The Skeleton Happening)
@WEIRDEVENT@  Changes if user will have a Weird Event in the forest, that
              is if they will find gems when entering.
              (Note: Weird is intentional spelling of the word.)
@SPIRITS@     Changes the player's spirits, from high to low or from low
              to high.
@HEAL@        Heals the player.
-----------------------------------------------------------------

NOTE:  If Weapon/Armour Names are specified in a RHP Script, they
       may NOT exceed 20 spaces in length.
---------------------------------------------------------------------------

    For Gateway v1.1++, RHPTest v1.2+ usage:
@BARDSONG@       Indicates whether player has have heard Bard Sing.
@FLIRTED@        Indicates whether player has Flirted with Player yet.
@SETHVIOLET@     Indicates whether player has Flirted with either
                 Violet or Seth Able.
------------
@SEENMASTER@     Indicates whether player has Seen their Master yet.
@SEENDRAGON@     Indicates whether player has Seen the Red Dragon yet.
    -- Neither indicates WHAT happened during meeting, just that there
    was one with either Training Master or The Red Dragon.
-----------------------------------------------------------------

Variables like these work like the older LORD style codes, you put them
in a string to output and they get replaced by the corresponding value.
Place the word you want in between @*@ like so:

  Example: `4Hello, @*@NAME@*@!

These all require The Gateway v1.0a+ in order to work:

ALLGOLD    : Player's total gold  (In Hand + In Bank)
ARMOUR     : Player's armour name (same as `a)
BANK       : Player's bank gold
CHARM      : Player's charm
CLASS      : Player's class (eg. "Death Knight")
DEFENCE    : Player's defense
DEFENSE    : Defense Points           (Gateway 1.1+ only)
EXPERIENCE : Player's experience
FIGHTS     : Player's human fights left
FOREST     : Player's forest fights left
GOLD       : Player's gold on hand
HITPOINTS  : Player's current hitpoints
HITMAX     : Player's maximum hitpoints
KILLS      : Player's number of player kills
KIDS       : Player's number of kids
LAYS       : Player's number of lays
LEVEL      : Player's level
NAME       : Player's name (same as `n lord code)
MARRIED    : Player's spouse's name (same as `m)
USER1      : User variable 1
USER2      : User variable 2
USER3      : User variable 3
USER4      : User variable 4
USER5      : User variable 5
STRENGTH   : Player's strength
SKILL      : Player's skill points level for current class
SKILLUSE   : Player's Skill Use level for current class (v1.1+)
VARIABLE1  : RHP variable 1
VARIABLE2  : RHP variable 2
VARIABLE3  : RHP variable 3
VARIABLE4  : RHP variable 4
VARIABLE5  : RHP variable 5
WEAPON     : Player's weapon name (same as `w)
WINS       : Number of times player has won
-----------------------------------------------------------------

Note: Old copies of these CODES.TXT files referred to @FIGHT@
code for Forest Fights.  It is actually @FIGHTS@, so be to sure
to use the ending 's'.
----------------------------------------

Section added 07/15/02: Applies to RHPTest v1.2+, and the
October 2002 LORD IGM releases:

CLEANMODE - Used in script to do one set of commands if LORD is
    in Clean Mode.  Second set done if LORD is in normal mode.
    Here are two examples of how to use it:

@IF@ CLEANMODE `1You're naughty!
-- If LORD is in clean mode, it displays the "You're naughty" phrase
on screen.  Can also be used with the @GOTO@ command, etc.

@IFNOT@ CLEANMODE <your statement>
-- If Clean mode NOT in use, then <your statement> content is
displayed on-screen.  Usable with @GOTO@ command, etc.

----------------------------
@IFNOT@ note:  All variables that can be used with @IF@ may also be
used with @IFNOT@.
---------------------------------------------------------------------

Usage of the @VARIABLEx@ Codes:  07/16/2002
    The @VARIABLE1@ through @VARIABLE5@ codes may be used in The
L.O.R.D. Cavern, Outlands Tavern, and The Gateway to store math
computation data that are multi-step.  IOW, the standard RHP scripts
easily handle x*y type mathematics.  But something like A*B/C would
require two separate math computation statement lines in a script.

    You store data in the five VARIABLE codes while getting to your
final result for complex math.

To code GOLD = LEVEL*2*GEMS would be done like this:
  Statement #1: @VARIABLE1@=0    (Presets variable for data handling)
  Statement #2: @VARIABLE1@ @LEVEL@*2       (Stores result of Level*2)
  Statement #3: @GOLD@ @VARIABLE1@*GEMS    (Multiples Variable1 * Gems)
  The result of @VARIABLE1@*GEMS is assigned to the @GOLD@ variable.
---------------------------------------------------------------------

The following codes can be put anywhere in a line, even in Mail and News
recording.  They are case sensitive, and will output the correct case if
they're at the beginning of a sentence.

`n  Put player's name
`a  Put player's armour name
`w  Put player's weapon name
`m  Put player's spouse's name if married
`l  Do not perform a line feed (put at the end of a line)
`s  Put player's sex (he/she)
`o  Put player's opposite sex (he/she)
`[  Put player's sex possessive (his/her)
`]  Put player's opposite sex possessive (his/her)
`<  Put player's sex (him/her)
`>  Put player's opposite sex (him/her)
-----------------------------------------------------------------

The following LORD text color codes can also be used:

`1 dark blue            `2 dark green       `3 dark cyan
`4 dark red             `5 dark violet      `6 brown
`7 gray                 `8 dark gray        `9 light blue
`0 light green          `! light cyan       `@ light red
`# light violet         `$ yellow           `% white

Advisory note: Keep in mind that LORD IGMs display data against
black background.  Use dark colors with caution, since user
will possibly be unable to read them on-screen.
-----------------------------------------------------------------

Note: LORD Color Codes section provided by
      Gary Hartzell - iron.man11@verizon.net

Codes.txt created by Jason Brown - jmbrown@pcisys.net

Donald Tidmore, maintainer and updater.
Email: ktidmore@bellsouth.net.  OR donald.tidmore@usa.net.

End of Codes file for The Gateway IGM.
Updated on: October 28, 2002.

