=============================================================
RScript2 Documentation:
=============================================================

Contents:
----------

1)	Introduction
2)	Example Script
3)	Boolean Flags
	* Alpha Masking
	* No backface culling
	* No Lightmap
	* Sphere Mapping
4)	Functions
	* Alpha
	* Blend Function
	* Frame based Animation
	* Scrolling
	* Texture Mapping
5)	Comments
6)	Notes


1 - Introduction
-----------------

RScript2 is the name of the scripting engine that has been designed from scratch and built into the Quake1 engine modification, MrGLQuake. Unlike the original RScript which was present in earlier releases of MrGLQuake, RScript2 has actually been thought out and properly designed. :)

Scripts written for use with RScript2 are incompatible with scripts written for the original RScript. RScript2 supports more advanced scripted effects such as sinewave alpha shifting, and removed limits that the original RScript had.


2 - Example Script
-------------------

A basic script looks like the following:

texture_name
{
	{
		map stage1
		nolightmap
	}
	{
		map stage2
		spheremap
	}
}

A script MUST begin with a texture name (for the texture it works on), followed by an open brace to signal that the script begins here, and ends with a closing brace to signal that the script ends here. Inside the script lie the rendering stages. They also MUST begin with an open brace and end with a closing brace, with the stage code lieing between them.


3 - Boolean Flags
------------------

Boolean flags are simply effects that are toggled, they dont have any parameters at all. By default they are all disabled. To enable them, simply put their name into the stage to have them enabled on.

* Alpha Masking
----------------
Script syntax: alphamask

Alpha masking is a pretty simple effect. If the texture map of a stage has an alpha channel on it, and alpha masking is enabled on it, any pixels with an alpha value less than one arent rendered, leaving sections of the image "see-through". This effect is often used to create grates and chain-link fence type images.

* No backface culling
----------------------
Script syntax: nocull

Use this to disable backface culling on a particular script stage. This allows the stage to be seen from "behind" the polygon that it's being rendered on. Good for using on grates and the like.

* No Lightmap
--------------
Script syntax: nolightmap

This boolean operator disables rendering of the lightmap for the stage that it's specified in. Careful use of this can help the framerate without affecting the visuals of a script, eg only updating and rendering the lightmap on the final stage of a script will be friendlier to the framerate than updating and rendering it on every stage.

* Sphere Mapping
-----------------
Script syntax: spheremap

This operator enables the sphere mapping effect on a stage. This is often used to give a surface a reflective "shiney" effect, such as that found on glass or the surface of water.

4 - Functions
--------------

Functions are similar to boolean flags except for the fact that they take parameters. By default they are disabled. To enable them, write in the script their name followed by their parameters.

* Alpha
--------
Script syntax: alpha <style> <speed> <min> <max>

This function controls the alpha value of a stage for blending purposes. It is used to set the amount that the stage is blended into the stage before it, or anything rendered behind it. It must be used in combination with the function "blendfunc" (see Blend Function). If <style> is "static", <min> is taken as the alpha value.

Valid settings for the parameters are:
<style>		static		- The alpha value never changes
		sine		- The alpha value follows a sine wave
		cosine		- The alpha value follows a cosine wave

<speed>		<number>	- A floating point number which controls the speed at which the alpha changes

<min>		<number>	- A floating point number which specifies the minimum value that the alpha can reach

<max>		<number>	- A floating point number which specifies the maximum value that the alpha can reach.

* Blend Function
-----------------
Script syntax: blendfunc <source> <destination>

This function tells the renderer how to blend the stage in with the previous stages. If the script is meant to leave objects behind it visible, it must only be used on a brush-model entity.

Valid settings for the parameters are:
<source>:	GL_ZERO
		GL_ONE
		GL_DST_COLOR
		GL_ONE_MINUS_DST_COLOR
		GL_SRC_ALPHA
		GL_ONE_MINUS_SRC_ALPHA
		GL_DST_ALPHA
		GL_ONE_MINUS_DST_ALPHA
		GL_SRC_ALPHA_SATURATE

<destination>:	ZERO
		GL_ONE
		GL_SRC_COLOR
		GL_ONE_MINUS_SRC_COLOR
		GL_SRC_ALPHA
		GL_ONE_MINUS_SRC_ALPHA
		GL_DST_ALPHA
		GL_ONE_MINUS_DST_ALPHA

* Frame based Animation
------------------------
Script syntax: anim <delay> <image1> <image2> <image3> ... end

This function controls frame based animations for the script. It works similar to a flipbook, where different images are shown with a small delay between them to give the illusion of movement.

Valid settings for the parameters are:
<delay>:		The delay between images (in milliseconds)

<image#>:		The name of the texture image to be used for the frame

* Scrolling
------------
Script syntax: scroll <xtype> <xspeed> <ytype> <yspeed>

This function controls how the stages texturemap moves. Movement can be linear, following a sine wave, or following a cosine wave.

Valid settings for the parameters are:
<xtype> & <ytype>	static		- Linear movement
			sine		- Follow a sine wave
			cosine		- Follow a cosine wave

<xspeed> & <yspeed>	<unmber>	- The speed at which the texture moves
	
* Texture Mapping
------------------
Script syntax: map <texturename>

This function specifies the filename of the texture map to apply on the stage.


5 - Comments
-------------

Scripts are able to contain lines of normal text that has nothing to do with the scripts code. These are referred to as comments, and are generally used to keep note of what does what.

To enter into comments, use the "/*" string, and to break out of comments use "*/" (excluding quotations). eg:

ground01
{
	{
		map ground01
		nolightmap	/* disable lightmap on this stage */
	}
	{
		map dirtlayer
		blendfunc gl_src_alpha gl_one_minus_src_alpha
		alpha static 1 0.2 0.2	/* blend this stage */
	}
}

Comments can span over multiple lines. It is recommended to break out of comments before the end of the file, whilst not 100% necessary, an error is printed to the console if the end of the file is reached whilst in a comments block.


6 - Notes
----------

When the engine is first loaded, every RScript file within the "scripts" folder is parsed and compiled into the renderer for use. Under the "scripts" directory is another directory named "maps". When loading a BSP (level) file, RScript checks for the existance of a .rscript file with the same name as the BSP file under the "scripts/maps" directory.

eg: map01.bsp will load scripts/maps/map01.rscript


When the script parser comes accross a script that has previously been defined, the old script is scrapped from memory, and the new one is loaded in to replace it.


A new console command has been added, "rscripts", which when entered will give a print-out to the console of all the individual scripts that have been parsed and loaded into memory.