MHSCRIPT
--------
A scripting system for MHQuake.


1. Introduction
---------------
This is version 2.0 of MHScript - the first version used XML, but was never released (or
even coded, although the specifications were partially written.)  This version uses a more
generally accepted script format.

A lot of people have been demanding scripting in MHQuake for quite some time now, and in
general it has been in relation to texture manipulation.  This has always seemed to me to
be underutilising the potentialities of scripting somewhat.  This initial incarnation of
MHScript therefore totally ignores texture scripting and focuses rather on manipulation of
some of the special effects that MHQuake allows you to have in your maps and on your Alias
Models.

This does quite a lot of useful stuff from my perspective as a Quake developer - most
importantly, it lets me add new features to these entities without actually adding in any
code to either read in new Worldspawn entries or assign effects to models based on the
model name.  Therefore, I need no longer worry about whether all the Hipnotic powerups
(for example) have been assigned the correct effects.

From the player's perspective, it lets you decide (for example) that you would like to 
always play E1M1 with green fog, E1M2 with no fog and E1M3 with brown fog, then just roll
off a script that contains the relevant settings, and you will automatically get them as
each map loads.  You also now have total freedom to decide which MHQuake effects you want
to have on which alias models if you don't like the ones I have assigned.

Future MHScript versions will of course include texture scripting, as well as a fully
scriptable HUD layout.  These are now easier to implement thanks to a common set of script
parsing functions I have developed.  I will also be releasing a script generating utility
which will enable you to easily make your own MHScripts without any fear of mistakes.

Please note that this is just an inital test release of MHScript, with the primary objective
of getting the thing working, getting it out there, and getting some feedback.  There will
be some obvious omissions, and a new version of MHQuake with a more expanded MHScript will
follow.

Until then, enjoy.


2. MHScript basics
------------------
Each MHScript file contains 3 basic components: header, items and declarations.  These will
be dealt with in turn later on.  A fourth (optional) component is comments.

MHScript files are (aside from the header) almost totally unfussy in terms of whitespace,
tabs, newlines, etc.

The MHScript files use a .mhs extension and are placed in a 'scripts' directory under your
game directory.  You can create and edit them in any plain text editor (such as notepad.)

Warning: the contents of MHScripts are case sensitive - normally, you should use lower
case.  This will be fixed in a later release.

2.1. MHScript Header
--------------------
This is a simple header that performs two key tasks: (1) identify the file as a valid
MHScript file, and (2) tell MHQuake what type of script it is.  MHQuake currently only
supports alias and map scripts.

The header for a map script will look like this:
{SCRIPT MAP}

The header for an alias script will look like this:
{SCRIPT MDL}

Note the use of the space between the word 'SCRIPT' and the 3 character code identifying
the script type: this is absolutely mandatory.

2.2. Items
----------
These are simply each entry in the script file: a script file for alias models may contain
settings for as many alias models as you want, and each of these alias models is seperated
from each other by enclosing them in braces.

To start a new item, use an opening brace ({) - this must be on a new line, but it can be
followed by a comment.

To finish the current item, use a closing brace (}) - this must be on a new line, but it
can be followed by a comment.

2.3. Declarations
-----------------
These are simply lists of property names and values for each item, and are described more
fully in the relevant sections for each script type.  Each name and value pair are typically
surrounded by double quotes (") with a space in between, and are on a line of their own
(although they do not have to be.)

Note that some item properties may use more than one value, either always or in certain
special circumstances.

Although the various declarations are listed below in a fixed order (and also will be
generated in a fixed order by the MHScript utility) you can have them in any order you
want.  Any declaration not given for an item will be given a default value.  Any item not
listed will have it's current properties unchanged - if you want to set an item's properties
to the default, you MUST at least declare it's name.

2.4. Comments
-------------
Comments can literally go anywhere in MHScript files.  There are no special identification
characters, just find somewhere and type them in.  The only restriction is that due to the
parsing routines, you cannot use the opening brace ({), closing brace (}) or double quote
(") characters in them.

Of course, you may find it easier to read them if you put them on lines of their own.
Compare the following 2:

"skyrotate" set the skybox rotation to x:5 y:0 z:15 "5" "0" "15"

set the skybox rotation to x:5 y:0 z:15
"skyrotate" "5" "0" "15"

Which is easier to understand?

(BTW: I don't mean to patronising here - just demonstrating how totally freeform MHScript
can really be.)


3. MHScript Execution
---------------------
MHScript has 2 different execution modes: scripts that execute automatically when a map
loads (this is true even for model scripts) and those that you can execute yourself from
the console (or from autoexec.cfg, or a stuffcmd command in QuakeC...)

3.1. Automatic Scripts
----------------------
If MHQuake finds a script called map.mhs in the scripts directory, it will attempt to
execute it automatically after loading the map.  If the map which has just been loaded
has no settings present in the script, MHQuake will set defaults for all the relevant
item properties.  The mdl.mhs script is similarly executed for alias model files upon map
load.  MHScript also allows you to specify an alternate model script if you wish, from
within the map script.

3.2. Console Scripts
--------------------
You can execute any MHScript any time you want by using the 'script <scriptname>' command.
This is very useful for developing.  Naturally, you can do the same with this command as
you can with any other command, ie. call it from your autoexec or from QC.


Appendix A - Map Script Declarations
------------------------------------
This list is by no means complete - future releases of MHScript will add to it as required.

"map"
-----
The name of the map, ie. what you would type at the console to load the map.  Eg. E1M1.
This is required.

"wateralpha"
------------
If you know that the map has been properly vised for translucent water, then you can use
this to automatically set a value of r_wateralpha for the map.  The default is "1.0".

Unlike other MHScript stuff, if r_wateralpha is not explicitly specified, it will be
reset to 1 (even if the map has no entry in the script) in order to prevent HOM effects
with maps that have not been properly vised.  MH regrets this necessary evil, and will
remove it as soon as automatic water translucency reaches a stage of development which
is comparable to a properly vised map.

"fog"
-----
Determines if the map shows global fog.  The values used are "0" for no fog or "1" for
global fog.  If the map does have global fog, then the "1" is followed by 5 more values
representing fog start, fog end, fog red, fog green and fog blue.

A map that's explicitly set to have no fog would look like this:
"fog" "0"

A map with a dirty brown fog might look like this:
"fog" "1" "5" "4096" "0.3" "0.2" "0.1"

The default is no fog.

"skyname"
---------
If the map uses a skybox, you should include this key, and give the name of the skybox.
There is no need to give paths (MHQuake will work this out for you) or extensions.  For
example, to use a skybox in the id1/gfx/env directory with components called "sky_up",
"sky_dn", "sky_lf", "sky_rt", "sky_ft" and "sky_bk" you would declare:

"skyname" "sky_"

And MHQuake will do the rest.

If you don't want to use a skybox, omit this key.

"skyrotate"
-----------
Uses 3 values for skybox rotations speed, x, y, and z.  You must specify all 3, even if
one of them is zero.

If you're mot using a skybox, you don't need to include this key among your declarations.

"mdlscript", "hudscript" and "texscript"
----------------------------------------
These allow you to specify map specific scripts for alias models, HUD configuration and
texture effects.  Such scripts are in addition to, rather than instead of, the default ones.

To specify a specific script for e1m1, you would declare the following

{
	"map" "e1m1"
	"mdlscript" "mymdlscript"
	other e1m1 declarations go here
}

Note that only alias model scripting is currently supported (in addition to map scripting,
of course.)


Appendix B - Alias Model Script Declarations
--------------------------------------------
This list is by no means complete - future releases of MHScript will add to it as required.

"model"
-------
The full name (including extension) and path to the model, eg. "progs/quaddama.mdl" - this
is the only mandatory declaration.  If you do not provide the full model name (as above),
MHScript will look in the default location.

"trans"
-------
The level of translucency that the model will have, eg. "0.5" - this assumes that you have
translucent alias models switched on - if not, you will get no translucency.

The default value is "1".

"glow"
------
Whether or not the model has a glow effect - this has a value of "0" for no glow effect or
a value of "1" or above if it does glow (older - and possibly future - versions of MHQuake
used an index into the Quake Palette rather than seperate RGB values for glow colour, so
it's best to use that instead of just "1" - although it doesn't matter for the current
version.)

If the model is glowing, there are 3 more values giving the RGB of the glow.  This may
sound a little complicated, but is really quite simple.

A model that does not glow can simply be listed as:
"glow" "0"

A model that glows (for example) blue can be listed as:
"glow" "251" "0.0" "0.0" "0.4"

It's best to use lowish RGB values that add to 0.5 or so, otherwise the glow will be a
little too strong.

Of course, if glowing models is set off, no amount of scripting will give you glow effects.

The default is "0" with no RGB entries.

There is currently no way to set the radius of the glow effect in MHScript (how did I miss
that one?)

"shadow"
--------
Specifies if the model casts a shadow or not when r_shadows is switched on.  Use "0" for no
shadow or "1" for a shadow.  The default is no shadow.

"shading"
---------
This affects how the model is lit - use "0" for standard Quake style lighting, or a number
between "1" and "255" to specify a fixed amount of lighting (can result in faster frame
rates.)  Note that some models, such as Lightning Bolts, Torches, etc, are more suited to
fixed lighting.  The default is normal lighting.

"special"
---------
This only applies if the model glows, otherwise it can be left out or set to anything you
like (even "goaway") - the default is "normal".  There are 4 different ways in which glow
effects can be further modified:

  "missile" - glow is behind the model and flickers
  "torch"   - glow is shifted slightly up and flickers
  "powerup" - glow pulses slowly
  "bolt"    - glow just flickers

If it's left out or set to anything else, you just get a steady glow.

This list may be expanded in future.


Appendix C - The MOD Command
----------------------------
Shadow suggested this idea, and it was too good to waste, so here it is.  The mod command
is used to change individual alias model properties on the fly without having to write a
script for them.

The basic command syntax is:

	mod <model_name> <property> <value(s)>

The same basic rules for alias model scripts apply, except that you should not use quotes.
