--------------------------------------------------------

RScript For BeefQuake

-------	Documentation ----------------------------------
--------------------------------------------------------


------- Contents ---------------------------------------
--------------------------------------------------------

1)	Introduction
2)	Example Script
3)	Boolean Flags
	- Alpha Masking
	- Environment Mapping
	- Safe
4)	Functions
	- Alpha Shift
	- Blend Function
	- Frame Based Animation
	- Rotate
	- Scroll
	- Subdivide
	- Texture Mapping
	- Vertex Warping
5)	Notes


-------	(1) Introduction -------------------------------
--------------------------------------------------------

RScript is the name of the simplistic script language that has been designed and implemented into the modified Quake II engine, BeefQuake, to allow custom visual effects to be rendered on surfaces within the game.


-------	(2) Example Script -----------------------------
--------------------------------------------------------

Each script file can consist of many actual scripts written within its contents, and each script can consist of multiple stages of rendering. A simple script looks like this:

texture_name
{
	{
		map textures/stage1.tga
		scroll static 0.2 static 0
	}
	{
		map textures/stage2.tga
		alphamask
	}
}

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 255 arent rendered, leaving sections of the image transparent (or "see-through"). This effect is often used to create grates and chain-link fence type images.


-------	Environment Mapping ----------------------------
--------------------------------------------------------

Script Syntax:	envmap

This flag 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.


-------	Safe -------------------------------------------
--------------------------------------------------------

Script Syntax:	safe

This flag tells the engine not to flush the script from memory on a map change. By default, all scripts are flushed from memory as to preserve RAM, but some scripts are wanted to remain in memory at all times (such as scripts for the console).

NOTE:		This flag is specified ONLY in the base area of the script, not in any of the stages. Eg:
		This flag should be used only when absolutely required.

script1
{
	safe
	{
		map stage1
	}
}


-------	(4) Functions ----------------------------------
--------------------------------------------------------

Functions are similar to boolean flags except for the fact that they take parameters. By default they are disabled, and are enabled when referenced within a scripts stage.


-------	Alpha Shift ------------------------------------
--------------------------------------------------------

Script Syntax:	alphashift <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).


Valid settings for the parameters are:
<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. Beware when using it on the first stage of world geometry.

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. The 'end' keyword MUST appear after all frame images are specified.

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


-------	Rotate -----------------------------------------
--------------------------------------------------------

Script Syntax:	rotate <rot_speed>

This function controls how the stages texturemap is rotated.

Valid setting for the parameter is:
<rot_speed>	<number>	- Rotation speed


-------	Scroll -----------------------------------------
--------------------------------------------------------

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>	<number>	- The speed at which the texture moves


-------	Subdivide --------------------------------------
--------------------------------------------------------

Script Syntax:	subdivide <size>

This function tells the engine to subdivide the surface into blocks with sides of a specific length. Proper use of this function can help create better looking turbulating (think water warp) effects.

Valid settings for the parameters are:
<size>			<number>	- The size of each side of the subdivided surfaces. Preferably a power-of-two number.

NOTE:		This flag is specified ONLY in the base area of the script, not in any of the stages. Eg:
		Only geometry surfaces are subdivided.

script1
{
	subdivide 64
	{
		map stage1
	}
}


-------	Texture Mapping --------------------------------
--------------------------------------------------------

Script Syntax:	map <texturename>

This function specifies the filename of the texture map to apply on the stage. If using frame based animation, ignore this function.

Optionally instead of specifying a texture image, a .cin (Quake II cinematic) file may be used here. Only 8 of these are allowed to be used at once, any more will be ignored by the engine. These are decompressed in realtime and uploaded to OpenGL, allowing streaming video on surfaces within the game.

New to BQr5 >> You can now specify "$lightmap" as the texturename, and RScript will put only the surfaces lightmap onto the polygon. This works only for BSP surfaces, not 2D overlays or alias models.


-------	Vertex Warping ---------------------------------
--------------------------------------------------------

Script Syntax:	vertexwarp <speed> <distance> <smoothness>

Warps the vertexes of the surface in a wave pattern along it's plane

Valid settings for the parameters are:
<speed>			<number>	- A floating point number specifying the speed of the warp

<distance>		<number>	- A floating point number specifying the maximum distance of the warp

<smoothness>		<number>	- A floating point number between 0.001 and 1.0 specifying the smoothness of the warp, 1.0 is a rough warp, 0.001 is a very smooth warp

NOTE:		This flag is specified ONLY in the base area of the script, not in any of the stages. Eg:
		Only geometry surfaces are warped.

script1
{
	vertexwarp 3 8 0.001
	{
		map stage1
	}
}


-------	Notes ------------------------------------------
--------------------------------------------------------

When the engine is loaded, every script within the "scripts" folder is loaded along with it. When a map is loaded, all scripts within memory are flushed, and then reloaded, and a map-specific script is loaded from the "scripts/maps" folder, where the script loaded has the same filename as the map, but with a ".txt" extension.

eg: Loading map "base1.bsp" will load the map specific script file, "scripts/maps/base1.txt".

This is a work-in-progress version of the script parser and renderer. That means that there may very well be unexpected bugs which cause visual errors. Syntax errors within scripts can cause the engine to crash unexpectedly during script parsing, so make sure you follow the syntax perfectly.