// The main renderfunction for the v1 RPG effects library.
// Every time Render()  is called or an R is reached on the map's
// Renderstring, this function is called... as long as HookRetrace("V1RPG_RenderFunc")
// was set beforehand (by default in The Sully Chronicles, this line is placed in
// the system.vc autoexec function() )
//
// This function checks for and does the following events:
// * Renders the Weather if any is on (see SetWeather()  in v1_weather.vc)
// * if there's a color filter on, applies it. ( see the VCScreenFilter()  functions below)
// * TBlits the vclayer over the screen. (see VCPutIMG() , ClearVCLayer() , VCText()  below)
// * Applies a tint if it's on. (see VCLayerTintScreen()  below)
// * shakes the screen if the quake has been set (see VCQuake()  below)
//
//
void V1RPG_RenderFunc()



// Sets the colorfilter option for V1RPG_RenderFunc.
//
//
void VCScreenFilter( int color_filter )



// returns true if there's a color filter on of any type.
//
int VCScreenFilterOn()




//Turns the VClayer's color filter off.
void VCScreenFilterOff()



// applies a lucency to the colorfilter.
// Remember: 100% lucent is nothing,
// 0% lucent is solid, 25% lucent is lightly see-though,
// 75% lucent is very see-through, etc etc.
void VCScreenFilterLucent( int perc )



// This sets a custom color filter.
// color_1 defines the darkest color on a screen,
// color_2 defines the brightest color on a screen.
//
// Make sure to supply both arguments using RGB()
//
// Example:
//	VCCustomFilter( RGB(0,0,0) , RGB(255,255,0)  ) ; //this will make the screen
//		//all shades of Yellow... as long as V1RPG_RenderFunc is in the HookRetrace.
void VCCustomFilter( int color_1, int color_2 )



// If something else accesses SetCustomColorFilter()  directly without accessing
// VCCustomFilter() , that something else can just call VCCustomFilterRestore()  after
// it's done and the V1RPG library will continue to function as normal with it's custom
// color filter.
//
// In the Sully Chronicles, the menu function uses SetCustomColorFilter()  to draw it's
// colored menu backgrounds, and so it calls this function after it's done to make sure
// any custom screen filtering resumes as normal (like in Sara's flashback) .
void VCCustomFilterRestore()


// returns 1 if VCCustomFilter()  is active, 0 if it is not.
int VCCustomFilterOn()



// returns the integer color-value of the current VCCustomFilter's "dark" color.
int getVCCustomFilterColor1()



// returns the integer color-value of the current VCCustomFilter's "light" color.
int getVCCustomFilterColor2()



// Tints the vc layer the given color a given percent.
// Useful for fading too and from a specific color.
void VCLayerTintScreen(int color, int percent)



// Turns off the vc layer tinting, if it was on.
void VCLayerTintOff()



// Clears the VC Layer of any and all images.
//
void ClearVCLayer()



// Takes an image's path and filename, and the position to put it onto the
// VC Layer.  It then loads it, blits it only the vc layer, and deletes the
// image.
//
// No fuss, no muss.  Very useful for drawing things to the screen to stick
// around for a while in a simple manner.
//
// If you ever want to wipe the screen after calling this, use ClearVCLayer().
void VCPutIMG( string img_name, int x_pos, int y_pos )



// Fills the vclayer with an RGB()
void FillVCLayer( int matte_color )



// Prints string s at (x,y) on the VCLayer in the v1-rpg lib's SmallFont.
//
// the v1-rpg lib's SmallFont.can be changed with v1_setSmallfont() 
void VCText( int x, int y, string s )



// Prints string s centered on the vclayer at height y.
// the font is the v1rpg smallfont.
//
void VCCenterText( int y, string s )



// Turns on vc-layer quaking with a horizontal shake of quake_x and a vertical
// shake of quake_y.
//
// The screen will shake but loosely follow the player until VCQuakeOff() is
// called.
//
// This is similar to EarthQuake() in v1_weather.vc, but allows the player to
// walk around and do stuff wile the screen is shaking.
void VCQuake( int quake_x, int quake_y )



// Turns off the vclayer quake effect.
void VCQuakeOff()



// This function enables the V1RPG Dual VC-layer mode!  It's totally wacky!
// It basically allows for two Rs in curmap.rstring, with V1RPG_RenderFunc()  being
// called when the first R triggers, and a straight-up TBlit of the second vc layer
// image on the second R.
//
// This mode is used on lab.map to blit things in the foreground, since lab.map puts
// the regular R-layer behind the entities and the tiles to make the neat translucent
// fog effect work.
//
void V1_StartDualMode( string newrstring )



// If Dual-rendering mode is on when this is called, it turns the mode off and
// restores the original curmap.rstring.
//
// Otherwise does nothing at all.
void V1_StopDualMode()



// This is the function that gets set to the HookRetrace by V1_StartDualMode()
// Do not call this yourself unless you Know What You're Doing.
//
// ...generally, you shouldn't use the Dual rendering mode unless you Know What
// You're Doing, too.
void V1RPG_RenderFunc_DUALMODE()



// This function takes care of all the loading and initialization for the v1_RPG
// library.
//
// You may recall seeing it in The Sully Chronicles's system.vc at the top of the
// autoexec() function with all the other library load functions!
void V1RPG_LoadResources()



// One of the cornerstones of the v1RPG effect library, this function takes
// care of all of the awesome things this library can do on the mapswitch.
//
// It stores the x and y that the party goes to on the new map, and the effect
// to use when the new map loads.  The it does the first half of the effect,
// sets the music volume to the global value (set by the v1_music.vc functions)
// just incase the volume was altered manually using SetVolume() , and turns off
// any weather that was going on.
//
// At that point, it calls Map()  with the specified mapname.  Map() , if you've
// read the v3 manual, ceases all activity on the present map, loads the new map,
// and calls the new map's personal autoexec function (you set that in maped.
// All of the Sully maps have theirs set to "start() ", but you can name yours
// whatever.)
//
// To have a V1_MapSwitch()  complete successfully on the new map, make sure
// v1_InitMap() ; is called.  In The Sully Chronicles, v1_InitMap()  is called
// inside InitMap() , which is defined in system.vc
//
void V1_MapSwitch(string mapn, int x, int y, int effect)



// The v1_rpg library's map upkeep function.
//
// Put this function in your map's autoexec function if you want
// your v1_mapswitch transitions to properly work.
//
// To have a V1_MapSwitch()  complete successfully on the new map, make sure
// v1_InitMap() ; is called.

// In The Sully Chronicles, v1_InitMap()  is called inside InitMap() , which is
// defined in system.vc
void V1_InitMap()



// Warps the player to tile coordinates (x,y) , using a specified fade effect.
// The fade effects have the following valid defines:
//   TNONE, TWHITE, TCROSS, TBOX, TWIPE, TCIRCLE
//
// NOTE: References simpletype library's GetPlayer()  to get the mapindex of
//       the player entity.  If you decide to use a different partyhandling
//       system with this library, make sure to change those to the proper
//       player entity index.
void Warp(int x, int y, int effect)



// Box-drawing tool for this library.
// Draws a box at screen coordinates (x,y)  with width and height of (w,h)
//
// NOTE: This is presently a wrapper around the v1_Menu's MenuDrawBackground()  function.
//       if you wish to use this library without v1_Menu, alter the contents of this
//       function as you see fit.
//
void V1_Box(int x, int y, int w, int h)



// Takes a one-line message and prints it in a centered MenuBox with the specified font.
//
// Does not do stringlength-checking, so you can make a long string draw off of the screen.
// Does not factor in newlines or tabs, either.
void CenterMessageBox( int font, string msg )



// Takes a one-line message and prints it in a centered MenuBox
// with the v1rpg Small Font.  The message stays up for duration, or until
// b1 is pressed.
//
// the menu is disabled during this function.
void Banner( string msg, int duration )



// Turns on the ability to save.
// 
void SaveEnable()



// Turns off the ability to save.
// 
void SaveDisable()



// Places tile t onto map layer 0 at (x,y) .
//
// obstructs the tile if obs is 1, unobstructs the tile if obs is 0
// leaves the obstruction alone if obs is any other value.
void AlterBTile(int x, int y, int t, int obs)



// Places tile t onto map layer 1 at (x,y) .
//
// obstructs the tile if obs is 1, unobstructs the tile if obs is 0
// leaves the obstruction alone if obs is any other value.
void AlterFTile(int x, int y, int t, int obs)



// The master Chest-opening script.
// returns 1 if the chest referenced at flags[flag] was not open, and sets the tile at
// (x,y)  to t, while playing an opening-the-chest sound.
//
// else returns 0.
//
// See any treasure script in Sully for use example.
//
int OpenTreasure( int flag, int x, int y, int open_tile )