Difference between revisions of "Template:Doc functions.txt"

From Spherical
Jump to: navigation, search
(created)
(No difference)

Revision as of 02:39, 2 June 2013

Sphere function documentation


Go here for language specification: http://www.mozilla.org/js/language/


Descriptions by Rizen Many thanks! Edited and updated by Darklich and AegisKnight :)


      • general functions ***

GetVersion()

 - Returns the current version of Sphere as a floating point number
   (e.g. 1.0 or 1.1)
      • script functions ***

EvaluateScript(script)

 - Reads the script in and uses it as if it were a part of the current script.
   ex: EvaluateScript("myscript.js");

EvaluateSystemScript(script)

 - Reads in one of the preset system scripts for use in the current script
   ex: EvaluateSystemScript("menu.js");

RequireScript(script)

 - Reads the script in and uses it as if it were a part of the current script.
   But only if the script has not already been evaluated.
   ex: RequireScript("myscript.js");

RequireSystemScript(script)

 - Reads in one of the preset system scripts for use in the current script.
   But only if the script has not already been evaluated.
   ex: RequireSystemScript("menu.js");

GarbageCollect()

 - invokes the JavaScript garbage collector


      • miscellaneous ***

CreateStringFromCode(code)

 - creates a single-character string based on the code passed in, i.e. 65 is "A"


      • engine functions ***

GetVersionString()

 - Returns the current Sphere version string

GetGameList()

 - Returns array of game objects
   - game.name          Name of game
   - game.directory     Directory (project name) where game is stored
   - game.author        Who wrote it?
   - game.description   Bite-sized summary of game.

ExecuteGame(directory)

 - executes the game in sphere/games/<directory>.  This function
   actually exits the first game and loads the one in 'directory'.
   When the second game returns, the original is loaded again.  (Note
   that this is unlike Sphere 0.97, which returned directly from
   ExecuteGame when the other game finished.)

RestartGame()

 - restarts the current game

Exit()

 - Exits the Sphere engine unconditionally

Abort(message)

 - Exits the Sphere engine unconditionally, displays the 'message' to the 
   user
   If you end the message with a newline it wont display the file/line
   where the Abort occured.
   e.g. Abort("Mistake here")
    vs. Abort("Game over!\n");


      • debugging (the log object) ***

OpenLog(filename)

 - opens a log file for use under the filename. If Sphere is unable to open 
   the file for logging, the engine will give an error message and exit. 
   If Sphere is successful in opening the file, it will return a log object
   for use.
   ex: var myLog = OpenLog("game.log");

log_object.write(text)

 - writes a string of text under the current block.
   ex: myLog.write("Starting system...");

log_object.beginBlock(name)

 - creates a "block" which is indent inside the log with the name as the 
   title of the block. Any subsequent write commands will go under the newly 
   created block.
   ex: myLog.beginBlock("Video Information");

log_object.endBlock()

 - closes the current log block.


      • system interfaces ***
 *** video ***
 FlipScreen()
   - displays the contents from the video buffer onto the screen. Then the 
     video buffer is cleared. You *need* to call this to make anything 
     you've drawn in code to appear on the screen.
 
 SetClippingRectangle(x, y, w, h)
   - Sets a clipping rectangle of width w and height h at (x, y) into the 
     video buffer. Anything drawn outside the rectangle is not drawn into 
     the video buffer.
     
  GetClippingRectangle()
    - Returns a rectangle object representing the clipping rectangle.
      i.e.
      var clip = GetClippingRectangle();
          clip.x
          clip.y
          clip.width
          clip.height
 
 ApplyColorMask(color)
   - fills the whole screen with the color specified. Note that the color
     passed must have an alpha that is less than 255. Otherwise, it'll 
     just make the screen solidly that color.
     ApplyColorMask tints the screen's current state
     (meaning you'll have to call it every frame
      if you want the effect to be permanent)
 
 SetFrameRate(fps)
   - allows you to set the maximum frames rendered per second that 
     the engine is allowed to draw at most.  Set to 0 in order to
     unthrottle the graphics renderer.  Keep in mind that this
     is not for the map engine, which uses the fps specified in the
     MapEngine() call.  This function only controls standard drawing
     functions and FlipScreen() outside of the map engine.  In short,
     don't use this function if you plan to be doing rendering in your
     own scripts in the map engine.
 
 GetFrameRate()
   - Returns the current fps (set by SetFrameRate... note: this is
     not the same as the map engine frame rate)
 
 GetScreenWidth()
   - returns the width of the engine screen
 
 GetScreenHeight()
   - returns the height of the engine screen


   *** graphic primitives ***
   NOTE: Make sure to use FlipScreen() when you're done drawing


   Point(x, y, color)
     - plots a point onto the video buffer at (x, y) with the color
   
   Line(x1, y1, x2, y2, color)
     - draws a line from (x1, y1) to (x2, y2) with the color
   
   GradientLine(x1, y1, x2, y2, color1, color2)
     - Draws a line from (x1, y1) to (x2, y2) with a color fade from color1 
       to color2
   
   Triangle(x1, y1, x2, y2, x3, y3, c)
     - Draws a filled triangle with the points (x1, y1), (x2, y2), (x3, y3), 
       with the color c
   
   GradientTriangle(x1, y1, x2, y2, x3, y3, c1, c2, c3)
     - Draws a gradient triangle with the points (x1, y1), (x2, y2), (x3, y3),
       with each point (c1 = color of (x1, y1), c2 = color of (x2, y2), c3 = color
       of (x3, y3)) having a color to generate the gradient of the triangle
   
   Rectangle(x, y, w, h, c)
     - Draws a rectangle at (x, y) of width w and height h, filled with color c.
   
   GradientRectangle(x, y, w, h, c_ul, c_ur, c_lr, c_ll)
     - Draws a gradient rectangle at (x,y) with the height h and width w.
       Each corner of a rectangle (c_ul = color of upper left corner, 
       c_ur = color of upper right corner, c_lr = color of lower right corner,
       c_ll = color of lower left corner) accepts a color information to 
       generate the gradient of the rectangle.


 *** input ***


   *** keyboard ***
   AreKeysLeft()
     - returns true or false depending if the there are keys from the key 
       input queue.
   
   GetKey()
     - returns the first key in the queue. If there are no keys in the queue,
       Sphere will wait until there is a key in the queue.
   
   IsKeyPressed(key)
     - checks if the key has been pressed. Returns true if 'key' is
   pressed....
   IsAnyKeyPressed()
     - checks if any key is pressed at the time.
   GetKeyString(key, shift)
     - converts the key into a string, KEY_A will become "a", etc.
     - if shift is true, returns uppercase/special value of key
     - control keys return ""


   *** mouse ***
   SetMousePosition(x, y)
     - Sets the x and y of the mouse cursor
   
   GetMouseX()
   GetMouseY()
     - returns the location of the mouse cursor within the engine screen
   
   IsMouseButtonPressed(button)
     - returns true if the button is pressed
       allowed button values are: MOUSE_LEFT, MOUSE_RIGHT, MOUSE_MIDDLE


   *** joystick ***
   GetNumJoysticks()
     - returns the number of joysticks available on the system
   GetJoystickX(joy)
   GetJoystickY(joy)
     - returns the current joystick position in normalized
       coordinates from -1 to 1 on both axes.
   GetNumJoystickButtons(joy)
     - returns the number of buttons available on this joystick
   IsJoystickButtonPressed(joy, button)
     - returns true if the button on joystick 'joy' is pressed


 *** time ***
 GetTime()
   - returns the number of milliseconds since some arbitrary time.
     ex:
      var start = GetTime();
      while (GetTime() < start + 1000) {}
 *** MapEngine object ***
 GetMapEngine()
   - returns the mapengine object currently being used by the map engine.
  
 mapengine_object.save(filename)
   - saves the map to filename


 *** ByteArray object ***
 ByteArrays are pretty much only used for networking (see below for Network 
 stuff) or RawFiles (also below)
 
 CreateByteArray(size)
   - returns a ByteArray object of 'size' bytes
 
 CreateByteArrayFromString(string)
   - returns a ByteArray object from string 'string'
 
 CreateStringFromByteArray(array)
   - returns a string from a ByteArray
 bytearray.length
   - the length of the byte array
 
 bytearray_object[index]
   - returns the allows you to access the index in the array
 bytearray.concat(bytearray_to_append)
   - returns bytearray with bytearray_to_append attached to the end of it
 bytearray.slice(start [, end])
   - returns a slice of the bytearray starting at start, and ending at end
     or the end of the bytearray if end is omitted.
     If end is a negative number, the end point is started from the end of the bytearray.
   *** MD5 fingerprinting ByteArray objects ***
   HashByteArray(byte_array)
     - generates an MD5 fingerprint as a hexadecimal string whose output
       is the same as the RSA reference implementation of RFC 1321 which
       means that the unix md5 command will return the same string for the
       identical input.  The resulting string contains the hexadecimal
       representation of the MD5 fingerprint for the specified byte
       array object
 *** networking ***
 GetLocalName()
   - returns a string with the local name of your computer
 
 GetLocalAddress()
   - returns a string with the IP address of your computer
 
 OpenAddress(address, port)
   - attempts to open a connection to the computer specified with 'address' on 'port'
     returns a socket object

 ListenOnPort(port)
   - listens for connections on port, returns a socket object if successful
 
 socket.isConnected()
   - returns true if the socket is connected

 socket.getPendingReadSize()
   - returns the size of the next array to be read in the socket
 
 socket.write(byte_array)
   - writes a ByteArray object into the socket
 
 socket.read(int size) 
   - reads from the socket, returns a ByteArray object
 socket.close()
   - closes the socket object, after this, the socket cannot be used.


      • sphere objects ***


 *** colors ***
 CreateColor(r, g, b [, a])
   - returns a color object with the color r is Red, g is Green, b is Blue,
     and a is alpha (translucency of the color). 
     Note + alpha of 0 = transparent, alpha of 255 = opaque
          + alpha is optional, and defaults to 255 if not specified
 
 BlendColors(c1, c2)
   - returns a color object that is the blended color of color c1 and c2
 
 BlendColorsWeighted(c1, c2, c1_weight, c2_weight)
   - blends two colors together, allowing you to specify the amount of each color
     ex:
     BlendColorsWeighted(a, b, 1, 1) // equal amounts (like BlendColors())
     BlendColorsWeighted(a, b, 1, 2) // 33% a, 66% b
 
 color_object.red
   - the red component of a color object
 
 color_object.green
   - the green component of a color object
 
 color_object.blue
   - the blue component of a color object
 
 color_object.alpha
   - the alpha (translucency) component of a color object
 
 + all color components are from 0-255 (unsigned 8-bits each, 4x8bit == 32bit)


 /* maps */
 
 MapEngine(map, fps)
   - starts the map engine with the map specified and runs at 'fps' frames per second
 
 ChangeMap(map)  
   - changes current map
   
 GetCurrentMap()
   - Returns the current map, e.g. "noisyforest.rmp"
   
 ExitMapEngine()
   - Exits the map engine.  Note:  This tells the map engine to shut
     down.  This does not mean the engine shuts down immediately.  You
     must wait for the original call to MapEngine() to return before you
     can start a new map engine.
 IsMapEngineRunning()
   - Returns true if the map engine is running, false if not
 UpdateMapEngine()
   - updates map engine (state of entities, color masks, etc.)
 SetMapEngineFrameRate(fps)
   - Sets the max frame rate (in frames per second) that the map engine will go at
 GetMapEngineFrameRate()
   - Returns the current map engine frames per second rate set by either MapEngine(map, fps) or SetMapEngineFrameRate(fps)
 
 CallMapScript(which)
   - calls a map's script from code
   the six events are:
     SCRIPT_ON_ENTER_MAP
     SCRIPT_ON_LEAVE_MAP
     SCRIPT_ON_LEAVE_MAP_NORTH
     SCRIPT_ON_LEAVE_MAP_EAST
     SCRIPT_ON_LEAVE_MAP_SOUTH
     SCRIPT_ON_LEAVE_MAP_WEST
 
 SetDefaultMapScript(which, script)
   - set the default script that the map engine should call before calling the map's specific script
   (The default map script is called, then the map specific script is called.)
   The events are the same from CallMapScript.
   The map engine doesn't have to be on to set a default script.
 
 CallDefaultMapScript(which)
   - call the default map script
   The events are the same from CallMapScript.
   The map engine doesn't have to be on to call a default script.
 
   *** maps ***
   GetNumLayers()
     - get number of layers on map
     - in the following functions, layer 0 is the bottommost layer.
     - layer 1 is the next one up, etc.
   GetLayerName(layer_index)
     - returns the name of 'layer'
   GetLayerWidth(layer_index)
     - get width of 'layer'
   GetLayerHeight(layer_index)
     - get height of 'layer'
   IsLayerVisible(layer_index)
     - returns true if the layer is visible
   SetLayerVisible(layer_index, visible)
     - shows 'layer_index' if visible == true, and hides it if visible == false
     e.g. SetLayerVisible(0, !IsLayerVisisble(0)); will toggle layer zero's visibility
    IsLayerReflective(layer_index)
     - returns true if the layer is reflective
   SetLayerReflective(layer_index, reflective)
     - sets whether layer should be reflective
   SetLayerMask(layer_index, mask)
     - set the color mask of 'layer' to 'mask'
     e.g. SetLayerMask(0, CreateColor(255, 0, 0, 128)); will make the layer semi red
   GetLayerMask(layer_index)
     - get the color mask currently being used by 'layer'
   SetLayerScaleFactorX(layer_index, factor_x)
     - Sets the x zoom/scale factor for the layer 'layer_index' to 'factor_x'
       e.g. SetLayerScaleFactor(0, 0.5); will make the layer zoom out to half the normal size
   SetLayerScaleFactorY(layer_index, factor_y)
     - Sets the y zoom/scale factor for the layer 'layer_index' to 'factor_y'
       e.g. SetLayerScaleFactor(0, 2); will make the layer zoom in to twice the normal size
   GetLayerAngle(layer_index)
     - Gets the angle (in radians) for the layer 'layer_index'
       e.g. var angle = GetLayerAngle(0) will get the angle for the first layer
       An angle of 0.0 is not rotated at all.
   SetLayerAngle(layer_index, angle)
     - Sets the angle (in radians) for the layer 'layer_index' to 'angle'
       e.g. SetLayerAngle(0, Math.PI) will make the layer rotate slightly
   GetNumTiles()
     - return number of tiles in map
   SetTile(x, y, layer, tile)
     - changes tile on map to 'tile'
   GetTile(x, y, layer)
     - returns tile on map
   GetTileName(tile_index)
     - returns the name of the tile 'tile_index'
   GetTileWidth()
     - returns width in pixels of tiles on current map
   GetTileHeight()
     - returns height in pixels of tiles on current map
   GetTileImage(tile_index)
     - returns the image of the tile 'tile_index'
     
   SetTileImage(tile_index, image_object)
     - sets the tile 'tile_index' to the image 'image_object'
   GetTileSurface(tile_index)
     - returns the surface of the tile 'tile_index'
     
   SetTileSurface(tile_index, surface_object)
     - sets the tile 'tile_index' to the surface 'surface_object'
     
   GetTileDelay(tile)
     - gets the animation delay of the tile 'tile'
       If it returns 0, the tile is not animated
   SetTileDelay(tile, delay)
     - sets the animation delay of the tile 'tile' to 'delay'
       A delay of 0 is considered not animated
   GetNextAnimatedTile(tile)
     - gets the next tile in the animation sequence of 'tile'
       Note that if the return value is 'tile' the tile is not animated.
     
   SetNextAnimatedTile(tile, next_tile)
     - sets the next tile in the animation sequence of 'tile' to 'new_tile'
       SetNextAnimatedTile(tile, tile) turns off the tile animation for 'tile'
   ReplaceTilesOnLayer(layer, oldtile, newtile)
     - Replaces all 'oldtile' tiles with 'newtile' on layer 'layer'
     
   IsTriggerAt(map_x, map_y, layer)
     - Returns true if there is a trigger at map_x, map_y on layer.  map_x
       and map_y are in map (per-pixel) coordinates.
       (Currently the layer parameter is ignored, although it still must be valid.)
     
   ExecuteTrigger(map_x, map_y, layer)
     - activates the trigger positioned on map_x, map_y, layer if one exists.
       map_x and map_y are in map (per-pixel) coordinates.
       (Currently the layer parameter is ignored, although it still must be valid.)
   AreZonesAt(map_x, map_y, layer)
     - returns true if there are any zones at map_x, map_y on layer
       (Currently the layer parameter is ignored, although it still must be valid.)
   ExecuteZones(map_x, map_y, layer)
     - executes all the zones that map_x, map_y, layer is within
       map_x and map_y are in map (per-pixel) coordinates.
       (Currently the layer parameter is ignored, although it still must be valid.)
   GetNumZones()
     - returns the amount of zones that there is
   GetCurrentZone()
       - best when called from inside a ZoneScript handler
         it will return the index of the zone for which the current script 
         is running
     
   GetZoneX(zone)
     - gets the x value of zone 'zone'
   GetZoneY(zone)
     - gets the y value of zone 'zone'
   GetZoneWidth(zone)
     - gets the width value of zone 'zone'
   GetZoneHeight(zone)
     - gets the height value of zone 'zone'
   GetZoneLayer(zone)
     - gets the layer value of zone 'zone'
   SetZoneLayer(zone, layer)
     - sets the layer value of zone 'zone'
   ExecuteZoneScript(zone)
     - executes the script for the zone 'zone'
   RenderMap()
     - Renders the map into the video buffer
   SetColorMask(color, num_frames)
     - applies a color mask to things drawn by the map engine for 'num_frames' frames
   SetDelayScript(num_frames, script)
     - in 'num_frames' frames, runs 'script'
       ex: SetDelayScript(60, "ChangeMap('forest.rmp')");
       this tells the map engine to change to forest.rmp after 60 frames


   *** input ***
   BindKey(key, onkeydown, onkeyup)
     - runs the 'onkeydown' script when the 'key' is pressed down and runs 
       'onkeyup' when the 'key' is released
       ex: BindKey(KEY_SPACE, "mode = 'in';", "mode = 'out';");
           refer to keys.txt for a list of key names
   
   UnbindKey(key)
     - unbinds a bound key
   BindJoystickButton(joystick, button, onbuttondown, onbuttonup)
     - runs the 'onbuttondown' script when the joystick 'button' is pressed down and runs
       'onbuttonup' when the joystick 'button' is released
   UnbindJoystickButton(joystick, button)
     - unbinds a bound joystick button
   AttachInput(person_entity)
     - makes the 'person_entity' respond to the input 
       (up = KEY_UP, down = KEY_DOWN, left = KEY_LEFT, right = KEY_RIGHT)
   
   DetachInput()
     - releases input from the attached person entity
   
   IsInputAttached()
     - returns true if a person is attached to the input
   
   GetInputPerson()
     - returns a string with the name of the person who currently holds input
   AttachPlayerInput(person_entity, player_index)
     - makes the 'person_entity' respond to the input
       Currenty player_index has to be from zero to four (max four players)
       Note: AttachInput is equilivent to AttachPlayerInput(person_entity, 0)
     
   DetachPlayerInput(person_entity)
     - releases input from the attached person entity
   SetUpdateScript(script)
   // calls 'script' after each frame (don't draw stuff in here!)
   SetRenderScript(script)
   // calls 'script' after all map layers are rendered
   SetLayerRenderer(layer, script)
     - calls the rendering 'script' after 'layer' has been rendered. Only one
       rendering script can be used for each layer of the map


   *** camera ***
   AttachCamera(person_name)
     - Attaches the camera view to specified person
   
   DetachCamera()
     - Detaches camera so it can be controlled directly
   
   IsCameraAttached()
     - returns true if the camera is attached to a person, false if the
       camera is floating
   
   GetCameraPerson()
     - returns a string with the name of the person whom the camera 
       is attached to
   SetCameraX(x)
   SetCameraY(y)
     - sets the location of the camera object on the map (the center
       of the screen if possible)
   
   GetCameraX()
   GetCameraY()
     - returns the location of the camera object on the map (the center
       of the screen if possible)
   MapToScreenX(layer, x)
   MapToScreenY(layer, y)
     - returns screen coordinates of position on map
   ScreenToMapX(layer, x)
   ScreenToMapY(layer, y)
     - returns map coordinates of position on screen


   *** entities ***


     *** persons ***
     GetPersonList()
       - returns an array of strings representing the current person entities
     CreatePerson(name, spriteset, destroy_with_map)
       - returns a person object with 'name' from 'spriteset'. If Sphere is 
         unable to open the file, the engine will give an error message and 
         exit. destroy_with_map is a boolean (true/false value), which the 
         spriteset is destroyed when the current map is changed if the flag 
         is set to true.
     
     DestroyPerson(name)
       - destroys the person with the name
     SetPersonX(name, x)
     SetPersonY(name, y)
     SetPersonLayer(name, layer)
       - sets the position of the person on the map
     SetPersonXYFloat(name, x, y)
       - sets the position of the person with floating point accuracy
     
     SetPersonDirection(name, direction)
     SetPersonFrame(name, frame)
       - sets which frame from which direction to display
     
     GetPersonX(name)
     GetPersonY(name)
     GetPersonLayer(name)
       - Gets the position of the person on the map.
         The position is based on the middle of the spriteset's base
         rectangle.
     GetPersonXFloat(name)
     GetPersonYFloat(name)
       - Gets the position of the person on the map in floating point 
         accuracy.
     
     GetPersonDirection(name)
     GetPersonFrame(name)
       - gets the frame and direction that are currently being displayed
     SetPersonSpeed(name, speed)
     SetPersonSpeedXY(name, speed_x, speed_y)

- sets the speed at which a person moves at

     GetPersonSpeedX(name)
     GetPersonSpeedY(name)
       - gets the speed at which a person moves at
     SetPersonFrameRevert(name, delay)

- sets the delay between when the person last moved and returning to

         first frame. The delay is in frames. 0 disables this behaviour.
     GetPersonFrameRevert(name)

- gets the delay between when the person last moved and returning to

         first frame.  The delay is in frames. 0 disables this behaviour.
     SetPersonScaleFactor(name, scale_w, scale_h)
       - rescales the sprite to a certain scale specified by scale_w and scale_h.
         Scaling is determined by floating point numbers like, 1.5 would scale
         the person to 1.5 times its normal size based on his original sprite
         size.
     SetPersonScaleAbsolute(name, width, height)
       - rescales the sprite to width pixels and height pixels.
     GetPersonSpriteset(name)
       - returns the person's spriteset.
     SetPersonSpriteset(name, spriteset)
       - set's the person's spriteset to spriteset
       e.g. SetPersonSpriteset("Jimmy", LoadSpriteset("jimmy.running.rss"));
     GetPersonBase(name)
       - returns the person's base obstruction object.
     GetPersonAngle(name)
       - returns the person's angle that is used
     SetPersonAngle(name, angle)
       - sets the angle which the person should be drawn at
       Note:
         Zero is no rotation, and angles are in radians.
         It does not rotate the spritesets obstruction base.
     SetPersonMask(name, color)
       - sets a color multiplier to use when drawing sprites.  if the color is
         RGBA:(255, 0, 0, 255), only the red elements of the sprite are drawn.
         If the color is RGBA:(255, 255, 255, 128), the sprite is drawn at
         half transparency.
     GetPersonMask(name)
       - returns the person's current mask
     IsPersonVisible(name)
       - returns the person's visible status 
       
     SetPersonVisible(name, visible)
       - sets the person's visible status, true = visible, false = not visible
       e.g. SetPersonVisible(GetCurrentPerson(), !IsPersonVisible(GetCurrentPerson()));
     GetPersonData(name)
       - gets a data object assiocated with the person 'name'
       There are certain default properties/values filled in by the engine, they are:
       num_frames - the number of frames for the person's current direction
       num_directions - the number of directions for the person
       width - the width of the spriteset's current frame
       height - the height of the spriteset's current frame
       leader - the person that this person is following, or "" if no-one...
       Any other properties are free for you to fill with values
       e.g. var data = GetPersonData("Jimmy");
       var num_frames = data["num_frames"];
     SetPersonData(name, data)
       - sets the 'data' object assiocated with the person 'name'
       e.g.
       var data = GetPersonData("Jimmy");
       data["talked_to_jimmy"] = true;
       SetPersonData("Jimmy", data);
     SetPersonValue(name, key, value)
       - SetPersonValue("Jimmy", "talked_to_jimmy", true); // same as code above
     GetPersonValue(name, key)
       - GetPersonValue("Jimmy", "num_frames"); // same as previous code above
     FollowPerson(name, leader, pixels)
       - makes the sprite 'name' follow 'pixels' pixels behind sprite 'leader'.
       If this function is called like:
       FollowPerson(name, "", 0),
       the person will detach from anyone it is following.
     
     SetPersonScript(name, which, script)
       - sets 'script' as the thing 'name' does in a certain event
         the five events are
         SCRIPT_ON_CREATE
         SCRIPT_ON_DESTROY
         SCRIPT_ON_ACTIVATE_TOUCH
         SCRIPT_ON_ACTIVATE_TALK
         SCRIPT_COMMAND_GENERATOR
         (SCRIPT_COMMAND_GENERATOR will be called when the command queue for
          the person runs out (for random movement thingies, etc))
     
     CallPersonScript(name, which)
       - calls a person's script from code
        'which' constants are the same as for SetPersonScript()
     
     GetCurrentPerson()
       - best when called from inside a PersonScript handler
         it will return the name of the person for whom the current script 
         is running
     QueuePersonCommand(name, command, immediate)
       - adds a command to the person's command queue
         the commands are:
           COMMAND_WAIT
           COMMAND_ANIMATE
           COMMAND_FACE_NORTH
           COMMAND_FACE_NORTHEAST
           COMMAND_FACE_EAST
           COMMAND_FACE_SOUTHEAST
           COMMAND_FACE_SOUTH
           COMMAND_FACE_SOUTHWEST
           COMMAND_FACE_WEST
           COMMAND_FACE_NORTHWEST
           COMMAND_MOVE_NORTH
           COMMAND_MOVE_EAST
           COMMAND_MOVE_SOUTH
           COMMAND_MOVE_WEST
         (note: these *might* change in a future release
         'immediate', if true, will execute the command go right away
         if false, it will wait until the next frame)
     
     QueuePersonScript(name, script, immediate)
       - adds a script command to the person's queue
     
     ClearPersonCommands(name)
       - clears the command queue of sprite with the 'name'
     IsCommandQueueEmpty(name)
       - returns true if the person 'name' has an empty command queue
     IsPersonObstructed(name, x, y)
     // returns true if person 'name' would be obstructed at (x, y)
     GetObstructingTile(name, x, y)
     // returns -1 if name isn't obstructed by a tile at x, y,
      - returns the tile index of the tile if name is obstructed at x, y
     GetObstructingPerson(name, x, y)
     // returns "" if name isn't obstructed by person at x, y,
      - returns the name of the person if name is obstructed at x, y
     IgnorePersonObstructions(person, ignore)
      - Sets whether 'person' should ignore other spriteset bases
     IsIgnoringPersonObstructions(person)
      - Returns true if 'person' is ignoring person obstructions, else false
      
     IgnoreTileObstructions(person, ignore)
      - Sets whether 'person' should ignore tile obstructions
     IsIgnoringTileObstructions(person)
      - Returns true if 'person' is ignoring tile obstructions, else false
     GetPersonIgnoreList(person)
      - Returns a list of people that 'name' is ignoring
     SetPersonIgnoreList(person, ignore_list)
      - Tells 'person' to ignore everyone in ignore_list
      e.g. SetPersonIgnoreList("White-Bomberman", ["bomb", "powerup"]);
      Tells White-Bomberman to not be obstructed by bombs or powerups
     SetTalkActivationKey(key)
     GetTalkActivationKey()
       - set key used to activate talk scripts
     SetTalkDistance(pixels)
     GetTalkDistance()
       - set distance to check for talk script activation


 *** spritesets ***
 LoadSpriteset(filename)
   - returns a spriteset object from 'filename'. If Sphere is unable to open
     the file, the engine will give an error message and exit.
  spriteset.filename
    - the filename that the spriteset was loaded with
  spriteset.save(filename)
    - saves the spriteset object to 'filename'
  spriteset.clone()
    - returns a copy of the spriteset object
  spriteset_object.images
    - array of image objects
  spriteset_object.directions
    - array of spriteset_direction objects
  spriteset_object.base
    - spriteset_base object
 // spriteset_direction objects
 spriteset_direction.name
   - name of direction
 spriteset_direction.frames
   - array of spriteset_frame objects
 
 // spriteset_frame objects
 spriteset_frame.index
   - index into images array
 spriteset_frame.delay
   - number of frames before animation should switch
 // spriteset_base object
 base.x1 }
 base.y1 } the coordinates of the base rectangle
 base.x2 }
 base.y2 }


 *** sounds ***
 LoadSound(filename [, streaming])
   - returns a sound object from 'filename'. If Sphere is unable to open
     the file, the engine will give an error message and exit.  If the optional
     argument 'streaming' is true or unspecified, the sound is streamed from the
     hard drive.  Otherwise, it's loaded into memory.
 
 sound_object.play(repeat)
   - plays the sound. repeat is a boolean (true/false), that indicates if 
     the sound should be looped
 
 sound_object.pause()
   - pauses playback. call play() again to resume playback.
 sound_object.stop()
   - stops playback
 
 sound_object.setVolume(volume)
   - sets the volume for the sound (0-255)
 
 sound_object.getVolume()
   - returns the sound's volume (0-255)
 sound_object.setPan(pan)
   - pan can be from -255 to 255.  -255 = left, 255 = right
 sound_object.getPan()
   - returns the current pan of the sound
 sound_object.setPitch(pitch)
   - pitch ranges from 0.5 to 2.0.  0.5 is an octave down (and half as fast)
     while 2.0 is an octave up (and twice as fast).  pitch defaults to 1
 sound_object.getPitch()
   - returns the current pitch
 sound_object.isPlaying()
   - returns true if the sound is currently playing
 sound_object.isSeekable()
   - returns true if the sound is seekable
     Not all sound types are seekable, Ogg is.
 sound_object.getPosition()
   - returns the position of the sound
     returns zero if the sound isn't seekable
 sound_object.setPosition(pos)
   - sets the position of the sound
     if the sound isn't seekable, this does nothing
 sound_object.getLength()
   - gets the length of the sound
 *** fonts ***
 GetSystemFont()
   - returns a font object of the font that the engine currently uses.
 
 LoadFont(filename)
   - returns a font object from 'filename'. If Sphere is unable to open 
     the file, the engine will give an error message and exit.
 
 font_object.setColorMask(color)
   - Sets the color mask for a font (see ApplyColorMask)
 
 font_object.getColorMask()
   - Gets the color mask being used by the font object
 
 font_object.drawText(x, y, text)
   - draws 'text' at x, y with the font
 font_object.drawZoomedText(x, y, scale, text)
   - draws scaled text (1.0 = normal) with (x,y) as the upper left corner
 
 font_object.drawTextBox(x, y, w, h, offset, text)
   - draws a word-wrapped text at (x, y) with the width w and height h. The
     offset is the number of pixels which the number of pixels from y which 
     the actual drawing starts at.
   Note: 'text' can have the following special characters within it:
     \n - newline
     \t - tab
     \" - double quote
     \' - single quote
 
    For example: font_object.drawTextBox(16, 16, 200, 200, 0, "Line One\nLine Two");
 
 font_object.getHeight()
   - returns the height of the font, in pixels
 
 font_object.getStringWidth(string)
   - returns the width of a given string, in pixels
 font_object.getStringHeight(string, width)
   - returns the height of the string as if it was drawn by drawTextBox
 font_object.clone()
   - returns a copy of 'font_object'
 *** window styles ***
 GetSystemWindowStyle()
   - returns a windowstyle object of the windowstyle that the engine currently
     uses.
 
 LoadWindowStyle(filename)
   - returns a windowstyle object from 'filename'. If Sphere is unable to open
     the file, the engine will give an error message and exit.
 
 windowstyle_object.drawWindow(x, y, w, h)
   - draws the window at (x, y) with the width and height of w and h.
     Note that window corners and edges are drawn outside of the width 
     and height of the window.
  windowstyle_object.setColorMask(color)
   - sets the color mask for a windowstyle (see ApplyColorMask)
 windowstyle_object.getColorMask()
   - gets the color mask being used by the windowstyle object


 *** images ***
 GetSystemArrow()
   - returns an image object of the System Arrow that the engine currently uses.
 
 GetSystemUpArrow()
   - returns an image object of the System Arrow(up) that the engine currently
     uses.
 
 GetSystemDownArrow()
   - returns an image object of the System Arrow(down) that the engine 
     currently uses.
 
 LoadImage(filename)
   - returns an image object from 'filename'. If Sphere is unable to open or 
     read the image, the engine will give an error message and exit. The 
     image type that the engine supports are either PCX, BMP, JPG, and PNG.
 
 GrabImage(x, y, w, h)
   - returns an image object from a section of the video buffer 
     defined by the parameters
     (see GrabSurface)
 
 image_object.blit(x, y)
   - draws the image onto the video buffer at x,y
 
 image_object.blitMask(x, y, mask)
   - draws the image into the video buffer, except that the color passed
     as 'mask' tints the image
 
 image_object.rotateBlit(x, y, radians)
   - draws the image into the video buffer, except that the image is rotates 
     in  anti-clockwise in radians, which have a range of 0-2*pi. 
     (x,y) is the center of the blit.
 image_object.rotateBlitMask(x, y, radians, color)
   - rotateBlit + mask
 
 image_object.zoomBlit(x, y, factor)
   - draws the image into the video buffer with zooming, with the scaling 
     depending on factor. Normally a factor of 1 will blit a normal looking
     image. Between 0 and 1 will shrink the image. Any values greater than 1
     will stretch the size of the image.
 image_object.zoomBlitMask(x, y, factor, color)
   - zoomBlit + mask
 
 image_object.transformBlit(x1, y1, x2, y2, x3, y3, x4, y4)
   - draws the image into the video buffer with "transformation", where 
     (x1, y1) is the upper left corner, (x2, y2) the upper right corner, 
     (x3, y3) is the lower right corner, and (x4, y4) is the lower left 
     corner.
 image_object.transformBlitMask(x1, y1, x2, y2, x3, y3, x4, y4, mask)
   - transformBlit + blitMask
 image_object.createSurface()
   - returns a new surface object from the image
 
 image_object.width
   - the width of the image
 
 image_object.height
   - the height of the image
 
 
 *** surfaces ***
 CreateSurface(width, height, color)
   - returns a surface object with width x height, filled with color
 
 LoadSurface(filename)
   - returns a surface object with an image with the 'filename'
 
 GrabSurface(x, y, w, h)
  - returns a surface object captured from an area of the video buffer, 
    at (x, y) with the width w and height h.
    (see GrabImage)
 surface_object.width
 surface_object.height
   - dimensions
 surface_object.applyLookup(x, y, w, h, red_lookup, green_lookup, blue_lookup, alpha_lookup);
   - Apply a lookup table transformation to the pixels contained in x, y, w, h
   The lookup parameters are arrays of 256 elements containg the new pixel values.
   e.g. var invert_lookup = [255, 254, 253, 252, 251, ..., 4, 3, 2, 1, 0];
 
 surface_object.applyColorFX(x, y, w, h,  colormatrix)

- Apply the colormatrix to the pixels contained in x, y, w, h (see CreateColorMatrix)

 surface_object.applyColorFX4(x, y, w, h,  cm_upperleft, cm_upperright, cm_lowerleft, cm_lowerright)
   - Apply 4 color matrixes. Each corner has a seperate color matrix.

(see CreateColorMatrix)

 surface_object.blit(x, y)
   - draws the surface to the video buffer at (x,y)
 
 surface_object.blitSurface(surface, x, y)
   - draws 'surface' onto 'surface_object' at (x,y)
 
 surface_object.createImage()
   - returns an image object from the surface object
 
 surface_object.setBlendMode(mode)
   - pass it with either BLEND or REPLACE
     REPLACE mode will make the surface erase the pixels needed when doing a 
             drawing operation (setpixel, line, rectangle...)
     BLEND will blend the pixels needed when doing a drawing operation
 
 surface_object.getPixel(x, y)
   - returns the color of the pixel at (x,y)
 
 surface_object.setPixel(x, y, color)
   - sets the pixel at (x,y) to 'color'
 
 surface_object.setAlpha(alpha)
   - sets the alpha of the surface
 surface_object.replaceColor(oldColor, newColor)
   - replace all pixels of the color oldColor in the surface with newColor
 
 surface_object.line(x1, y1, x2, y2, color)
   - draws a line onto the surface starting from (x1, y1) to (x2, y2) with 
     the color
 
 surface_object.rectangle(x, y, w, h, color)
   - draws a filled rectangle onto the surface from (x, y) to (x+w, y+h)
     with 'color'
     
 surface_object.triangle(x1, y1, x2, y2, x3, y3, color)
   - draws a filled triangle with the points (x1, y1), (x2, y2), (x3, y3), 
     with 'color'
 
 surface_object.rotate(radians, resize)
   - rotates the surface anti-clockwise with the range 0 - 2*pi. The resize 
     flag is a boolean to tell the engine to resize the surface if needed
     to accomodate the rotated image.
 
 surface_object.resize(w, h)
   - resizes the surface images. This does not stretch or shrink the image
     inside the surface.
 
 surface_object.rescale(w, h)
   - stretches or shrinks the surface to the new width w and height h
 
 surface_object.flipHorizontally()
   - flips the surface horizontally
 
 surface_object.flipVertically()
   - flips the surface vertically
 
 surface_object.clone()
   - returns a surface object, which is a copy of this surface object
 
 surface_object.cloneSection(x, y, w, h)
   - returns a new surface object with the height and width of h and w, with
     part of image at (x,y) from the surface_object with the width w and 
     height h.
  surface_object.drawText(font, x, y, text)
   - draws 'text' at x, y with the font onto the surface_object
 surface_object.drawZoomedText(font, x, y, scale, text)
   - draws scaled text (1.0 = normal) with (x,y) as the upper left corner
     onto the surface_object
 
 surface_object.drawTextBox(font, x, y, w, h, offset, text)
   - draws a word-wrapped text at (x, y) onto the surface_object with the width w and height h.
     The offset is the number of pixels which the number of pixels from y which 
     the actual drawing starts at. 
     See font_object.drawTextBox for more detail.
 surface_object.save(filename)
   - saves the surface_object as an image using the filename 'filename'
     the image type is determined by the extension of the file
     e.g. surface.save("test.png") saves a png image called test.png
 *** color matrix ***
 CreateColorMatrix(rn, rr, rg, rb,  gn, gr, gg, gb,  bn, br, bg, bb)
   - Creates a colormatrix that is used to transform the colors 

contained in a pixel with the following formula:

       newcolor.red   = rn + (rr * oldcolor.red + rg * oldcolor.green + rb * oldcolor.blue) / 255;
       newcolor.green = gn + (gr * oldcolor.red + gg * oldcolor.green + gb * oldcolor.blue) / 255;
       newcolor.blue  = bn + (br * oldcolor.red + bg * oldcolor.green + bb * oldcolor.blue) / 255;
     (see applyColorFX and applyColorFX4)


 *** animations ***
 LoadAnimation(filename)
   - Returns an animation object with the filename. If Sphere is unable to 
     open the file, the engine will give an error message and exit. Sphere 
     supports animation formats of .flic, .fli, .flc and .mng
 
 animation_object.width
   - returns the width of the animation
 
 animation_object.height
   - returns that height of the animation
 
 animation_object.getNumFrames()
   - returns the number of frames the animation contains.  If the
     animation is an MNG file, the number of frames is unknown, and
     this function returns 0.
 
 animation_object.getDelay()
   - returns the delay between frames, in milliseconds
 
 animation_object.readNextFrame()
   - readies the next frame for drawing
 
 animation_object.drawFrame(x, y)
   - draws the current frame into the video buffer
 animation_object.drawZoomedFrame(x, y, scale);
   - draws the current frame into the video buffer with a specified
     zoom scale


 *** files ***
 GetFileList(directory)
   - directory = directory in which to enumerate files, "save" if not specified
   - returns an array of strings, which contains the filenames that resides
     in the 'directory' directory of the game.
 
 OpenFile(filename)
   - returns a file object with the filename. The file is created/loaded 
     from the "save" directory of the game. Note that any changes in the keys
     will not be saved until the file object is destroyed.
 
 file_object.read(key, default)
   - reads a value from the key
     the value type returned depends on the default value. 
     + if the default is a number, read will return a number.
     + if the default is a text or string, read will return a string.
     + if the default is a boolean, read will return a boolean
     + if the key is not present in the file, it will return the default value.
 
 file_object.write(key, value)
   - writes a value (string, number, boolean) to the file under the key name
 file_object.getNumKeys()
   - returns the number of keys in the file
 file_object.getKey(index)
   - returns a string of the key at 'index'
 file_object.flush()
   - writes the file to disk immediately...  this way you don't have
     to wait for it to save when the file object is garbage collected


 *** raw files ***
 OpenRawFile(filename [, writeable])
   - opens a file with the filename.
     Unless writeable is true, the file *must* exist and reside
     in the "other" directory of the game otherwise Sphere will give an error. 
     If the file is opened successfully, the function will return a rawfile
     object. If the optional argument 'writeable' is true,
     the conents of the file will be destroyed,
     and you will be able to write to the file.
   
 rawfile_object.setPosition(position)
   - sets the position that the file will be read from
 
 rawfile_object.getPosition()
   - returns the current position which the data is read from
 
 rawfile_object.getSize()
   - returns the number of bytes in the file
 
 rawfile_object.read(num_bytes)
   - reads the number of bytes that is specified by num_bytes. It will create
     and return an array of data the rawfile object has read. The array of 
     data are numbers representation of each byte (0-255). Note that if the 
     number of bytes that will be read, exceeds the filesize from the current 
     position, it will only return an array of data of that is
     actually read.  The returned object is a ByteArray, so you can do
     the same things with it as you can with any other ByteArray.
 rawfile_object.write(byte_array)
   - writes the byte array to the file at the current position
     The file must have been opened as writeable for this to work.
     
 rawfile_object.close()
   - closes the rawfile object, after this, the rawfile_object cannot be used anymore.
   *** MD5 fingerprinting rawfiles ***
   HashFromFile(filename)
     - generates an MD5 of the specified raw file, which, by backtracking
       with a ../ may refer to any file within the game directory structure.
       The result is a 32 character string containing the hexadecimal
       representation of the resulting 128-bit MD5 fingerprint.  Identical
       files produce the same MD5 hash so it is an effective way to determine
       if a file has become corrupt or altered
      • 3d Functions ***
      • All 3d functions (currently) require sphere_gl to be used as the video driver ***

SwitchProjectMode(integer)

 - Sets the drawing mode to 2d if integer is 0, 3d if 1.  All 3d drawing
   must be done while in 3d mode, and likewise for 2d.  When done drawing
   in 3d, the mode must be set back to 2d.
 

PRenderMap()

 - Renders the map as a 3d image.  

image_object.transform3DBlit(x1, y1, z1, x2, y2, z2, x3, y3, z3, x4, y4, z4)

 - Blits the image to the coordinates given.  Point 1 is the upper left
   corner of the image, 2 is the upper right, 3 is the lower right,
   and 4 is the bottom left

image_object.triangle3DBlit(sx1,sy1,x1,y1,z1,sx2,sy2,x2,y2,z2,sx3,sy3,x3,y3,z3)

 - Blits the triangle (sx1, sy1) (sx2, sy2) (sx3, sy3) part of the image, given
   in terms of the image size, to the 3 points (x1,y1,z1) (x2,y2,z2) (x3,y3,z3) 
   respectively.

Set3DCameraPosition(x,y,z)

 - Sets the 3d camera to the point (x,y,z).

Set3DCameraAngles(x_angle, y_angle, z_angle)

 - Sets the 3d camera angles to x_angle, y_angle, and z_angle, with respect
   to the corresponding x,y, and z axis.  Input is given in terms of degrees.

Get3DCameraX()

 - Returns the cameras current x position.

Get3DCameraY()

 - Returns the cameras current y position.

Get3DCameraZ()

 - Returns the cameras current z position.

Get3DCameraAngleX()

 - Returns the cameras current x angle.

Get3DCameraAngleY()

 - Returns the cameras current y angle.

Get3DCameraAngleZ()

 - Returns the cameras current z angle.