                      +----------------------------------+                  MAXIMIZE THIS SCREEN
                      Ý     PURGE Kit  Reference File    Ý        WORD WRAP may interfere if resolution is below 1024x768
                      Ý      Designed for Verge 2.0      Ý
                      Ý           by Grenideer           Ý
                      Ý       Obsolete v2 Functions      Ý
                      Ý        Built-in Functions        Ý
                      Ý        Built-in Variables        Ý
                      +----------------------------------+


Current as of 10.31.3

++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
I. Obsolete v2 Functions

PaletteMorph() -- ALWAYS use PalMo() instead.
PlayMusic() -- still usable, but PURGE's Music() function is easier. If you use this for panning, music_playing will
               not be updated.
PlaySound() -- still usable, but PURGE's Sound() function is easier.
Map() -- It's better to use MapSwitch(). If you are merely manipulating maps and have no player, then using Map()
         is ok, although currentmap and lastmap will not be updated.
SetPlayer() -- ALWAYS use SetLeader() instead.

++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++


============================================================================================================================

II. Built-in Functions

---------------------------------------------
void AddChar(int partyindex,int notification)
---------------------------------------------
Adds the specified char referenced in PARTY.TXT to the end of the active party, notifying if specified. For notification,
enter a 1 - for no notification, enter a 0. If the party is currently full (ie. if there is a char[5]) then this will
say so and not add a party member.

See also: RemoveChar()

Example:
  AddChar(24,1);

---------------------
void AddItem(int itm)
---------------------
Adds the specified item (referenced in ITEMS.TXT) to the party inventory. If there is no available space, then a menu will
prompt the player to drop an item from inventory. Canceling at this point will cancel the pick-up and not drop any items
except the one being added. This dropping will not accidentally drop a Necessary item,nor let you cancel a pick-up of one.

See also: RemoveItem()

Example:
  AddItem(34);

------------------------------------------------
void AddSkill(int skll,int chr,int notification)
------------------------------------------------
Adds skill specified by skll to chr (chars are 1-99; not charslot), in the next available skill slot,with
notification(1) or none(0). A char's potential skills are referenced in PARTY.TXT, and these are added
automatically by leveling.
	Skills can either be gained by level, or by calling this function. Remember that the total combined skills
learned by both methods can not exceed 30 per char.
Example:
  AddSkill(1,7);

-------------------------------------------------
void AddXP(int charslot,int exp,int notification)
-------------------------------------------------
Gives the specified charslot [1-5] exp amount of XP. If this is enough to level the char, then LevelUp() is
automatically called, with notification if 1 (none if 0). If this is enough to LevelUp() the char multiple
times, it will automatically do so. This function is ideal for leveling a chr up a number of levels at once.

See also: LevelUp()

Example:
  AddXP(1,110);

-------------------------------------------
void AfflictState(int battlechar,int state)
-------------------------------------------
This battle function affects the current state the battlechar(1-5) is in. State can range from 0-4, as follows:
  0-normal
  1-stunned=battlechar loses turn next opportunity, then returns to normal
  2-bound=battlechar cannot use skills (may break out at end of turn)
  3-asleep=battlechar loses turn until damaged (may break out at end of turn)
  4-unconscious=battlechar loses turns
Since battlechars can only have one state at a time, higher-end states take precedence. If a battlechar is
bound, he can be put to sleep or rendered unconscious, but trying to stun him will have no effect. The only
time a state can be subtracted is when it is set to 0, to restore the character to normal.

Example:
  AfflictState(2,3);

------------------------------------------------
void AgilitySuccess(int charslot,int difficulty)
------------------------------------------------
Tests the charslot's agility (1-5) at a specified difficulty level (0-5). 0 is automatic, 1-easy--5-hard.
This is useful for non-battle skill scripts that wish to test a specific stat, or for other instances in the
game where you may want to do a D&D-type stat check. The scale for PURGE kit stats ranges from 1-100 usually,
so this is mainly useful in similar bounds.
	This function sets the success variable to 1 if the check is passed, otherwise to 0.

See also: StrengthSuccess(),WillSuccess()

Example:
  AgilitySuccess(4,0);
  If (success) { blah blah; )

----------------------------------------------------------------------------------------------------
void Animate(string imagefile,int width,int height,int xpos,int ypos,int frames,int delay,int layer)
----------------------------------------------------------------------------------------------------
This is the v2 version of PlayVAS. It basically plays a VergeAnimationStrip. Using a PURGE animation formatted image,
this function will play a series of frames, in effect playing an animation. Width and Height refer to each frame,
Xpos and Ypos point to the position onscreen where this will be displayed. Frames MUST reference the total number of
frames this imagefile contains, and delay is the time in roughly hundredths of a second between each frame. You may
specify any layer for this function, but OpenGraphicsLayers() must first be initialized.

************included sample.pcx VAS*********************************

See also: OpenGraphicsLayer(), CloseGraphicsLayers()

Example:
  Animate("strip.pcx",30,30,50,50,6,100,layer2);

-----------------------------------------------
void AutoEquip(int charslot,int class,int item)
-----------------------------------------------
Creates an item and equips the char with it automatically. Charslot is the active char[1-5]; class needs to match the
item being equipped, and item references ITEMS.TXT. Mostly useful for automatically equipping new chars with items,
without any notification at all.
Classes are 1-head,2-body,3-arms,4-legs,5-other,6-weapon.

See also: EquipOptions()

Example:
  AutoEquip(4,1,37);

---------------------
void AutoexecBattle()
---------------------
There are two kinds of maps that PURGE uses: battle maps and normal maps. This function must be in the autoexec of
EVERY BATTLE MAP. It includes a call to PalMo(), but more importantly enables map switching to function. This
function is what actually starts the entire battle interface. DO NOT call this function at the beginning of a
normal map.

See also: InitializeMap()

Example:
  AutoExecBattle();

-------------------------------------------------------------
void BannerPrompt(int xpos,int ypos,int layer,string message)
-------------------------------------------------------------
Displays a one-line banner message on a small menu background at xpos, ypos, on the selected layer. The message can be
any length that fits. This prompt is in essence a mini-menu with one option selected, and can be canceled closed (ALT)
or accepted (RETURN). Calling this in between the menu-interface funtions will estrange those variables from eachother.
OpenGraphicsLayers() must be initialized.

See also: OpenGraphicsLayers()

Example:
   BannerPrompt(140,5,layer4,"Got yellow potion");

--------------------------------------------------------------------
void BannerWait(int xpos,int ypos,int layer,string message,int time)
--------------------------------------------------------------------
Displays a one-line banner message on a small menu background at xpos, ypos, on the selected layer, as above. This
prompt is in essence a mini-menu, but with no option selected. Because of this, it can not be exited by the user. The
message lasts the specified time in hundredths of a second before going away. Calling this in between the menu-interface
funtions will estrange those variables from eachother. OpenGraphicsLayers() must be initialized.

See also: OpenGraphicsLayers()

Example:
  BannerWait(125,5,layer4,"Can't Drop virago whistle",100);

-------------------------------------------------------------------------------
void BattleAnimationGroup(string imagefile,int frames,int delay,string wavfile)
-------------------------------------------------------------------------------
Points to the PURGE kit format animation pcx file (imagefile). Frames and delay are used in the same way they are
in Animate(). Wavfile is the sound effect this animation has. Use this function ONLY in skill/item/SpAttack scripts
(in EFFECTS.VC) when the effect will point to all mons or chars. Although group effects are looped for each individual
target, wavfile will only play once.

************included bgroup.pcx VAS*********************************

See also: BattleAnimationTargeted(), Animate(), battletarget var

Example:
  BattleAnimationGroup("bgroup.pcx",5,20,"null.wav");

---------------------------------------------------------------------------------------------
void BattleAnimationTargeted(string imagefile,int frames,int delay,int target,string wavfile)
---------------------------------------------------------------------------------------------
Points to the PURGE kit format animation pcx file (imagefile). Frames and delay are used in the same way they are
in Animate(). Target points to the battletarget, and wavfile is the sound effect this animation has. Use this function
ONLY in skill/item/SpAttack scripts (in EFFECTS.VC) when the effect will point to a single target.

************included btarget.pcx VAS*********************************

See also: BattleAnimationGroup(), Animate(), battletarget var

Example:
  BattleAnimationTargeted("btarget.pcx",10,20,6,"null.wav");

--------------------------
void ClearLayer(int layer)
--------------------------
Used to completely clear the selected graphics layer. Graphics Layers must be open first, as they start clear anyway.
After this function call, render settings are restored to default (RestoreRenderSettings()).

ClearLayer() actually draws the blankness to the screen. If you are immediately redrawing
to this layer it can be seen as a visible blink. To avoid this, do it the hardcoded v2 way:
SetRenderDest(layer), then RectFill(0,0,screenx,screeny,0), then Render().

See also: OpenGraphicsLayers(), RestoreRenderSettings()

Example:
  OpenGraphicsLayers();
  DisplayImage("statmenu.pcx",80,5,layer1);
   [after picture is finished displaying]
  Wait(300);
  ClearLayer(layer1);

--------------------------
void CloseGraphicsLayers()
--------------------------
Used to clear, close, and free up the memory used by all the graphics layers, including layer5. Call this function
after you are finished displaying graphics to the screen, with the exception of Text(). All layers default to closed.

See also: OpenGraphicsLayers()

Example:
  OpenGraphicsLayers();
  DisplayImage("statmenu.pcx",80,5,layer1);
   [after picture is finished displaying]
  CloseGraphicsLayers();

-----------------------
void CompileInventory()
-----------------------
Organizes all item[] variables so there are no empty spaces in between. This is invisibly done automatically and need
never be manually called unless you are specifically changing the item variables.
	For example, if you changed item[13] to 0 (no item), then you would need to call CompileInventory(), or there
would be a visible space on the Inventory() menu.

See also: Inventory()

Example:
  item[13]=0;
  CompileInventory();

---------------------------------------------------------------------
void CreateMenu(int xpos,int ypos,int opts,int longestword,int layer)
---------------------------------------------------------------------
This function is the beginning of a series of functions designed to create a menu interface. What this function
specifically does is draw the menubox to the specified size. Xpos and ypos are the topleft coordinates of the box,
opts (options) is the number of rows down that will be in the menu box (20 max), longestword is the number of characters
that the longest word in the menu will be (to adjust for size automatically), and layer is the selected layer this menu
is drawn to (can NOT be layer5). This function should be followed by the Option(), Select(), and Switch() functions.
OpenGraphicsLayers() must be called before this function.
	This function uses the MENU.PCX file in the verge folder as the background, scaled to size. Unfortunately,
at this time, the grey border is hardcoded into the function- but that color can be changed with little effort.

See also: Option(), Select(), OpenGraphicsLayers()

Example:
  OpenGraphicsLayers();           //open/initialize layers
  CreateMenu(5,5,3,9,layer4);     //create menu box at 5,5, with 3 options up to 9 charaters long
   Option(1,"Profile");           //first option drawn
   Option(2,"Inventory");         //second option drawn (longest option, which is why menu is set to 9 chrs)
   Option(3,"Journal");           //third option drawn
   Select(1);                     //actual selection process, starting on option 1 (Profile)-- returns choice
  Switch(choice)                  //applies result based on choice
  {
   case 0: CloseGraphicsLayers(); //choice is 0 when menu is canceled (ALT)
   case 1: Profile();             //choice 1 calls function
   case 2: Inventory();           //choice 2 calls function
   case 3: Journal();             //choice 3 calls function
  }
  CloseGraphicsLayers();

--------------------------------
void DamageChar(int chr,int dmg)
--------------------------------
This function will deduct dmg number of points from the specified char in the charslot(chr). If used in battle,
it will display the damage inflicted, but otherwise can be used in nonbattle situations to lower vigor.

See also: HealChar()

Example:
  DamageChar(5,13);

-----------------------------------
void DamageMon(int monster,int dmg)
-----------------------------------
This function will cause dmg amount of damage points to the given monster(1-5). It will likewise display
the damage inflicted and kill the monster upon reaching 0.

See also: HealMon(), KillMon()

Example:
  DamageMon(2,12);

--------------------------------
void Darken(int span, int light)
--------------------------------
Fades the screen blacker, to the specified light variable (ranging from v2's 0-63 light value). Span is the approximate
time this fading takes, in hundredths of a second. This fading provides a smooth transition from the current light level,
and need not fade all the way to black (0). To lower the light level automatically, call this function with span=0.

See also: Lighten(), PalMo()

Example:
  Darken(200,20);

---------------------------
void DestroyEntity(int ent)
---------------------------
A simple function that v2 sorely lacked. This will destroy the entity (ent) specified. Technically this entity is being
warped to coordinates -1,-1. This means that if you are calling this function on the cameratracked player, or a
likewise tracked entity, then the map will reset to it's top left corner.

Example:
  DestroyEntity(4);

------------------------------------------------------------
void DisableMove(int nodown,int noup,int noleft,int noright)
------------------------------------------------------------
Place this function in a single-square zone on a map where you wish to restrict player movement. If a direction is
flagged with a 1 then the player may not move that direction from that tile. It is important not to place adjacent
zones where the character *MAY* walk to, because that zone will not work. If it is not important that the adjacent
zone doesn't work, or if the zone is in a direction which is disabled from the player, then you may place the zone.
	This function is especially useful when you want to simulate map obstructions without having a full tile
blocked off from the map. Ie., you can simulate a horizontal line as an obstruction with a nodwon from the top and
a separate noup from the bottom, while still allowing all the tiles to be walked on, just not across that line.

Example:
  DiableMove(1,0,0,0);

--------------------------------------------------------------
void DisplayImage(string image, int xpos, int ypos, int layer)
--------------------------------------------------------------
Displays the selected (supported v2 file-type) image, with the x and y positions as the top left of the image. Can be
pointed to layers 1-5. This image will display onscreen until either the specific layer is turned off or all the layers
are closed. Note that even with the graphics layers opened, layer5 defaults to off.

See also: OpenGraphicsLayers(), DisplayScaledImage()

Example:
  OpenGraphicsLayers();
  DisplayImage("statmenu.pcx",80,5,layer1);
   [after picture is finished displaying]
  CloseGraphicsLayers();

-----------------------------------------------------------------------------------
void DisplayImageSelection(string imagefile, int xpointer, int ypointer, int width,
                           int height, int xpos, int ypos, int layer)
-----------------------------------------------------------------------------------
Displays the selected image as per DisplayImage() above, but this displays only a selected portion of the imagefile.
The x an y pointer point to the top-left of the clipped section from the imagefile, and the width and height are needed
to complete the square selection size. The result image can be placed anywhere on the screen, as usual. This function
is used internally to gather speech portraits, etc., from files - but can clip any portion of any v2 supported image
file for onscreen display.
It is important to realize that the image blitted to the screen can have transparencies, but these areas will clear
the portions of the graphics layer where there are used (as opposed to still being able to see parts of an image
below it on the same layer). This is because in most cases this function is used to change a stance of a sprite, and
this requires clearing the old one.

See also: OpenGraphicsLayers(), DisplayImage()

Example:
  OpenGraphicsLayers();
  DisplayImageSelection("speech.pcx",x,y,32,32,15,135,layer5);
   [after picture is finished displaying]
  CloseGraphicsLayers();

------------------------------------------------------------------------------------
void DisplayScaledImage(string image, int xpos, int ypos, int x1, int y1, int layer)
------------------------------------------------------------------------------------
Displays the selected image as per DisplayImage() above, but resizes the file to x1 width and y1 height.

See also: OpenGraphicsLayers(), DisplayImage()

Example:
  OpenGraphicsLayers();
  DisplayScaledImage("menu.pcx",10,10,20,100,layer2);
   [after picture is finished displaying]
  CloseGraphicsLayers();

-----------
void Draw()
-----------
Refreshes all the graphics layers specified as ON and draws them to the screen, processing entity movement and restoring
all render settings to the default. This is an internal function that does not need to be called unless you want to.
Whenever the graphics layers are open, this command is automatically hookretraced.

See also: LayerOn[] variable

Example:
  Draw();

---------------------------
void DropItem(int itemslot)
---------------------------
Like ItemSlotEffect(), this is an internal command and not too useful unless making menus. It drops the item in the given
itemslot [1-30] and Compiles the Inventory afterwards. To remove specific items, instead use RemoveItem().

See also: RemoveItem(), ItemSlotEffect()

Example:
  DropItem(21);

------------------------------------
void EntityWarp(int ent,int x,int y)
------------------------------------
Warps the entity (ent) to the specified map coordinates immediately.

See also: Warp(), MapSwitch()

Example:
  EntityWarp(7,83,4);

----------------------------------
void EquipList(int char,int class)
----------------------------------
Called automatically by EquipOptions(), or can be called manually to skip that step. Char references the active party,
as with EquipOptions(), and class mimics the selection of EquipOptions(). The following menu shows what items are
available to equip on that char in that class out of the current party inventory. As with Inventory(), pushing
left/right will toggle the menu if more than 5 items are available. Selecting the item equips it.
Class-1-head,2-body,3-arms,4-legs,5-other,6-weapon.
	This command calls ShowStats() and/or ShowStatBonuses(), which can be edited from the default SYSTEM.VC. If
these commands are used, then whatever equipable item is selected will display its statistic bonuses if whatever
format these two commands are set up to use.

See also: EquipOption()

Example:
  EquipList(5,1);

---------------------------
void EquipOptions(int char)
---------------------------
Shows the equipable locations (class-weapon,head,body,etc.) for the specified char. Char references the active party,
char[1] through char[5]. This begins the entire menu driven equip process, calling EquipList() automatically when the
location to equip is selected.
	Care should be taken to avoid calling this when the char is dead, unless your game uses a wounded system
where dead chars can perform actions in camp.

See also: EquipList(), AutoEquip()

Example:
  EquipOptions(2);

--------------------------------
void Face(int ent,int direction)
--------------------------------
Just like v1's command (except for updating facing values), this function does what v2's entity.facing[] variable
should do. The specified entity (ent) will immediately face the given direction(0-down,1-up,2-left,3-right). Works
on the party leader as well.

Example:
  Face(player,3);

----------------------
int FindChar(int char)
----------------------
This function returns the line number of the given char NAME in PARTY.TXT. This is useful when manually manipulating
PARTY.TXT. This function does not use the file in any way - it just mathematically computes the number of the line for
the char specified.

Example:
  pointer=FindChar(23);

----------------------
int FindItem(int item)
----------------------
This function returns the line number of the given item NAME in ITEMS.TXT. This is useful when manually manipulating
ITEMS.TXT. This function does not use the file in any way - it just mathematically computes the number of the line for
the item specified.

Example:
  pointer=FindItem(45);

------------------------
int FindMon(int monster)
------------------------
This function returns the line number of the given monster NAME in MONSTERS.TXT. This is useful when manually
manipulating MONSTERS.TXT. This function does not use the file in any way - it just mathematically computes
the number of the line for the monster specified.

Example:
  pointer=FindMonster(45);

-----------------------
int FindSkill(int skll)
-----------------------
This function returns the line number of the given skill NAME in SKILLS.TXT. This is useful when manually manipulating
SKILLS.TXT. This function does not use the file in any way - it just mathematically computes the number of the line for
the skill specified.

Example:
  pointer=FindSkill(3);

-------------------------------
void FindSpAttack(int spattack)
-------------------------------
This function returns the line number of the given special attack NAME in SPATTACK.TXT. This is useful when manually
manipulating SPATTACK.TXT. This function does not use the file in any way - it just mathematically computes the
number of the line for the special attack specified.

Example:
  pointer=FindSpAttack(17);

---------------
void GameMenu()
---------------
This function opens up the three game options, Save, Load, and Exit. Save and Load call up their respective menus.

See also: SaveMenu(), LoadMenu()

Example:
  GameMenu();

----------------------------------------
void GainSpirit(int points,int charslot)
----------------------------------------
Adds points of Spirit to charslot. This is called automatically and only need be used when manually manipulating
Spirit. Of course, it will not raise Spirit above it's maximum value, determinate by level.

See also: LoseSpirit()

Example:
  GainSpirit(50,5);

------------------------------
void HealChar(int chr,int vig)
------------------------------
Raises the avigor of the given char in the charslot(chr) by vig points. This value cannot exceed the maximum
vigor, and can be used in and out of battle, with the former display the amount healed.

See also: DamageChar()

Example:
  HealChar(2,3);

---------------------------------
void HealMon(int monster,int vig)
---------------------------------
Will raise the specified monster's(1-5) monvig, by vig number of points. Of course, the total monvig cannot exceed
it's maximum amount. A display of the vig healed will be shown.

See also: DamageMon()

Example:
  HealMon(4,20);

-------------------------
void InitializeLoadGame()
-------------------------
To be used every time you LOAD a SAVED game. This function includes a call to PalMo().

See also: InitializeNewGame()

Example:
  InitializeLoadGame();

--------------------
void InitializeMap()
--------------------
There are two kinds of maps that PURGE uses: battle maps and normal maps. This function must be in the autoexec of
EVERY NORMAL MAP. It includes a call to PalMo(), but more importantly enables MapSwitch to function. DO NOT call
this function at the beginning of a battle map.

See also: AutoExecBattle()

Example:
  InitializeMap();

------------------------
void InitializeNewGame()
------------------------
To be used at the beginning of a NEW game ONLY. Once a game is saved, do not use this on it. This function includes
a call to PalMo(), and also requires that SYSTEM.FNT be in your verge directory. This will be the main font used by
PURGE.

See also: InitializeLoadGame()

Example:
  InitializeNewGame();

--------------------------------------------------
void Inn(string innwelcome,int cost,int resurrect)
--------------------------------------------------
An automatic menu function for automatic inns. Innwelcome is a simple welcome string that cannot exceed 20 characters.
It can be left blank if you want. Cost will be the gold amount deducted for the visit, and resurrect will determine
whether dead chars are affected (1) or ignored (0).

See also: RestoreAll()

Example:
  Inn("Rest yourself.",75,1);

----------------
void Inventory()
----------------
Displays the entire inventory list for the party. There are two menus of 15 items each, which can be toggled by pushing
left/right (if needed). Accepting an item will use the item, discarding it if not Multi-Use. Pressing 'd' will drop the
selected item, if not Necessary. Items on the list are variables item[1] to item[30], in that order.

See also: CompileInventory()

Example:
  Inventory();

-------------------------------------
void ItemDamage(int lower,int higher)
-------------------------------------
Every item automatically defaults to 0 dmg. In battle, for an item to cause damage, you must manually assign
the global variable 'damage' a number. This number is the final result, and will not be modified in any way.
Item damage SHOULD take into account a char's agility, and the mon's defense. This is what this function does.
	In the actual item script, assign a lower and a higher value for the item damage. This will not only
make the item damage variable within a range, but will take into account modifiers. For a static damage
amount that will still take modifiers into account, make lower and higher equal the same value. Of course, if you
want a special item to ALWAYS do the same amount of damage regardless of agility/defense, you can always
just make damage=whatever in the item script. Also, this obviously only works for battle items.

See also: SkillDamage(), SpAttackDamage(), damage variable

Example:
  SkillDamage(3,7);

-------------------------
void ItemEffect(int item)
-------------------------
Calls the script (in EFFECTS.VC) of the selected item. The result is the same as if using the given item, except this
command does not need or use any actual item in inventory.

See also: ItemSlotEffect()

Example:
  ItemEffect(2);

---------------------------------
void ItemSlotEffect(int itemslot)
---------------------------------
This command uses the item from the specified itemslot [1-30], discarding if not Multi-Use. It is a lot less useful than
ItemEffect() because it doesn't matter what item is in the slot. It is used internally for the Inventory() function, and
similar menus can be made with it, as with DropItem().

See also: ItemEffect(), DropItem()

Example:
  ItemSlotEffect();

-------------------------
void KillMon(int monster)
-------------------------
Usually called when DamageMon() inflicts lethal damage, you can manually use this to automatically kill
the specified monster, regardless of monvigor.

See also: DamageMon()

Example:
  KillMon(1);

-------------------------------------------
void LevelUp(int charslot,int notification)
-------------------------------------------
Automatically called when AddXP raises a char's level, but can be manually called at any time to force a level. When
this is called, it raises the char in the specified charslot[1-5] one level, notifying if 1, or not if 0. If the XP of
the char in the charslot is not enough to be at the new level, then the XP value is raised to the minimum required
by that level. This is useful when manually raising a char a level or two.

See also: AddXP()

Example:
  LevelUp(5,0);

---------------------------------
void Lighten(int span, int light)
---------------------------------
Brightens the screen from black values, to the specified light variable (ranging from v2's 0-63 light value). Span is
the approximate time this brightening takes, in hundredths of a second. This brightening provides a smooth transition
from the current light level, and need not brighten all the way to full light (63). To raise the light level automatically,
call this function with span=0.

See also: Lighten(), PalMo()

Example:
  Darken(200,20);

----------------------------
void LoadBattle(string bmap)
----------------------------
The first in a series of functions to kick off a battle. Bmap stores the battle map that this battle will
take place in. MUST be called to initialize battle variables, and Monster() calls must follow.

See also: Monster(), StartBattle(), AutoExecBattle()

Example:
  LoadBattle("battle02.map");
   Monster(1,1);
   Monster(2,2);
   Monster(3,2);
  StartBattle();

---------------
void LoadMenu()
---------------
This function opens up the load menu, listing the 5 loadslots that can be loaded.

See also: SaveMenu(), GameMenu()

Example:
  LoadMenu();

--------------------------------------
void LoseSpirit(int cost,int charslot)
--------------------------------------
Deducts cost amount of Spirit points from charslot. This is called automatically and only need be used when
manually manipulating Spirit.

See also: GainSpirit()

Example:
  LoseSpirit(6,1);

--------------------------------------------------------------
void MapSwitch(string mapname,int x,int y,int facing,int fade)
--------------------------------------------------------------
Switches player to the specified map, starting at the specified coordinates, facing as specified, with a fade if 1,
no fade if 0. Because of v2's current entity system, the new map must have InitializeMap() in it's autoexec for this
to work. Also, unlike it's v1 counterpart, the PURGE version of MapSwitch() needs to spawn a character. In order to
do this, AT LEAST ONE CHAR must be in the active party, with the first one becoming the leader (via SetLeader() )
if already not. This may sound complicated, but in normal use you WILL have at least one char in the party and
the char in charslot 1 (char[1]) will already be the leader. When you need to take this into account is really at
times, like at the title screen, when you may not have added a char to the party yet but want to switch to the
first map. Just make sure to call AddChar() first- MapSwitch() will call SetLeader() for you.
	This function updates two global variables: currentmap and lastmap. Currentmap becomes the map you are
switching to, and lastmap hold what currentmap used to hold (ie. the last map you were on). Again, if this is a
NEW GAME where there WAS no last map, lastmap will be blank. Because of these variables, this function supercedes
the v2 Map() function, which should NEVER be used. If you absolutely MUST use Map(), make sure you update the
lastmap and currentmap variables manually to the correct settings.

See also: InitalizeMap(), Warp(), currentmap and lastmap variables

Example:
  MapSwitch("dungeon.map",45,23,0);

------------------------------------
void Merchandise(int order,int item)
------------------------------------
Must be called AFTER SetUpShop(). In order to open a shop window in-game, you must first tell PURGE what items
are stocked. Each shop has a maximum of 8 slots. Merchandise can be called once per slot, and less if needed.
Order will hold the slot being stocked (and should be called *in* order), and item is the item number (referenced
in ITEMS.TXT) that will fill the slot. A call to OpenShop() must follow the last Merchandise() call.

See also: SetUpShop(), OpenShop()

Example:
  See SetUpShop() example

-------------------------------------
void Monster(int monslot,int monster)
-------------------------------------
The second function to be called to get into battle. Must be used AFTER LoadBattle() but BEFORE StartBattle().
Monslot is the order of the monster (referenced in MONSTERS.TXT). Monslot can be called only once for each
open slot (1-5, since you can fight 5 maximum monsters).
	Instead of using any specific Monster calls, you can call RandomizeMons instead.
   	Monster() (not Randomize, though) can also be called DURING battle to respawn monsters, but make sure you
call UpdateBattleScreen() afterwards. It will replace the mon[] currently in the monslot,if any.

See also: LoadBattle(), RandomizeMons(), StartBattle(), AutoExecBattle()

Example:
  see LoadBattle() example

----------------------------------
void Music(string song,int volume)
----------------------------------
This function overrides the v2 PlayMusic() function. It plays the specifed v2-supported module at the specified
volume(0-100). It is VITAL that the song string be ALL LOWERCASE. Music_volume is automatically set (a normal v2
variable) and music_playing is also set (a new PURGE kit variable). The advantage of music_playing it that if you try
to play a song already being played, it will not restart. For this to always work, YOU MUST NOT initialize music
through the maps (in MapEd) EVER. Instead put it on the first line or so of all your maps. It enables a LOT better
control.
	You can technically still use the old v2 method, but you need to make sure to set the music_playing variable
yourself. This is useful when you want to control the panning.

See also: music_playing var, MusicFadeOut(), MusicFadeIn()

Example:
  Music("arcolite.xm",35);

--------------------------------------
void MusicFadeIn(int span, int volume)
--------------------------------------
This fades the music_volume variable from a lower initial value to volume (1-100), at a specified span.

See also: MusicFadeOut(),  Music(), music_playing var

Example:
  MusicFadeIn(200,35);

---------------------------------------
void MusicFadeOut(int span, int volume)
---------------------------------------
This fades the music_volume variable from a higher initial value to volume (0-99), at a specified span.

See also: MusicFadeIn(),  Music(), music_playing var

Example:
  MusicFadeOut(300,0);

-------------------------
void OpenGraphicsLayers()
-------------------------
Initializes all 5 graphics layers as blank. Layers 1-4 are also turned 'ON' (visible) but layer5 (the text layer) starts
'OFF'. You MUST use this function before calling any graphics function (Menu(), DisplayImage(), etc.) with the exception
of Text(). It is important to note that you DO NOT have to close these layers before reopening them - this function first
closes all layers just as the CloseGraphicsLayers() function does. IE. You can recall this function to clear all layers
and continue displaying graphics to the screen. All layers default to closed. It is a good idea to pretty much never use
Layer5, the text layer, manually.

See also: CloseGraphicsLayers(), LayerOn[] variables

Example:
  OpenGraphicsLayers();
  DisplayImage("statmenu.pcx",80,5,layer1);
   [after picture is finished displaying]
  CloseGraphicsLayers();

---------------
void OpenShop()
---------------
The last of the three shop-support functions, this must be called after the final Merchandise() call. This
function is what actually opens up the Buy/Sell window and enables the player to navigate through the shop.
Shop windows show how much gold the player currently has, how much items cost, and who can use selected items.

See also: SetUpShop(), Merchandise()

Example:
  See SetUpShop() example

-----------------------------------
void Option(int option,string name)
-----------------------------------
This is the second of a series of menu interface functions, which follows after CreateMenu(). This funtion overlays the
name of the option on the menu in the option position listed, and is drawn to the layer called by the last CreateMenu().
This function is called once for each option listed, in numerical order (the option variable counts up from 1), with the
last option coinciding with CreateMenu()'s number of options listed (20 max).
	Leaving a single blank space as the name (" ") will leave a blank space in the menu for that option. While you
can technically do this by calling no option, or with multiple blank spaces, the single blank space (" ") allows for the
Select() function the skip over this space as if it weren't an option. Otherwise, you would be able to select the blank
space as a menu option. Leaving a " " as an option is useful for creating fixed-height menus. This function should be
followed by the Select(), and Switch() functions.

See also: CreateMenu(), Select()

Example: See CreateMenu() example

--------------------------------------------------------
void PalMo(int red,int green,int blue,int mix,int light)
--------------------------------------------------------
Replacement shelled funtion for PaletteMorph()- NEVER use the v2 palettemorph(), ALWAYS use PalMo() instead. This function
is exactly the same as PaletteMorph, except it keeps track of a lighting variable needed for Lighten() and Darken() to
operate correctly. This variable should NOT be changed, as it doesn't affect the current lighting status.

See also: Lighten(), Darken()

Example:
  PalMo(0,0,0,0,63);

--------------------
void PauseEntities()
--------------------
This stops all entities from moving until they are unpaused. It is useful for textboxes and menus, and is called
internally by CreateMenu() and other PURGE kit functions. This only works on the first 100 map entities, not on the
player or any spawned entities.

See also: UnPauseEntities(), entpaused var

Example:
  PauseEntities();

-------------------------------------------
void PoisonChar(int charslot,int poisonlvl)
-------------------------------------------
This funtion can be used in and out of battle, and sets the charslot to a certain poisonlvl(0-5). 0 will restore a
charslot to an unpoisoned state. For each poison level, a battlechar will lose 4% of his health each round. So if
a battlechar is currently at poisonlvl 2, he will lose 8%. Whether you are in battle or not has no bearing on
whether a charslot is poisoned or not, but actual poison damage ONLY OCCURS IN BATTLE.
	This 'variable' poison level can increment or decrement, and is what differs PURGE kit poison from other games.
This poisonlvl is invisible to the player, however. If a player is currently not poisoned, then you can set the initial
posinlvl to any number, and the charslot will be affected to that level. However, if a charslot is already poisoned at
the time, then his poisonlvl will only increment by one, to a maximum of five. In battle, charslots may naturally heal
from poison, and their poisonlvl will decrement until they are completely healed. Items and such should automatically
set this value to 0.

See also: poison[] var

Example:
  PoisonChar(5,3);

---------------------------------------------------------
void PrintStringRightJust(int font,string line,int width)
---------------------------------------------------------
Just like v2's PrintString(), but right justifies the print to fit a column width characters long. Is useful
when printing tables or values.

Example:
  PrintStringRightJust(font, str((agility[char[charslot]])), 3);

---------------------------
int Probability(int chance)
---------------------------
Given a percentage chance (0-100), returns a 1 if the likelihood is met, and a 0 if not. For example, if you want
something to have a 37% chance of happening, you would call Probability and pass the value of 37. PURGE will
calculate a random number, and if it 'rolls' your 37% chance, this function will return a 1, meaning a success. A
0 will be returned if the event did not happen. Obviously, a chance of 0 will always return a 0, and passing 100
will always return a 1.

Example:
  chanceofhappening=Probability(33);

----------------------------------------------------------------------------------
void RandomizeMons(int minmons,int maxmons,int montype1,int montype2,int montype3)
----------------------------------------------------------------------------------
A special function more useful to actual game mechanics, this essentially replaces the Monster() function. It
must be called AFTER LoadBattle() and BEFORE StartBattle(). Whereas Monster() may be called up to 5 times
in between these two, RandomizeMons will only be called once. Minmons and maxmons specify
the minimum and maximum number of monsters you want to be possible for the battle. The values must range from
1-5, and minmons cannot be higher than maxmons and vice-versa. The three montypes are the three possible
monsters that you want loaded into battle; set the value to the monster number indexed in MONSTERS.TXT. You 
an leave one or two blank if you want by setting a 0 value. Or, if you want two monsters and you wish to have
one of the two monsters more likely to appear (and in greater number) you can set montype 1 & 2 as the same
monster's index, with the third as the different one.
	This functions is especially useful for random map battles where you have a certain class or strength of
monsters that you want for the battles, yet do not wish to randomize each battle yourself.

See also: Monster(), LoadBattle(), StartBattle(), AutoexecBattle()

Example:
  LoadBattle("battle02.map");
   RandomizeMons(2,4,7,18,0);
  StartBattle();

-----------------
void RemoveChar(int chr,int notification)
-----------------
More useful than RemoveCharSlot(), because this will remove the specified char no matter what order the party is in.
Chr references the char in PARTY.TXT; 1 for notification and 0 for none. If the given char is not in the party, a
message will say so.

See also: AddChar(), RemoveCharSlot()

Example:
  RemoveChar(45);

--------------------------------------------------
void RemoveCharSlot(int charslot,int notification)
--------------------------------------------------
Removes the char in the specified charslot, notifying if a 1 is specifed (pass a 0 for no notification). Charslot must
reference the active party (1-5). This command is not nearly as useful as RemoveChar(), because this command can only
specify the charslot to remove. It is better used to drive menus.

See also: RemoveChar()

Example:
  RemoveCharSlot(3,0);

----------------------------
void RemoveItem(int itemref)
----------------------------
Removes every instance of the specific item from the party inventory. It does NOT remove any equipped item, however.
This is more useful than DropItem(), which is better used internally in menus.

See also: DropItem(), AddItem()

Example:
  RemoveItem(45);

------------------------------
void RestoreAll(int resurrect)
------------------------------
This function restores all party members to maximum vigor and spirit. If resurrect is set to 1, dead characters
will be affected, if 0, they will be left alone. Useful for inns/savepoints.

See also: Inn()

Example:
  RestoreAll(1);

---------------
void SaveMenu()
---------------
This function opens up the save menu, listing the 5 saveslots that can be saved to.

See also: LoadMenu(), GameMenu()

Example:
  SaveMenu();

--------------------------------------------------------------------------------------------------------
void ScaleImage(string image, int xorigin, int yorigin, int x0width, int y0height,
                int x1width, int y1height, int leftinc, int rightinc, int upinc, int downinc, int layer)
--------------------------------------------------------------------------------------------------------
Complicated function that displays a series of scaled images to the selected layer, actually resizing in real time. Similar
to DisplayScaledImage(), except for the following: x0width and y0height are the starting values when the image is first
displayed, and the x1width and the y1height are the end result values that the image will be at when the scaling is
finished. The respective increments are the PIXEL value that each side will increment, either outward or inward. This
function will clear the target layer of any other images.
	This is a powerful function that has more facets than immediately noticeable. First off, any image can either be
enlarged or shrunk, OR enlarged on one axis while simultaneously being shrunk on the other. Also, because of the ability
to specify where the size increments take place, you can have an image fixed on say, the left side, and have it scale
outward to the right (leftinc=0, rightinc>0). The higher the increment value, the faster this scaling will take place.
Better results are achieved when the increment values are exactly divisible by the change in pixel size. (For example, a
40X10 picture can be enlarged seemingly at center to 80x20 -- best results would be achieved by setting the left and right
increments to 4 and setting the up and down increments to 1.)
	Also of note with this function- the BASE for incrementation is calculated differently for enlarging and shrinking.
Unfortunately, this means you can not enlarge and shrink an image in the same spot by simply changing the 0 and 1 width
and height values, as would be assumed. This is due to the fact that the origin values of the image are NOT pointing to
the center of the image, but to the left-top of it (in order to be more obvious with the other functions). To create the
effect of an image enlarging and shrinking on the same center axis, not only would the 0 and 1 width values need to be
swapped, but the origin values would need to be adjusted.

See also: OpenGraphicsLayers(), DisplayScaledImage()

Example:
  OpenGraphicsLayers();
  ScaleImage("profile.pcx",40,5,0,60,50,60,6,6,0,0,layer2);
   [after picture is finished displaying]
  CloseGraphicsLayers();

------------------
void ScreenSlide()
------------------
This function slides the screen over in the direction the player is facing (a la zelda 1 style). The axis the player
is on is shared by both screens (ie. the edge of the screen with the ScreenSlide() zone). Cameratracking MUST equal 0
for this to work.

Example:
  ScreenSlide();

--------------------------
void Select(int selection)
--------------------------
The third function used for menu interfaces, after CreateMenu() and Option(). This is where the actual player selection
and menu navigation takes place. Selection determines which option starts highlighted. Pressing UP and DOWN will cycle
the highlight, RETURN will select whatever is highlighted, and ALT will cancel out of the menu without a selection.
Choice is the variable this function 'returns' (this function does not technically return a variable, but it changes
the global variable 'choice'). If the option chosen is 1, then choice=1. If the menu is canceled, choice=0. This
function is what actually draws the highlight (on layer5 - which is why menus can not be drawn there). This function
should be followed by the Switch() code-control structure, to determine the result of the selection.

See also: CreateMenu(), Option(), choice variable

Example: See CreateMenu() example

---------------------------------------------------------------
void SetLeader(int charslot,int locx,int locy,int notification)
---------------------------------------------------------------
Sets the specified charslot as the leader of the party, at the given coordinates, with notification if a 1 is specified
(0 for none). The leader will become the visible entity as specified in PARTY.TXT, and the old leader entity will
disappear.
	Never use the v2 SetPlayer() command. This function automatically does that for you, and using SetPlayer()
also will mix things up.

Example:
  SetLeader(2,45,52,1);

------------------------------
void SetUpShop(string welcome)
------------------------------
The first in a series of commands enabling ITEM shop support. This function initializes the shop, and welcome
holds the greeting that will be displayed when the shop is open. Call the Mechandise() function next.

See also: Merchandise(), OpenShop()

Example:
  SetUpShop("Hey partner!");
   Merchandise(1,1);
   Merchandise(2,3);
   Merchandise(3,4);
   Merchandise(4,5);
  OpenShop();();

----------------------------
void ShowStats(int charslot)
----------------------------
*This function is an opensource PURGE kit function, meaning you can and should edit it to fit your game.*
Defaults to showing the stats of the char in the given charslot, useful for menus.

See also: ShowStatBonuses()

Example:
  ShowStats(3);

-------------------------------------------
void ShowStatBonuses(int charslot,int item)
-------------------------------------------
*This function is an opensource PURGE kit function, meaning you can and should edit it to fit your game.*
Defaults to calling ShowStats(), and then showing the bonuses the specified item gives the char in the charslot.
If a 0 is called for item, then stats are shown without any bonuses.

See also: ShowStats()

Example:
  ShowStatBonuses(2,45);

--------------------------------------
void SkillDamage(int lower,int higher)
--------------------------------------
Every skill automatically defaults to 0 dmg. In battle, for a skill to cause damage, you must manually assign
the global variable 'damage' a number. This number is the final result, and will not be modified in any way.
Skill damage SHOULD take into account a char's will, and the mon's defense. This is what this function does.
	In the actual skill script, assign a lower and a higher value for the skill damage. This will not only
make the skill damage variable within a range, but will take into account modifiers. For a static damage
amount that will still take modifiers into account, make lower and higher equal the same value. Of course, if you
want a special skill to ALWAYS do the same amount of damage regardless of will/defense, you can always
just make damage=whatever in the skill script. Also, this obviously only works for battle skills.

See also: ItemDamage(), SpAttackDamage(), damage variable

Example:
  SkillDamage(3,7);

---------------------------------------
void SkillEffect(int skll,int charslot)
---------------------------------------
Calls the script (in EFFECTS.VC) of the selected skill. The charslot needs to be given to deduct the appropriate
Spirit, as well as for some targeting concerns.

See also: SkillList()

Example:
  SkillEffect(13,2);

----------------------------
void SkillList(int charslot)
----------------------------
This is the main menu for the skill process. This function displays the known skills for the char in the given
charslot. A separate window will also show the selected skill's spirit cost, camp target, battle target, and
basic description. Selecting the skill will use it.
	Care should be taken to avoid calling this when the char is dead, unless your game uses a wounded system
where dead chars can perform actions in camp.

See also: SkillEffect()

Example:
  SkillList(5);

---------------------------------
void SkillSuccess(int difficulty)
---------------------------------
Designed for NON-OFFENSIVE skills only.
All skills don't need to be automatic. This function can be used in a skill script in EFFECTS.VC to determine if the
given skill succeeds. The difficulty rating can be from 0-automatic,1-easy--5-hard. The higher the char's Will who
is using the skill, the better chance of success. Note that it can be Impossible for a lower level char to succeed
at higher difficulty skills. You'll need at least a Will=50 to have a 20% chance of success if the difficulty is
5. Test it out to find how hard the difficulties are. This function returns the result to the global variable
success. If success=1, you succeed. If success=0, fail. Only use this for skills targeting your friendly party. Can
not be used as offensive; if used in battle, it must target a party member.
	If you want a skill to be automatic, you obviously never need to call this function, but I enabled you to
pass a 0 for automatic skills just in case you wanted to use this function in a script somewhere. Nothing automatically
tests for success, so you'll need to create an If statement in the skill script.

See also: success variable

Example:
  SkillSuccess(2);
  If (success)
  {
   If (battleon)
   {
    HealChar(battletarget,10);
   }
   If (!battleon)
   {
    HealChar(itemtarget,10); //itemtarget is used interchangeably for items and skills
   }
  )

---------------------------------------------------------------------------------------------------------
void SlideImage(string image,int xorigin,int yorigin,int xtarget,int ytarget,int inc,int delay,int layer)
---------------------------------------------------------------------------------------------------------
Slides the specified image either up, down, left, or right- otherwise similar to DisplayImage(). The x and y origins
are the coordinates to the starting top-left image position, and the x and y targets are the coordinates for the final
position, which is where the slid image stays at a standstill after this function is through. Inc determines how many
pixels at a time the image increments, sacrificing smoothness for speed (1-50 recommended). The delay is how long in
milliseconds that the image slides to the next increment (1-50 recommended). This function will clear the target layer
of any other images. OpenGraphicsLayers() must be initialized.
	This function is limited to sliding on only one axis, which means that either the set of x values or the y
values must be equal to eachother, with the other set being NOT equal to eachother.

See also: OpenGraphicsLayers(), DisplayImage()

Example:
  OpenGraphicsLayers();
  SlideImage("console.gif",320,50,0-320,50,20,1,layer4);
  CloseGraphicsLayers();

----------------------------------------
void Sound(string soundfile, int volume)
----------------------------------------
A dumbed down version of v2's PlaySound that doesn't require you to cache or free variables. It simply plays
the specified soundfile at the specified volume (0-mute/64-loudest). Of course, this doesn't let you control
panning, so you are free to use v2's PlaySound() if you like.
	This function loads a new sound each time it is called, and v2 only supports 100 loaded sounds at once. You
should use FreeAllSounds() liberally during play after many sounds are called with this function. InitializeMap() and
the battlesystem frees sounds. It is a good idea to free sounds in the beginning of your menus as well. This is not
very neat code but it beats having to index wavs by number and load them into libraries of 100 at a time - trust me.
Then again, feel free to use v2's PlaySound() any way you see fit.

Example:
  Sound("hit.wav",64);

------------------
void StartBattle()
------------------
The last function that actually MapSwitches and begins the battle, this mus be called AFTER either the Monster()
function or the RandomizeMons() function (whichever you used for this battle). AutoExecBattle() MUST be in the
target battle map, otherwise no battle will occur.

See also: LoadBattle(), Monster(), RandomizeMons(), AutoExecBattle()

Example:
  see LoadBattle() example

-------------------------------------------------
void StrengthSuccess(int charslot,int difficulty)
-------------------------------------------------
Tests the charslot's strength (1-5) at a specified difficulty level (0-5). 0 is automatic, 1-easy--5-hard.
This is useful for non-battle skill scripts that wish to test a specific stat, or for other instances in the
game where you may want to do a D&D-type stat check. The scale for PURGE kit stats ranges from 1-100 usually,
so this is mainly useful in similar bounds.
	This function sets the success variable to 1 if the check is passed, otherwise to 0.

See also: AgilitySuccess(),WillSuccess()

Example:
  StrengthSuccess(2,1);
  If (success) { blah blah; )

-----------------------------------------
void SpAttackDamage(int lower,int higher)
-----------------------------------------
Every special attack automatically defaults to 0 dmg. For a special attack to cause damage, you must manually
assign the global variable 'damage' a number. This variable is the final result, and will not be modified in any
way. Special attack damage SHOULD take into account a mon's agility, and the char's defense. This is what this
function does.
	In the actual special attack script, assign a lower and a higher value for the special attack damage.
This will not only make the special attack damage variable within a range, but will take into account modifiers.
For a static damage amount that will still take modifiers into account, make lower and higher equal the same value.
Of course, if you want a certain special attack to ALWAYS do the same amount of damage regardless of agility/defense,
you can always just make damage=whatever in the special attack script. The lower and higher bounds should be a pretty
low number otherwise these SpAttacks can get pretty destructive at higher agility levels.

See also: ItemDamage(), SkillDamage(), damage variable

Example:
  SpAttackDamage(4,4);

---------------------------------------------------------------------------
void Text(int portrait,string a,string b,string c,string d,int keeptalking)
---------------------------------------------------------------------------
Displays a hardcoded 4 line textbox, with the speech portrait number referencing the 32x32 image cut from SPEECH.PCX.
A portrait value of 0 will display no speech portrait at all (or whatever is in the 0 slot). TEXTBOX.PCX is the background
file used. The strings are displayed on screen with a maximum line length of 38 characters using the v2 default font. If
keeptalking=1, then the textbox won't shrink so the character can continue talking. Set this to 0 whenever a character
is finished talking (if you like). It is important to note that this textbox is drawn to layer5, but OpenGraphicsLAyers()
never need be called for Text functions. It is done automatically ONLY for layer5, and opening all layers does not interfere
with this function either.

Example:
  Text(2,"I have a cluster rifle trained",
         "on you. Homeworld won't mind",
         "if I splatter your brains all",
         "over, so stay your ground.",0);

----------------------
void UnPauseEntities()
----------------------
This resumes all entities at their previous speeds after they are paused. It is useful for textboxes and menus,
and is called internally by CreateMenu() and other PURGE kit functions.

See also: PauseEntities(), entpaused var

Example:
  UnPauseEntities();

-------------------------
void UpdateBattleScreen()
-------------------------
This function is part of what makes the PURGE battle system so flexible. This will refresh all stats, player
and monster states, and everything else that appears visually on the battle screen. Usually this function is
called automatically: when a monster dies, this function refreshes it's state to dead; when a player uses
a skill and loses spirit, this function refreshes his new spirit. This function can be called manually for
special battle effects that you create. This function does NOT, however, do anything with the battle char
entities other than initially spawn them.

See also: bce[] variables

Example:
  UpdateBattleScreen();

--------------------
void Wait(int delay)
--------------------
Stops control and the engine for delay amount of time, in hundredths of a second. Sometimes when things aren't
quite working out with functions being called right after another, sticking a Wait(1); in between will solve things.

Example:
  Wait(200);

-------------------------------
void Warp(int x,int y,int fade)
-------------------------------
Warps the player to the specified coordinates on the current map, with a fade if 1, no fade if 0.

See also: MapSwitch(), EntityWarp()

Example:
  Warp(10,26,1);

---------------------------------------------
void WillSuccess(int charslot,int difficulty)
---------------------------------------------
Tests the charslot's will (1-5) at a specified difficulty level (0-5). 0 is automatic, 1-easy--5-hard.
This is useful for non-battle skill scripts that wish to test a specific stat, or for other instances in the
game where you may want to do a D&D-type stat check. The scale for PURGE kit stats ranges from 1-100 usually,
so this is mainly useful in similar bounds.
	This function sets the success variable to 1 if the check is passed, otherwise to 0.

See also: AgilitySuccess(),StrengthSuccess()

Example:
  WillSuccess(1,5);
  If (success) { blah blah; )


============================================================================================================================

III. Built-in Variables

Many PURGE kit variables are status variables (ie. they hold the state of something). Basically this means that
by no means should you ever change them. Great care should be taken to make sure you don't change the value
of these [read-only] variables manually.


autohit
-------
1=autohit.
Only used in skill/item/spatack scripts. All of these effects do not automatically hit. They are tested
against char/mon defensive scores and must score high to hit. If you want a specific effect to hit
automatically, just call autohit=1 in the script. Note that this has no bearing on damage or otherwise.
	Since this variable is constantly changing in battle, it is not feasible to read it.
[write-only]

Example:
  autohit=1;;


battleon
--------
0=no battle,1=battle.
A variable that holds whether the game is currently in battle mode or not. This is usually used when determining
the result of items/skills that have both battle and camp applications, even if the effects are mostly the same.
Usually targeting may be handled differently, and battle effects have animations whereas camp effects do not. All
of this must be taken care of from within the script. Of course, this variable has many other applications.
[read-only]

Example:
  If (battleon)
  {
   HealChar(battletarget,10);
  }
  If (!battleon)
  {
   HealChar(itemtarget,10);
  }


battleuser,battletarget
-----------------------
Per every char/mon's attack, these variables will hold the values: battleuser will hold the number of
the attacker/caster/user, and battletarget will hold the individual target, whether friend or foe. Since
these values are constantly changing in battle, the only time these are useful are during item/skill/SpAttack
scripts as parameter calls.
	In any script where the only effect is damage dealt, these never need be called. In these scripts
the damage amount must be specified, and the battle engine will take care of the rest. In order to allow
a more flexible battle system where anybody can create effects, for anything else, EVEN HEALING, these
variables are usually used. Keep in mind that both these variables can only hold a single target at a time.
If you are affecting ALL mons or chars then battletarget will still work, technically once at a time.
Where you DO use battletarget is when the battle engine makes you select your target manually, as in
who you want to specifically heal or attack. The only time you can use this otherwise is for Mon SpAttacks,
since you don't pick their target - they do. Just make sure the target of the SpAttack is only one mon or char.
	Now keep this in mind: When dealing with mons-only they are numbered 1-5, but since this value can pertain
to mons AND chars, mons must be listed as 6-10. Therefore, in order to plug in the correct value for something
that can only be a mon, you must subtract 5 to make the 6-10 become 1-5. Lack of foresight on my part caused
this, which is probably one of the main reasons engines get rewritten. I'm lazy.
[parameter call]

Example:
  SkillSuccess(1);
  If (success)
  {
   HealMon(battletarget-5,2);
  }


bce[1]-bce[5]
-------------
each bce=entity index for chars[1-5].
The 5 entities the active party assumes in battle (Battle Char Entity). Chars 1-5 becomes bce 1-5
respectively. If a char is added with AddChr() in the middle of battle, UpdateBattleScreen() will
respawn another bce, but removing bce is currently unsupported. You can use DestroyEntity() to get rid
of it, but you wouldn't be able to respawn another bce in its place.
	Since UpdateBattleScreen() can't do anything to these entities after spawning them, entity control
must be handled manually, using these variables.
[read-only]

Example:
  Face(bce[battleuser],1);


char[1],char[2],char[3],char[4],char[5]
---------------------------------------
1-99=PARTY.TXT reference
PURGE supports up to 99 player-controlled characters total referenced in PARTY.TXT, but only 5 may be in the
active party at a time. There is a difference between a char(1-99) and a charslot[1-5]. Because of my lack of
foresight in this matter, I incorrectly named this variable as it technically refers to the active party
(charslots 1-5). Out of habit I kept it. When formally referring to a charslot, however, it means 1-5. This is
important because some functions call for a char parameter rather than a charslot; just make sure not to
be confused if char is ever used in place of charslot.
[read-only]

Example:
  If (char[5]) { Message("Party is full.",200); }


charname[1],charname[2],charname[3],charname[4],charname[5]
-----------------------------------------------------------
string=name of char in charslot, referenced in PARTY.TXT
When a charslot is full, it's corresponding charname will hold the referenced name. For example, if char[2]=17,
then the second person in the party is the 17th player character referenced in PARTY.TXT. The string name of
this char is stored in charname[2].
[read-only]

Example:
  PrintString(font,"My name is "charname[1]);


choice
------
0=no selection(canceled),1-20=possible Option() choices.
This global variable is determined by the player's choice when using Select(). It is used in Switch
statements to determine selection results.
[read-only]

Example:
  see the CreateMenu() example


currentmap
----------
string=filename of current map being visited.
MapSwitch() stores this variable for player use. Check that function for more info.
[read-only]

Example:
  s=0; //difference between strings
  s=StrCmp("fireisle.map",currentmap);
  If (!s) { Message("You are currently on Fire Isle.",200); }


curse[1-99],bcurse[1-5]
-----------------------
0=fine,1=afflicted.
The first is the permanent stat applying to chars(1-99, since a char can be cursed outside of battle), whereas
the second is the battle state and applies to the battlechar[1-5]. Ie. When in battle, use bcurse[], otherwise
use curse[].
	When a char is cursed, he can not heal his vigor until he is cured. RestoreAll() overrides this effect.

Example:
  If (battleon) { bcurse[battletarget]=1; }
  If (!battleon) { curse[itemtarget]=1; }

damage
------
defaults to 0, may be any amount of dmg.
Only used to determine the damage of item/skill/spattacks. Normal attacks are not included here. Also, there
are alternate functions for the above to cause damage that vary and take defense into account.
	If you want an effect to cause an exact amount of damage that does not take defense into consideration,
you can write to this variable in the script of the effect. Otherwise you never need to use this.
[write-only]

Example:
  damage=10;


darkness
--------
0=default,1=darness.
This variable determines whether the next map loaded will require light to be seen and entered (a la Phantasy Star 1).
If set to 1 right before a MapSwitch, then the new map will be dark and an inventory prompt will open up, so the
player can use an item that resets darkness to 0. This default to 0 and only needs to be called in these two cases.

Example:
  darkness=1;
  MapSwitch("darkcave.map",12,6,0);
         . . . and in the item script
  Sound("torch.wav",64);
  darkness=0;


entpaused
---------
0=unpaused,1=paused.
This variable just shows the state of the entities on the map, changed by PauseEntities() and UnPauseEntities().
It is mainly used internally.
[read-only]

Example:
  If (entpaused) { UnpauseEntities(); }

feeble[1-99],bfeeble[1-5]
-------------------------
0=fine,1=afflicted.
The first is the permanent stat applying to chars(1-99, since a char can be emfeebled outside of battle), whereas
the second is the battle state and applies to the battlechar[1-5]. Ie. When in battle, use bfeeble[], otherwise
use feeble[].
	When a char is emfeebled, he can not recover his spirit until he is cured. RestoreAll() overrides this effect.

Example:
  If (battleon) { bfeeble[battletarget]=1; }
  If (!battleon) { feeble[itemtarget]=1; }

flags[0]-flags[99]
------------------
RESERVED
flags[50](showpageon=0/1)
Graphics layers continually update onscreen by default. By setting this flag to 0, you can halt gfx updates until
you are finished drawing the entire scene, then turn updates back on. This will avoid ugly tearing effects and
prevent only parts of the displays being shown while otehrs are still drawing.                      

flags[100]-flags[800]
---------------------
v1 compatibility, defaults to 0.
These, just like in v1, can hold flags. Flags are general variables that can hold values that can later be
referenced. The only reason this is included is to easily transfer v1 map scripts to v2, or for those already
in the habit of using flags. Only 500 flags, however, are supported. These are in no way needed for PURGE to run.
[read/write]

Example:
  If (YouTalkedToTheHermit) { flags[234]=1; }
    /*later*/
  If (flags[234]) { Text(23,"So he told you my secret. . .","","","",1);


font
----
The PURGE kit by default uses the system.fnt. This font may be changed to any font you like, however, it
must be named system.fnt for InitializeNewGame() to recognize it. This font pointer is stored in font.
[parameter call]

Example:
  PrintString(font,c);;


GFX
---
0=graphics layers are closed,1=graphics layers are open.
Holds the state of the graphics layers as a whole. 
[read-only]

Example:
  If (!GFX) { OpenGraphicsLayers(); }


item[1]-item[30]
----------------
0=none,itemnumber=an item is in that itemslot.
Holds the item value (referenced in ITEM.TXT) for each of the 30 item slots in the player's inventory.
Usually used as a read-only but CAN be written to ONLY IF DONE CAREFULLY AND CORRECTLY. Any direct change
to these variables should be followed by a call to CompileInventory(). Still, PURGE handles this by itself
fine and for best results treat this as a read-only.
[read/write]

Example:
  If (!item[30]) { Message("You have space in your inventory.",200);


itemtarget
----------
1-5=charslot targets.
This is an important but complicated variable, partly because it's one of those variables that I wisely
designed to have more than one purpose. Behind the scenes it collects the targeting data from ITEMS.TXT,
but I should have never told you that, since you can never manually use or read it in this regard. Whenever
an item has a specific target, itemtarget will hold the value. So where this variable comes into play is
ONLY in the item's script (referenced in EFFECTS.VC).
	Do not get the above targets this variable uses confused with the targets found in ITEMS.TXT, which is
the only reason I mentioned that behind the scenes purpose at all. ITEMS.TXT uses general Camp/Battle targets.
What itemtarget holds is the SPECIFIC target the item will affect.
	Also, note that itemtarget is also used to hold the SPECIFIC targets of skills, still for use in
EFFECTS.VC. In fact, the words skill and item are interchangeable in this description (even the file name 
turns to SKILLS.TXT) except that the variable itemtarget is the same. There is no such variable as skilltarget.
	Also, THIS IS ONLY USED FOR NON-BATTLE SCRIPTS. See battletarget for the battle version.
[read-only]

Example:
  If (!battleon) { HealChar(itemtarget,10); }


lastmap
-------
string=filename of last map visited.
MapSwitch() stores this variable for player use. Check that function for more info.
This variable isn't very dependable, so never rely on it.
[read-only]

Example:
  MapSwitch(lastmap,10,10,0);


layer1, layer2, layer3, layer4, layer5
--------------------------------------
The 5 graphics layers that can be drawn to. Plug the preferred variable into the layer parameter
of any graphics function. layer5 should not normally be drawn to, as it is by default the Text() layer.
[parameter call]

Example:
  DisplayImage("drek.pcx,10,25,layer4);


LayerOn[1], LayerOn[2], LayerOn[3], LayerOn[4], LayerOn[5]
----------------------------------------------------------
1=layer is visible,0=layer is not being redrawn.
With the graphics layer open, all of these variable except for LayerOn[5] defaults to 1. You can change the value
to 0 to make that layer disappear, and back to 1 to redraw it. Closing the graphics layers turns all these back to
0. Since layer5 by default is the text-box layer, it is automatically opened by Text().

[read/write]

Example:
  LayerOn[2]=0;


lighting
--------
0=completely darkened-63=completely lit.
PalMo() creates this variable to keep track of the current lighting used by PaletteMorph(). NEVER use
PaletteMorph() however. Also, NEVER manually change this variable, as it will NOT actively change the
brightness of the screen. That's what Darken() and Lighten() are for.
[read-only]

Example:
  If (lighting<45) { Lighten(100,45); }


mon[1],mon[2],mon[3],mon[4],mon[5]
----------------------------------
monster=MONSTERS.TXT reference.
The monster equivalent of char[], this holds the slots for up to the 5 max monsters supported in battle. Mainly used
for targeting in battle, but has many possible uses. Never change this manually.
[read-only]

Example:
  If (mon[1]) { HealMon(1,10); }
  If (mon[2]) { HealMon(2,10); }
  If (mon[3]) { HealMon(3,10); }
  If (mon[4]) { HealMon(4,10); }
  If (mon[5]) { HealMon(5,10); }


music_playing
-------------
string=filename of current song playing.
This variable MUST be all lowercase when set by Music() to be recognized by the PURGE kit.
[read-only]

Example:
  s=0; //difference between strings
  s=StrCmp("arcolite.xm",music_playing);
  If (!s) { Message("Music: Archons of Light",200); }


poison[1-99],bpoison[1-5]
-------------------------
The current poison level of the char (not charslot). 0=not poisoned,1-5=poisonlevel,6=immune for battle,7=always immune.
This variable is usually handled by the PoisonChar() function and shouldn't be altered. The exception to this is when
you want something to change the poison level to 6 or 7, which CANNOT be done with PoisonChar(). Poison[] is the permanent
stat while bpoison is the battle stat. While in battle, ALWAYS use the bpoison[] and vice versa.  6 only works for the
current battle (and thus only applies to bpoison), so it MUST be altered during battle (ie. with a battle item),
but 7 is permanent and can be altered anywhere (and to its respective stat).
[read-write]

Example:
  bpoison[battletarget]=6;

norun
-----
0=run enabled(default),1=rundisabled.
After LoadBattle() is called, before either Monster() or RandomizeMons(), you can call norun=1. Then load
the mons and call StartBattle(). This disables the run feature in THIS battle. Players will still be able to
select it, but they can not run. Useful for boss battles.
	This feature can also be turned on and off in the middle of battle.
[read/write]

Example:
  norun=1;


run
---
1=will run at end of round.
Determines whether chars will run. This variable can be used in a skill/item script, as run=1, to
end battle at the end of that round. Other use of this variable is not supported. Partly because
at different points in battle this variable MEANS different things, like whether the chars WANT to
run, and later whether they succesfully ran, and even later to cancel a loop. It is for this reason
that it should never be read from at all, or modified except as mentioned above.
[write-only]

Example:
  run=1;


success
-------
0=failure,1=success.
Used in conjunction with SkillSuccess(), which tests the success of a NON-OFFENSIVE skill and returns
the result to this variable. Test this variable in an If statement that contains the result if the skill
succeeded.
	Likewise used in conjunction with Strength, Agility, and WillSuccess(), to test the success of a stat, also
best used in NON-OFFENSIVE situations.
[read-only]

Example:
  See SkillSuccess() example


++++++++++++++++++++++++++++statistic variables++++++++++++++++++++++++++
-
-strength[1-99],agility[1-99],will[1-99],vigor[1-99],attack[1-99],defense[1-99],spirit[1-99],avigor[1-99],aspirit[1-99] 
-----------------------------------------------------------------------------------------------------------------------
-each stat should=1-100 or so, but can be up to 999.
-Each char has 7 stats. avigor[] and aspirit[] are adjusted versions of their counterpart.
-Strength determines damage bonuses during combat.
-Agility determines battle order, and also gives a defense bonus against being hit when actively defending in battle.
-Will gives bonuses when attempting to hit with skills and trying to defend from SpAttacks. Also used for SkillSuccess().
-Vigor is the MAX life of a char. Avigor is the current, adjusted life, which constantly changes (but not above vigor[]).
-Attack determines chance of hitting with a normal attack, and damage is based on this.
-Defense helps to avoid getting hit, and also subtract general damage received, especially when actively defending.
-Spirit is the MAX value used to spend on skills. Aspirit is the current, adjusted spirit (can not exceed spirit[]).
-	The main attributes can be written-to to raise/lower them. The values for these for all 99max chars are
-stored at the beginning of a NEW game. Changing them once will change them for the remainder of the game, until
-they are changed again. The only variables which should not be written to (and only read) are avigor[] and aspirit[].
-There are functions to adjust these to ensure they do not rise above their max or fall below 0.
-	PURGE was designed to be balanced with stats (besides vigor[] and spirit[]) going above about 100. A few things
-like SkillSuccess() can be too easy if their corresponding stats get too high. Still, assign values as you wish.
-	These stats are mainly reliable in camp. In battle, you can read a char's original stat value if you wanted
-with these, but battles have a duplicate set of stats to not interfere with these, since these last the entire game.
-[read/write]
-
-Example:
-  strength[47]=strength[47]+5;
-
-
-level[1-99],xp[1-99],next[1-99]
--------------------------------
-stat maximums=verge2 bounds.
-Stores the level, current experience points, and total amount needed to gain another level, respectively.
-NEVER write to these variables- there are PURGE kit functions designed for this.
-[read-only]
-
-Example:
-  If (level[9]>4)
-  {
-   Text(12,"You have reached adequate strength.","","","",0);
-  }
-
-
-weapon[1-99],head[1-99],body[1-99],arms[1-99],legs[1-99],other[1-99]
---------------------------------------------------------------------
-0=none,equiplocation=an item.
-Holds the item number (referenced in ITEMS.TXT) of what is equipped in the given location.
-NEVER write to these variables- there are PURGE kit functions designed for this.
-[read-only]
-
-Example:
-  If (weapon[2]!=3)
-  {
-   Text(1,"That weapon will not suffice.","","","",0);
-  }
-
-
-gold,sgoldname,pgoldname
-------------------------
-max gold in possession=verge bounds.
-strings=singular and plural 'gold' names.
-Gold represents the gameworld's currency, whether it actually be 'gold' or not, and holds the number value.
-Sgoldname and Pgoldname are string variables that hold the singular and plural forms of the monetary unit.
-These only need to be set once at the beginning of a NEW game. PURGE really only uses this for battle awards,
-but general public functions should properly call these for support of multiple games.
-[read/write]
-
-Example:
-  gold=gold+75;
-  sgoldname=dollar;
-  pgoldname=dollars;
-
-
-bstr[1-5],bagi[1-5],bwil[1-5],bvig[1-5],batt[1-5],bdef[1-5],bspi[1-5]
----------------------------------------------------------------------
-each stat should=1-100 or so, but can be up to 999.
-Each char has the same basic 7 stats, but in battle these are used instead. This helps avoid accidents
-that can permanently change stats for the entire game. Also, since it is common for stats to change during
-battle, you can freely modify these at will, and they only last the length of battle. Raising battlestrength
-will not raise the char's real strength. The only stats that transfer at the end of battle are the vigor and
-spirit stats, which change the char's real adjusted forms.
-	Still, battlevigor and battlespirit should not be modifed manually to ensure staying within the proper bounds.
-[read/write]
-
-Example:
-  bagi[2]=bagi[2]-6;
-
-
-monstr[1-5],monagi[1-5],monvig[1-5],monatt[1-5],mondef[1-5],monmaxvig[1-5]
---------------------------------------------------------------------------
-each stat should=1-100 or so, but can be up to 999.
-Each monster has 5 stats. Monmaxvig[] is an adjusted version of it's counterpart.
-Strength determines a mon's damage in battle.
-Agility determines a mon's attack order, and helps with defense in some cases.
-Vigor is the mon's life, while Max Vigor holds the maximum amount, which should not be exceeded.
-Attack determines whether a monster hits or not.
-Defense helps avoid being hit, and subtract general damage from being taken.
-	These variables are only used during battle, obviously, so they can be adjusted as you wish. However,
-do not manually change monvig[], in order to ensure that it doesn't go below 0 or above the monmaxvig[].
-Game balance issues are dependent on stats, so try not to over inflate stats besides for vigor.
-[read/write]
-
-Example:
-  mondef[3]=mondef[3]+10;
-
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

============================================================================================================================